Booking System Deployment Guide

This document describes the complete deployment process for the Booking system, covering both development and production environments.

Directory Structure

booking-deploy/
├── compose/                    # Docker Compose configuration files
│   ├── docker-compose.dev.yml     # Development environment orchestration
│   ├── docker-compose.prod.yml    # Production environment orchestration
│   ├── dev.compose.env.example    # Development environment variables template
│   └── prod.compose.env.example   # Production environment variables template
├── env/                       # Application environment variables
│   ├── dev/                   # Development environment
│   │   ├── backend.env.example
│   │   └── frontend.env.example
│   └── prod/                  # Production environment
│       ├── backend.env.example
│       └── frontend.env.example
└── scripts/                   # Deployment scripts
    ├── deploy-dev.sh          # Development environment deployment script
    ├── deploy-prod.sh         # Production environment deployment script
    └── verify-images.sh       # Image verification script

Environment Preparation

1. Docker and Docker Compose

• Docker Engine 20.10+ or Docker Desktop
• Docker Compose v2+ (recommended) or docker-compose v1.29+

2. Environment Variables Preparation

Development Environment

# Copy template files
cd booking-deploy

# Compose environment variables
cp compose/dev.compose.env.example compose/dev.compose.env
# Edit dev.compose.env to update Docker Hub image addresses if needed

# Application environment variables
cp env/dev/backend.env.example env/dev/backend.env
cp env/dev/frontend.env.example env/dev/frontend.env
# Edit .env files and set actual values (e.g., JWT_SECRET, etc.)

Production Environment

cd booking-deploy
cp compose/prod.compose.env.example compose/prod.compose.env
cp env/prod/backend.env.example env/prod/backend.env
cp env/prod/frontend.env.example env/prod/frontend.env

# Important: Production environment requires strong passwords and real secrets

Image Tagging Strategy

The Booking system's CI/CD pipeline automatically generates multiple types of Docker image tags, each with different purposes and reliability characteristics:

Tag Types

Tag Type	Format Example	Mutability	Recommended Use	Reliability
Branch Tags	dev, main	Mutable - Updated on every push	Rapid development, integration testing	Low - Not suitable for production
Commit Tags	dev-abc123, main-def456	Immutable - Tied to specific commits	Reliable deployment, rollback, auditing	High - Recommended for production
Semantic Version	v1.0.0, v1.2.3	Immutable - Versioned releases	Official releases, version management	Highest - Best practice for production
PR Tags	pr-123	Mutable - PR builds	PR verification, code review	Low - For temporary use only
latest	latest	Mutable - Latest from main branch	Development convenience	Low - Prohibited for production

Selection Guide

1. Development Environment:

   • Rapid iteration: Use dev branch tag
   • Reliable testing: Use dev-<commit-hash> commit tag

2. Production Environment:

   • Must use immutable tags: Commit tags or semantic version tags
   • Emergency fixes: Use main-<commit-hash>
   • Official releases: Use semantic versions like v1.0.0
   • Prohibited: main or latest tags

Image Verification

All images are verified with real deployment topology:

• ✅ Include PostgreSQL and Redis dependencies
• ✅ Run database migrations
• ✅ Verify health endpoint (/v1/health)
• ✅ Check database and Redis connection status
• ✅ Verify frontend accessibility

View Available Tags

Image tags are automatically generated by GitHub Actions workflows:

• Backend images: booking-backend/.github/workflows/backend-image.yml
• Frontend images: booking-frontend/.github/workflows/frontend-image.yml
• Migration images: Dedicated booking-backend-migration image

Rollback Operations

To rollback to a previous version:

1. Find the previous commit tag (e.g., main-abc123def)
2. Update image tags in prod.compose.env file
3. Re-run the deployment script

# Rollback to specific commit
BACKEND_IMAGE=docker.io/cho-geer/booking-backend:main-previous-commit
BACKEND_MIGRATION_IMAGE=docker.io/cho-geer/booking-backend-migration:main-previous-commit
FRONTEND_IMAGE=docker.io/cho-geer/booking-frontend:main-previous-commit

Deployment Process

Development Environment Deployment

# Enter booking-deploy directory
cd booking-deploy

# Run deployment script
./scripts/deploy-dev.sh

The deployment script performs the following steps:

1. Check for environment variable files existence
2. Pull latest images from Docker Hub
3. Execute database migrations (independent migration service)
4. Start all services (PostgreSQL, Redis, Backend, Frontend)
5. Health check to verify all services are available
   • Backend health endpoint: http://localhost:3001/v1/health
   • Backend Swagger: http://localhost:3001/api/docs
   • Frontend page: http://localhost:3000

Production Environment Deployment

cd booking-deploy
./scripts/deploy-prod.sh

The production environment deployment process is the same as development environment but uses different configurations:

