Node.js App #

# The most basic Node.js reverse proxy configuration
example.com {
    reverse_proxy localhost:3000
}

# Optimal production configuration for a Node.js application
example.com {
    # 1. Structured Access Logging Configuration (JSON)
    log {
        output file /var/log/caddy/nodejs-access.log {
            roll_size 100mb
            roll_keep 7
            roll_keep_days 30
        }
        format json
    }
    
    # 2. Automatic Response Compression (Zstd and Gzip)
    encode zstd gzip
    
    # 3. Security Using HTTP Security Headers
    header {
        # Prevent clickjacking
        X-Frame-Options "SAMEORIGIN"
        # Enable browser encryption enforcement (HSTS)
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        # Prevent browsers from guessing file MIME types (MIME sniffing)
        X-Content-Type-Options "nosniff"
        # Configure a safe referrer policy
        Referrer-Policy "strict-origin-when-cross-origin"
        # Hide the web server binary information for security
        -Server
        -X-Powered-By
    }
    
    # 4. Efficient Static Asset Serving Directly by Caddy.
    # All requests to the /static/ folder or favicon/robots files
    # are read directly from disk by Caddy without triggering the Node.js process.
    @static path /static/* /favicon.ico /robots.txt
    handle @static {
        root * /var/www/myapp
        file_server
        # Install aggressive 1-year Cache-Control because static files have unique name hashes
        header Cache-Control "public, max-age=31536000, immutable"
    }
    
    # 5. All Other (Dynamic/API) Requests Are Routed to Node.js
    handle {
        reverse_proxy localhost:3000 {
            # Forward the visitor's real IP header to Node.js
            header_up X-Real-IP {remote_host}
            header_up X-Forwarded-For {remote_host}
            header_up X-Forwarded-Proto {scheme}
            header_up Host {host}
            
            # Backend Health Testing (Active Health Check)
            health_uri /health
            health_interval 10s
            health_timeout 5s
            health_status 200
            
            # Transport timeout configuration
            transport http {
                dial_timeout 5s
                response_header_timeout 60s
                read_timeout 120s
                write_timeout 120s
            }
        }
    }
}

# Install PM2 globally on our Linux system
sudo npm install -g pm2

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'nodejs-prod-app',
    script: 'dist/server.js',        // Your application's entry point file
    instances: 'max',                 // Run as many instances as the CPU core count (Cluster Mode)
    exec_mode: 'cluster',             // Enable cluster mode for internal load balancing
    
    // Environment Variable Configuration
    env: {
      NODE_ENV: 'development',
      PORT: 3000
    },
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    
    // Log File Configuration
    error_file: '/var/log/myapp/error.log',
    out_file: '/var/log/myapp/access.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    
    // Crash Recovery Policy (Restart Policy)
    max_restarts: 10,                 // Maximum consecutive automatic restarts before stopping
    min_uptime: '15s',                // Minimum duration the app must stay alive to be considered stable
    max_memory_restart: '500M',       // Auto-restart if RAM consumption exceeds 500MB (leak protection)
    kill_timeout: 3000                // Graceful shutdown wait time before forced termination (ms)
  }]
};

# Run the application using the ecosystem file in production mode
pm2 start ecosystem.config.js --env production

# Save the active PM2 process list to the system configuration
pm2 save

# Configure PM2 to automatically restart when the Linux server boots (reboot)
pm2 startup

# Caddy Load Balancing configuration for a local Node.js cluster
example.com {
    encode zstd gzip
    
    reverse_proxy {
        # Define all Node.js instance targets (Upstreams)
        to localhost:3000 localhost:3001 localhost:3002 localhost:3003
        
        # Request distribution policy: Round Robin (alternating sequentially)
        lb_policy round_robin
        
        # Active Health Check: Test the /health route every 10 seconds
        health_uri /health
        health_interval 10s
        
        # Passive Health Check (Circuit Breaker):
        # If an instance fails to respond 3 times in a row,
        # isolate that instance from the routing list for 30 seconds.
        fail_duration 30s
        max_fails 3
        
        # Forward the real IP header
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

# Example of Socket.io WebSocket routing in Caddy
example.com {
    # Regular route for frontend static pages
    handle /static/* {
        root * /var/www/myapp
        file_server
    }
    
    # Socket.io WebSocket connection route.
    # Caddy forwards the connection automatically without extra flags.
    handle /socket.io/* {
        reverse_proxy localhost:3000
    }
    
    # Main API route
    handle {
        reverse_proxy localhost:3000
    }
}

#!/bin/bash
# deploy-nodejs.sh — Safe zero-downtime deploy automation script

PROJECT_DIR="/var/www/myapp"
CADDY_BIN="/usr/bin/caddy"

echo "=== Starting the Zero-Downtime Deployment Process ==="

# 1. Enter the project directory and pull the latest code from the Git repository
cd "$PROJECT_DIR" || exit 1
git pull origin main

# 2. Install new dependencies specifically for production needs
npm ci --production

# 3. Compile the code if using TypeScript or a bundler
npm run build

# 4. Validate whether the current system Caddyfile configuration is still valid
echo "Validating the Caddyfile configuration..."
$CADDY_BIN validate --config /etc/caddy/Caddyfile
if [ $? -ne 0 ]; then
    echo "✗ Caddyfile validation failed! Cancel the deployment."
    exit 1
fi

# 5. Trigger PM2 to do a gradual rolling restart.
# PM2 reloads each cluster instance one by one in the background.
# The old instance stays active serving users until the new instance is ready to receive traffic.
echo "Starting the Node.js process rolling restart in PM2..."
pm2 reload ecosystem.config.js --env production

# 6. Wait 5 seconds to give the application initialization time
sleep 5

# 7. Do an internal system health verification (Local Health Check)
echo "Testing the application route health..."
HTTP_STATUS=$(curl -sf -o /dev/null -w "%{http_code}" http://localhost:3000/health)

if [ "$HTTP_STATUS" != "200" ]; then
    echo "✗ Health test failed with status: $HTTP_STATUS!"
    echo "Triggering a rollback to the previous process version..."
    pm2 revert nodejs-prod-app
    exit 1
fi

echo "✓ Deployment completed safely without downtime!"

// server.js (Production Express.js Application)
const express = require('express');
const app = express();

// IMPORTANT: Enable trust proxy so Express trusts the X-Forwarded-* headers from Caddy.
// This guarantees the 'req.ip' property returns the visitor browser's real IP,
// and 'req.secure' correctly detects the HTTPS status for session cookie security.
app.set('trust proxy', 1);

// Provide a health check endpoint
app.get('/health', (req, res) => {
    res.status(200).json({
        status: 'UP',
        uptime: process.uptime(),
        timestamp: new Date().toISOString()
    });
});

// Logging Middleware with the real client IP address
app.use((req, res, next) => {
    // req.ip now contains the real IP (e.g., 203.0.113.50) thanks to 'trust proxy'
    console.log(`[${new Date().toISOString()}] ${req.ip} - ${req.method} ${req.path}`);
    next();
});

app.get('/api/users', (req, res) => {
    res.json([{ id: 1, name: 'Budi' }, { id: 2, name: 'Ani' }]);
});

// Run the Express server
const PORT = process.env.PORT || 3000;
const HOST = '127.0.0.1'; // BIND ONLY TO LOCALHOST (Safe from direct external port access)

app.listen(PORT, HOST, () => {
    console.log(`Express server is internally active at http://${HOST}:${PORT}`);
});

# Centralized CORS configuration in Caddy
api.example.com {
    # Special handling for OPTIONS method requests (Preflight Request)
    @options method OPTIONS
    handle @options {
        header Access-Control-Allow-Origin      "https://app.example.com"
        header Access-Control-Allow-Methods     "GET, POST, PUT, DELETE, OPTIONS"
        header Access-Control-Allow-Headers     "Content-Type, Authorization"
        header Access-Control-Allow-Credentials "true"
        header Access-Control-Max-Age           "86400" # Store the preflight cache for 24 hours
        respond "" 204 # Return an empty response without content
    }
    
    # Insert CORS headers for regular transaction requests (GET, POST, etc.)
    header Access-Control-Allow-Origin      "https://app.example.com"
    header Access-Control-Allow-Credentials "true"
    
    # Compress and forward to the Node.js backend
    encode zstd gzip
    reverse_proxy localhost:3000
}

# Caddyfile configuration specifically for Streaming Responses (SSE)
example.com {
    # Special endpoint for real-time data streaming
    handle /events/* {
        reverse_proxy localhost:3000 {
            # Setting the flush interval to -1 forces Caddy to immediately
            # stream every data chunk from Node.js to the client browser without buffering.
            flush_interval -1
        }
    }
    
    # Other regular endpoints still use standard buffering for efficiency
    handle {
        reverse_proxy localhost:3000
    }
}