Deploy a Next.js Application with Docker and CI/CD in Production

# Check the Node.js version
node --version  # v20.x.x required
 
# Install dependencies
npm install
 
# Test the production build
npm run build
 
# Verify that the server starts
npm start

// app/api/health/route.ts
import { NextResponse } from "next/server";
 
export async function GET() {
  return NextResponse.json({
    status: "healthy",
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
  });
}

# =============================================================================
# Stage 1: Base image with dependencies
# =============================================================================
FROM node:20-alpine AS base
 
# Install libc6-compat for native modules
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
# =============================================================================
# Stage 2: Install dependencies
# =============================================================================
FROM base AS deps
 
# Copy dependency files
COPY package.json package-lock.json* ./
 
# Install all dependencies (including devDependencies for the build)
RUN npm ci
 
# =============================================================================
# Stage 3: Build the application
# =============================================================================
FROM base AS builder
WORKDIR /app
 
# Copy installed dependencies
COPY --from=deps /app/node_modules ./node_modules
 
# Copy source code
COPY . .
 
# Disable Next.js telemetry during build
ENV NEXT_TELEMETRY_DISABLED=1
 
# Production build
RUN npm run build
 
# =============================================================================
# Stage 4: Production image (lightweight)
# =============================================================================
FROM node:20-alpine AS runner
WORKDIR /app
 
# Production mode
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
 
# Create a non-root user for security
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
 
# Copy public files
COPY --from=builder /app/public ./public
 
# Copy the Next.js standalone build
# Standalone mode copies only the necessary files
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
# Use the non-root user
USER nextjs
 
# Expose the port
EXPOSE 3000
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"
 
# Docker healthcheck
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
 
# Start the application
CMD ["node", "server.js"]

// next.config.js (or next.config.mjs)
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: "standalone",
};
 
module.exports = nextConfig;

# .dockerignore
node_modules
.next
.git
.gitignore
*.md
docker-compose*.yml
.env*.local
.vscode
.idea
coverage
.husky

# Build the image
docker build -t my-nextjs-app .
 
# Check the image size
docker images my-nextjs-app
# REPOSITORY        TAG       SIZE
# my-nextjs-app     latest    ~150MB
 
# Run the container
docker run -p 3000:3000 my-nextjs-app
 
# Test in another terminal
curl http://localhost:3000/api/health

# docker-compose.dev.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: deps  # Use only the dependencies stage
    command: npm run dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules  # Exclude node_modules from the volume
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
 
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
 
  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
 
volumes:
  postgres_data:
  redis_data:

# docker-compose.prod.yml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    ports:
      - "3000:3000"
    env_file:
      - .env.production
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      start_period: 40s
      retries: 3
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "0.5"
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
 
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    env_file:
      - .env.production
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 256M
 
  cache:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --maxmemory 128mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    deploy:
      resources:
        limits:
          memory: 128M
 
volumes:
  postgres_data:
  redis_data:

# Start all services
docker compose -f docker-compose.dev.yml up -d
 
# View logs
docker compose -f docker-compose.dev.yml logs -f app
 
# Stop services
docker compose -f docker-compose.dev.yml down

# .github/workflows/deploy.yml
name: CI/CD Pipeline
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  # =====================================================
  # Job 1: Linting and tests
  # =====================================================
  test:
    name: Tests and quality
    runs-on: ubuntu-latest
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: "npm"
 
      - name: Install dependencies
        run: npm ci
 
      - name: Linting
        run: npm run lint
 
      - name: Unit tests
        run: npm test -- --passWithNoTests
 
      - name: Verification build
        run: npm run build
 
  # =====================================================
  # Job 2: Build and push Docker image
  # =====================================================
  build:
    name: Docker Build
    runs-on: ubuntu-latest
    needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
 
    permissions:
      contents: read
      packages: write
 
    outputs:
      image-tag: ${{ steps.meta.outputs.tags }}
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Login to GitHub registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extract Docker metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=
            type=raw,value=latest
 
      - name: Setup Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
  # =====================================================
  # Job 3: Deploy to VPS
  # =====================================================
  deploy:
    name: Production deployment
    runs-on: ubuntu-latest
    needs: build
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
 
    environment:
      name: production
      url: https://${{ vars.DOMAIN_NAME }}
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: ${{ secrets.VPS_USER }}
          key: ${{ secrets.VPS_SSH_KEY }}
          script: |
            # Navigate to the project directory
            cd /opt/apps/mon-app
 
            # Login to the GitHub registry
            echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
 
            # Pull the latest image
            docker pull ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
 
            # Update the service with zero downtime
            docker compose -f docker-compose.prod.yml up -d --no-deps --wait app
 
            # Clean up old images
            docker image prune -f
 
            # Verify the healthcheck
            sleep 10
            curl -f http://localhost:3000/api/health || exit 1
 
      - name: Success notification
        if: success()
        run: echo "Deployment successful on ${{ vars.DOMAIN_NAME }}"
 
      - name: Failure notification
        if: failure()
        run: echo "Deployment failed - check the logs"

