portfolio/STAGING_SETUP.md

🚀 Staging Environment Setup

Overview

You now have two separate Docker stacks:

1. Staging - Deploys automatically on dev or main branch

   • Port: 3001
   • Container: portfolio-app-staging
   • Database: portfolio_staging_db (port 5433)
   • Redis: portfolio-redis-staging (port 6380)
   • URL: https://staging.dk0.dev (or http://localhost:3001)

2. Production - Deploys automatically on production branch

   • Port: 3000
   • Container: portfolio-app
   • Database: portfolio_db (port 5432)
   • Redis: portfolio-redis (port 6379)
   • URL: https://dk0.dev

How It Works

Automatic Staging Deployment

When you push to dev or main branch:

1. ✅ Tests run
2. ✅ Docker image is built and tagged as staging
3. ✅ Staging stack deploys automatically
4. ✅ Available on port 3001

Automatic Production Deployment

When you merge to production branch:

1. ✅ Tests run
2. ✅ Docker image is built and tagged as production
3. ✅ Zero-downtime deployment (blue-green)
4. ✅ Health checks before switching
5. ✅ Rollback if health check fails
6. ✅ Available on port 3000

Safety Features

Production Deployment Safety

• ✅ Zero-downtime: New container starts before old one stops
• ✅ Health checks: Verifies new container is healthy before switching
• ✅ Automatic rollback: If health check fails, old container stays running
• ✅ Separate networks: Staging and production are completely isolated
• ✅ Different ports: No port conflicts
• ✅ Separate databases: Staging data doesn't affect production

Staging Deployment

• ✅ Non-blocking: Staging can fail without affecting production
• ✅ Isolated: Completely separate from production
• ✅ Safe to test: Break staging without breaking production

Ports Used

Service	Staging	Production
App	3001	3000
PostgreSQL	5433	5432
Redis	6380	6379

Workflow

Development Flow

# 1. Work on dev branch
git checkout dev
# ... make changes ...

# 2. Push to dev (triggers staging deployment)
git push origin dev
# → Staging deploys automatically on port 3001

# 3. Test staging
curl http://localhost:3001/api/health

# 4. Merge to main (also triggers staging)
git checkout main
git merge dev
git push origin main
# → Staging updates automatically

# 5. When ready, merge to production
git checkout production
git merge main
git push origin production
# → Production deploys with zero-downtime

Manual Commands

Staging

# Start staging
docker compose -f docker-compose.staging.yml up -d

# Stop staging
docker compose -f docker-compose.staging.yml down

# View staging logs
docker compose -f docker-compose.staging.yml logs -f

# Check staging health
curl http://localhost:3001/api/health

Production

# Start production
docker compose -f docker-compose.production.yml up -d

# Stop production
docker compose -f docker-compose.production.yml down

# View production logs
docker compose -f docker-compose.production.yml logs -f

# Check production health
curl http://localhost:3000/api/health

Environment Variables

Staging

• NODE_ENV=staging
• NEXT_PUBLIC_BASE_URL=https://staging.dk0.dev
• LOG_LEVEL=debug (more verbose logging)

Production

• NODE_ENV=production
• NEXT_PUBLIC_BASE_URL=https://dk0.dev
• LOG_LEVEL=info

Database Separation

• Staging DB: portfolio_staging_db (separate volume)
• Production DB: portfolio_db (separate volume)
• No conflicts: Staging can be reset without affecting production

Monitoring

Check Both Environments

# Staging
curl http://localhost:3001/api/health

# Production
curl http://localhost:3000/api/health

View Container Status

# All containers
docker ps

# Staging only
docker ps | grep staging

# Production only
docker ps | grep -v staging

Troubleshooting

Staging Not Deploying

1. Check GitHub Actions workflow
2. Verify branch is dev or main
3. Check Docker logs: docker compose -f docker-compose.staging.yml logs

Production Deployment Issues

1. Check health endpoint before deployment
2. Verify old container is running
3. Check logs: docker compose -f docker-compose.production.yml logs
4. Manual rollback: Restart old container if needed

Port Conflicts

• Staging uses 3001, 5433, 6380
• Production uses 3000, 5432, 6379
• If conflicts occur, check what's using the ports:

  lsof -i :3001
  lsof -i :3000
  

Benefits

✅ Safe testing: Test on staging without risk ✅ Zero-downtime: Production updates don't interrupt service ✅ Isolation: Staging and production are completely separate ✅ Automatic: Deploys happen automatically on push ✅ Rollback: Automatic rollback if deployment fails

---

You're all set! Push to dev/main for staging, merge to production for production deployment! 🚀