Skip to content

DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
314 lines (231 loc) · 6.13 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

314 lines (231 loc) · 6.13 KB
Raw

🚀 Deployment Guide - Noted Application

Prerequisites

  • Docker & Docker Compose installed
  • Firebase project created
  • Google OAuth credentials (if using calendar integration)
  • Domain with SSL certificate (for production)

🔐 Pre-Deployment Checklist

1. Remove Secrets from Git History (IMPORTANT!)

If you've already committed .env files with secrets:

# Install git-filter-repo
pip install git-filter-repo

# Remove .env files from history
git-filter-repo --invert-paths --path .env --path backend/.env --path NoteFront/.env

# Force push (WARNING: affects all collaborators)
git push --force-all

2. Environment Setup

Copy example files and configure:

# Root directory
cp .env.example .env
cp backend/.env.example backend/.env
cp NoteFront/.env.example NoteFront/.env

Edit each .env file:

.env (Root - for docker-compose)

DB_USER=root
DB_PASSWORD=STRONG_PASSWORD_HERE  # Use: openssl rand -hex 16
DB_NAME=Note
VITE_BASE_URL_API=https://yourdomain.com  # For production

backend/.env

DB_HOST=mysql
DB_PORT=3306
DB_USER=root
DB_PASSWORD=STRONG_PASSWORD_HERE  # Same as above
DB_NAME=Note
PORT=8080
GIN_MODE=release
FIREBASE_CREDENTIALS_PATH=./firebase-credentials.json
ALLOWED_ORIGINS=https://yourdomain.com  # Add all allowed origins
JWT_SECRET=STRONG_JWT_SECRET  # Use: openssl rand -hex 32

NoteFront/.env

VITE_BASE_URL_API=https://yourdomain.com/api
VITE_FIREBASE_API_KEY=your_actual_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
# ... other Firebase config

3. Firebase Setup

  1. Go to Firebase Console
  2. Create/Select your project
  3. Download service account key:
    • Settings → Service Accounts → Generate new private key
    • Save as backend/firebase-credentials.json
  4. Copy web app config to NoteFront/.env

4. SSL Certificates

Development (Self-signed):

mkdir -p Nginx/https
openssl req -x509 -newkey rsa:4096 -keyout Nginx/https/private.key \
  -out Nginx/https/certificate.crt -days 365 -nodes

Production (Let's Encrypt):

# Use certbot to generate certificates
certbot certonly --standalone -d yourdomain.com

# Copy certificates to:
# /etc/letsencrypt/live/yourdomain.com/fullchain.pem → certificate.crt
# /etc/letsencrypt/live/yourdomain.com/privkey.pem → private.key

🐳 Docker Deployment

Build and Start

# Build images
docker-compose build

# Start services (detached mode)
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Specific service logs
docker-compose logs -f backend
docker-compose logs -f frontend

Health Check

# API Health
curl http://localhost:8080/api/health

# Full Status
docker-compose ps

Stop Services

# Graceful shutdown
docker-compose down

# With volume cleanup
docker-compose down -v

🔍 Debugging

Check Service Connectivity

# Bash into backend
docker-compose exec backend bash

# Test database connection
nc -zv mysql 3306

# Check environment variables
env | grep DB_

Database Issues

# Connect to MySQL
docker-compose exec mysql mysql -u root -p

# View created tables
USE Note;
SHOW TABLES;

# Check user auto-provisioning
SELECT * FROM users;

Frontend Issues

# Build logs
docker-compose logs frontend

# Rebuild frontend
docker-compose up --build frontend

📊 Production Deployment

1. Configure Nginx Domain

Edit Nginx/default.conf:

server_name yourdomain.com www.yourdomain.com;

2. Environment Variables

Set production values in .env:

  • Use strong passwords (20+ chars)
  • Set GIN_MODE=release
  • Add production domain to ALLOWED_ORIGINS
  • Generate new JWT_SECRET: openssl rand -hex 32

3. SSL/TLS

  • Install certificates in Nginx/https/
  • Ensure ssl_certificate paths match
  • Test SSL: https://yourdomain.com/api/health

4. Backup Strategy

# Backup MySQL data
docker-compose exec mysql mysqldump -u root -p Note > backup.sql

# Restore from backup
docker-compose exec -T mysql mysql -u root -p Note < backup.sql

5. Monitoring

# Monitor resource usage
docker stats

# Check error logs
docker-compose logs --tail=100

# Setup log rotation (add to docker-compose.yml)
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

🔐 Security Checklist

  • ✅ .env files not in git
  • ✅ Database password: 20+ characters
  • ✅ JWT secret: randomly generated
  • ✅ CORS origins: specific domains only
  • ✅ HTTPS enabled with valid certificates
  • ✅ Nginx security headers configured
  • ✅ Firebase credentials: service account only
  • ✅ No hardcoded secrets in code
  • ✅ API errors: don't expose schema details
  • ✅ Rate limiting: configured on auth endpoints

📝 Common Issues

Issue: "Connection refused" to MySQL

Solution: Ensure MySQL healthcheck passes

docker-compose logs mysql
docker-compose up mysql --detach  # Start MySQL first

Issue: CORS errors in browser

Solution: Update ALLOWED_ORIGINS in backend/.env

# Restart backend to apply
docker-compose restart backend

Issue: 401 Unauthorized on API calls

Solution: Verify Firebase credentials and JWT token

# Check backend logs
docker-compose logs backend | grep -i auth

🚀 Production Quick Start

# 1. Setup files
cp .env.example .env
cp backend/.env.example backend/.env
cp NoteFront/.env.example NoteFront/.env

# 2. Edit all three .env files with production values

# 3. Place Firebase credentials
# backend/firebase-credentials.json

# 4. Place SSL certificates
# Nginx/https/certificate.crt
# Nginx/https/private.key

# 5. Deploy
docker-compose build
docker-compose up -d

# 6. Verify
docker-compose ps
curl https://yourdomain.com/api/health

📞 Support

For issues, check:

  • Backend logs: docker-compose logs backend
  • Frontend logs: docker-compose logs frontend
  • Nginx logs: docker-compose logs nginx
  • MySQL logs: docker-compose logs mysql