# Update the system
sudo apt update && sudo apt upgrade -y
 
# Install Docker via the official script
curl -fsSL https://get.docker.com | sudo sh
 
# Add the user to the docker group
sudo usermod -aG docker $USER
 
# Install Docker Compose (included in modern Docker Engine)
docker compose version
 
# Restart the session to apply permissions
exit
# Reconnect

# Create the application directory
sudo mkdir -p /opt/apps/mon-app
sudo chown $USER:$USER /opt/apps/mon-app
cd /opt/apps/mon-app
 
# Create the production environment file
cat > .env.production << 'EOF'
NODE_ENV=production
DATABASE_URL=postgresql://postgres:YOUR_STRONG_PASSWORD@db:5432/myapp
REDIS_URL=redis://cache:6379
POSTGRES_USER=postgres
POSTGRES_PASSWORD=YOUR_STRONG_PASSWORD
POSTGRES_DB=myapp
EOF
 
# Protect the file
chmod 600 .env.production

# Copy docker-compose.prod.yml to the server from your local machine
scp docker-compose.prod.yml deploy@YOUR_VPS:/opt/apps/mon-app/

# Create the deploy user
sudo adduser --disabled-password deploy
sudo usermod -aG docker deploy
 
# Configure the SSH key for deployment
sudo mkdir -p /home/deploy/.ssh
sudo cp ~/.ssh/authorized_keys /home/deploy/.ssh/
# Add the public key generated for GitHub Actions
echo "YOUR_ED25519_PUBLIC_KEY" | sudo tee -a /home/deploy/.ssh/authorized_keys
sudo chown -R deploy:deploy /home/deploy/.ssh
sudo chmod 700 /home/deploy/.ssh
sudo chmod 600 /home/deploy/.ssh/authorized_keys

# Install Nginx
sudo apt install -y nginx
 
# Install Certbot for Let's Encrypt
sudo apt install -y certbot python3-certbot-nginx

# /etc/nginx/sites-available/my-app
upstream nextjs_upstream {
    server 127.0.0.1:3000;
    keepalive 64;
}
 
server {
    listen 80;
    server_name myapp.example.com;
 
    # Redirect to HTTPS (will be configured by Certbot)
    location / {
        return 301 https://$server_name$request_uri;
    }
}
 