• Different Docker Compose file (docker-compose.prod.yml)
• Different environment variable files (prod.compose.env, env/prod/)
• Possibly different network configurations and resource constraints

Service Architecture

Development Environment Services

Service	Image	Port	Description
PostgreSQL	postgres:16	5432	Main database
Redis	redis:7-alpine	6379	Cache and session storage
Backend	${BACKEND_IMAGE}	3001	NestJS API service
Frontend	${FRONTEND_IMAGE}	3000	Next.js frontend application
Migration	${BACKEND_MIGRATION_IMAGE}	-	Database migration service

Production Environment Differences

• May use external databases (e.g., RDS) instead of containerized PostgreSQL
• May use external Redis clusters
• May add load balancing and monitoring services
• Different resource constraints and restart policies

Database Migrations

Independent Migration Service

The deployment process includes an independent migration service to ensure:

1. Migrations execute before application startup
2. Deployment stops on failure to prevent applications from connecting to inconsistent databases
3. Idempotency: prisma migrate deploy can be safely executed repeatedly

Manual Migration Execution

# Development environment
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env run --rm migration

# Production environment
docker compose -f compose/docker-compose.prod.yml --env-file compose/prod.compose.env run --rm migration

Health Checks and Monitoring

Built-in Health Checks

• Backend: GET /v1/health - Returns application, database, and Redis status
• PostgreSQL: Docker health check uses pg_isready
• Redis: Docker health check uses redis-cli ping

Post-Deployment Verification

The deployment script automatically verifies:

1. Backend health endpoint returns 200 OK
2. Swagger UI is accessible
3. Frontend homepage is accessible

Manual Verification

# Check backend health
curl http://localhost:3001/v1/health | jq .

# Check service status
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env ps

Troubleshooting

Common Issues

1. Missing Environment Variable Files

Missing booking-deploy/compose/dev.compose.env
Create it from booking-deploy/compose/dev.compose.env.example

Solution: Copy the template file and fill in actual values.

2. Migration Failure

Error: P3009: migrate found failed migrations in the target database

Solution:

• Check database connection string
• Manually fix migrations: docker compose exec postgres psql -U postgres -d booking_system
• View migration logs

3. Health Check Failure

The deployment script times out after 80 seconds. Solution:

• Check service logs: docker compose logs backend
• Verify database connection: docker compose exec backend npm run prisma:deploy
• Check for port conflicts

4. Image Pull Failure

Error response from daemon: pull access denied for cho-geer/booking-backend

Solution:

• Confirm the Docker Hub repository exists and is public
• Or update compose/dev.compose.env to use locally built images

Viewing Logs

# View all service logs
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs

# View specific service logs
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs backend

# Tail logs in real-time
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env logs -f

Upgrades and Rollbacks

Version Upgrades

1. Update image tags in compose/dev.compose.env or compose/prod.compose.env
2. Execute deployment script
3. Verify new version functionality

Rollback Operations

1. Restore old image tags in environment variable files
2. Execute deployment script
3. Database forward compatibility: Ensure old version applications can work with current database schema

Zero-Downtime Deployment (Future Extension)

The current deployment strategy uses rolling restarts, future extensions could include:

• Blue-green deployment
• Canary releases
• Using Docker Swarm or Kubernetes

Security Considerations

1. Sensitive Information Management

• Never commit .env files to version control
• Use secret management services (e.g., AWS Secrets Manager) for production secrets
• Regularly rotate JWT secrets and database passwords

2. Network Security

• Use dedicated networks for production environments
• Restrict external access to database and Redis
• Enable firewall rules

3. Image Security

• Regularly scan images for vulnerabilities
• Use minimal base images
• Update dependencies promptly

Automated CI/CD (Future)

Current deployment is manually triggered, future integration with CI/CD pipelines:

GitHub Actions Workflow

name: Deploy to Production
on:
  push:
    tags:
      - 'v*'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Server
        uses: appleboy/ssh-action@v0.1.5
        with:
          host: ${{ secrets.PROD_HOST }}
          username: ${{ secrets.PROD_USER }}
          key: ${{ secrets.PROD_SSH_KEY }}
          script: |
            cd /opt/booking-system/booking-deploy
            ./scripts/deploy-prod.sh

Approval Process

Production deployments should include:

1. Code review
2. Automated test passing
3. Manual approval
4. Post-deployment verification

---

Appendix

A. Manual Deployment Command Reference

# Pull images
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env pull

# Execute migrations
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env run --rm migration

# Start services
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env up -d

# Stop services
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env down

# View status
docker compose -f compose/docker-compose.dev.yml --env-file compose/dev.compose.env ps

B. Environment Variables Description

See comments in each .env.example file.

C. Related Documentation

• Docker Hub Image Build Configuration
• Backend API Documentation
• Frontend Development Guide

---

Last updated: 2026-04-08 Maintained by: DevOps Team