server {
    listen 443 ssl http2;
    server_name myapp.example.com;
 
    # SSL certificates will be added by Certbot
    # ssl_certificate /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/myapp.example.com/privkey.pem;
 
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
 
    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml application/json application/javascript
               application/xml+rss application/atom+xml image/svg+xml;
 
    # Cache Next.js static files
    location /_next/static {
        proxy_pass http://nextjs_upstream;
        proxy_cache_valid 60m;
        add_header Cache-Control "public, max-age=31536000, immutable";
    }
 
    # Static public files
    location /images {
        proxy_pass http://nextjs_upstream;
        proxy_cache_valid 60m;
        add_header Cache-Control "public, max-age=86400";
    }
 
    # Proxy to Next.js
    location / {
        proxy_pass http://nextjs_upstream;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;
 
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

# Enable the site
sudo ln -s /etc/nginx/sites-available/my-app /etc/nginx/sites-enabled/
 
# Check the configuration
sudo nginx -t
 
# Reload Nginx
sudo systemctl reload nginx
 
# Get the SSL certificate with Certbot
sudo certbot --nginx -d myapp.example.com --non-interactive --agree-tos -m your@email.com
 
# Verify automatic renewal
sudo certbot renew --dry-run

#!/bin/bash
# scripts/deploy.sh - Zero downtime deployment
 
set -euo pipefail
 
APP_DIR="/opt/apps/mon-app"
HEALTH_URL="http://localhost:3000/api/health"
MAX_RETRIES=30
RETRY_INTERVAL=2
 
log() {
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
}
 
check_health() {
    curl -sf "$HEALTH_URL" > /dev/null 2>&1
}
 
cd "$APP_DIR"
 
log "Starting deployment..."
 
# Pull the new image
log "Pulling the new image..."
docker compose -f docker-compose.prod.yml pull app
 
# Start the new container
log "Starting the new container..."
docker compose -f docker-compose.prod.yml up -d --no-deps app
 
# Wait for the healthcheck to pass
log "Verifying healthcheck..."
retries=0
until check_health; do
    retries=$((retries + 1))
    if [ "$retries" -ge "$MAX_RETRIES" ]; then
        log "ERROR: Healthcheck failed after $MAX_RETRIES attempts"
        log "Rolling back..."
        docker compose -f docker-compose.prod.yml rollback app 2>/dev/null || true
        exit 1
    fi
    log "Waiting for healthcheck... ($retries/$MAX_RETRIES)"
    sleep "$RETRY_INTERVAL"
done
 
log "Healthcheck OK"
 
# Clean up old images
docker image prune -f
 
log "Deployment completed successfully"

# Make the script executable
chmod +x /opt/apps/mon-app/scripts/deploy.sh

// lib/logger.ts
type LogLevel = "info" | "warn" | "error" | "debug";
 
interface LogEntry {
  level: LogLevel;
  message: string;
  timestamp: string;
  [key: string]: unknown;
}
 
function log(level: LogLevel, message: string, meta?: Record<string, unknown>) {
  const entry: LogEntry = {
    level,
    message,
    timestamp: new Date().toISOString(),
    ...meta,
  };
 
  const output = JSON.stringify(entry);
 
  if (level === "error") {
    console.error(output);
  } else if (level === "warn") {
    console.warn(output);
  } else {
    console.log(output);
  }
}
 
export const logger = {
  info: (msg: string, meta?: Record<string, unknown>) => log("info", msg, meta),
  warn: (msg: string, meta?: Record<string, unknown>) => log("warn", msg, meta),
  error: (msg: string, meta?: Record<string, unknown>) => log("error", msg, meta),
  debug: (msg: string, meta?: Record<string, unknown>) => log("debug", msg, meta),
};

# View logs in real time
docker compose -f docker-compose.prod.yml logs -f app
 
# View container statistics
docker stats
 
# Check container status
docker compose -f docker-compose.prod.yml ps
 
# Check Docker disk usage
docker system df
 
# Clean up unused resources
docker system prune -f

// app/api/health/route.ts
import { NextResponse } from "next/server";
 
export async function GET() {
  const healthData = {
    status: "healthy",
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    memory: {
      used: Math.round(process.memoryUsage().heapUsed / 1024 / 1024),
      total: Math.round(process.memoryUsage().heapTotal / 1024 / 1024),
      unit: "MB",
    },
    version: process.env.npm_package_version || "unknown",
    node: process.version,
  };
 
  return NextResponse.json(healthData);
}

# .env.example - Required environment variables
NODE_ENV=production
DATABASE_URL=postgresql://user:password@db:5432/dbname
REDIS_URL=redis://cache:6379
 
# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=change_me
POSTGRES_DB=myapp
 
# Application
NEXTAUTH_SECRET=generate_a_strong_secret
NEXTAUTH_URL=https://myapp.example.com

# Build and start
docker compose -f docker-compose.dev.yml up --build -d
 
# Check logs
docker compose -f docker-compose.dev.yml logs -f
 
# Test the healthcheck
curl http://localhost:3000/api/health

# Create a test branch
git checkout -b test/cicd-pipeline
 
# Make a minor change
echo "// test" >> lib/logger.ts
 
# Commit and push
git add . && git commit -m "test: verify CI/CD pipeline"
git push -u origin test/cicd-pipeline
 
# Create a pull request on GitHub
gh pr create --title "Test CI/CD pipeline" --body "Pipeline verification"

# After merging to main, verify the deployment
curl https://myapp.example.com/api/health
 
# Expected response:
# {"status":"healthy","timestamp":"...","uptime":42,"memory":{"used":85,"total":128,"unit":"MB"}}

# Check container logs
docker compose -f docker-compose.prod.yml logs app --tail 50
 
# Check that ports are not in use
sudo ss -tulnp | grep 3000
 
# Restart services
docker compose -f docker-compose.prod.yml restart
 
# Fully rebuild
docker compose -f docker-compose.prod.yml up -d --build --force-recreate