Running Node.js directly on a VPS works until you need to manage dependencies, Node.js versions, environment variables, and process restart behavior across deploys. Docker solves these problems by packaging everything into a reproducible container. This article covers multi-stage Docker builds for small production images, health checks that catch application failures before users do, and a deployment workflow that minimizes downtime.<\/p>\n\n
Docker on a single VPS is not Kubernetes. It is a packaging and isolation tool that gives you:<\/p>\n\n
A multi-stage build separates the build environment from the runtime environment. The final image contains only the production dependencies and the compiled application, not the build tools or source code:<\/p>\n\n
# Dockerfile\n# Stage 1: Build\nFROM node:20-alpine AS builder\n\nWORKDIR \/app\n\n# Install dependencies (separate layer for caching)\nCOPY package*.json .\/\nRUN npm ci --only=production && \\\n cp -R node_modules \/tmp\/node_modules\n\n# Install all dependencies for build\nRUN npm ci\n\n# Copy source and build\nCOPY . .\nRUN npm run build\n\n# Stage 2: Production\nFROM node:20-alpine AS production\n\nRUN addgroup -g 1001 appgroup && \\\n adduser -u 1001 -G appgroup -s \/bin\/sh -D appuser\n\nWORKDIR \/app\n\n# Copy only production artifacts\nCOPY --from=builder \/tmp\/node_modules .\/node_modules\nCOPY --from=builder \/app\/dist .\/dist\nCOPY package*.json .\/\n\n# Set non-root user\nUSER appuser\n\n# Health check\nHEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \\\n CMD node -e \"require('http').get('http:\/\/localhost:3000\/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})\"\n\nEXPOSE 3000\n\nCMD [\"node\", \"dist\/server.js\"]<\/code><\/pre>\n\nThis Dockerfile produces a final image of approximately 80\u2013120 MB, compared to 400\u2013600 MB for a single-stage build. The build stage compiles TypeScript and bundles assets. The production stage copies only the compiled output and production dependencies.<\/p>\n\n
Step 2: Health Check Endpoint<\/h2>\n\n
The Docker HEALTHCHECK directive in the Dockerfile above calls a \/health<\/code> endpoint. Your application must implement this endpoint. It should return a 200 status code when the application is healthy and a 5xx status code when it is not:<\/p>\n\n\/\/ Express.js health check endpoint\napp.get('\/health', (req, res) => {\n const checks = {\n database: await checkDatabase(),\n redis: await checkRedis(),\n uptime: process.uptime()\n };\n\n const allHealthy = Object.values(checks).every(c => c !== false);\n const status = allHealthy ? 200 : 503;\n\n res.status(status).json({\n status: allHealthy ? 'healthy' : 'unhealthy',\n timestamp: new Date().toISOString(),\n checks\n });\n});\n\nasync function checkDatabase() {\n try {\n await pool.query('SELECT 1');\n return true;\n } catch {\n return false;\n }\n}\n\nasync function checkRedis() {\n try {\n await redis.ping();\n return true;\n } catch {\n return false;\n }\n}<\/code><\/pre>\n\nDocker will mark the container as unhealthy after 3 failed health checks. If you use Docker Swarm or a reverse proxy that respects health checks, unhealthy containers are automatically removed from the load balancer pool.<\/p>\n\n
Step 3: Docker Compose for Production<\/h2>\n\n
Use Docker Compose to define the application stack \u2014 the Node.js app, a reverse proxy, and any databases:<\/p>\n\n
# docker-compose.yml\nversion: \"3.8\"\n\nservices:\n app:\n build:\n context: .\n dockerfile: Dockerfile\n container_name: node-app\n restart: unless-stopped\n expose:\n - \"3000\"\n environment:\n - NODE_ENV=production\n - DATABASE_URL=postgresql:\/\/app_user:${DB_PASSWORD}@db:5432\/app_db\n - REDIS_URL=redis:\/\/redis:6379\n deploy:\n resources:\n limits:\n memory: 256M\n cpus: \"0.5\"\n reservations:\n memory: 128M\n cpus: \"0.25\"\n networks:\n - backend\n\n db:\n image: postgres:16-alpine\n container_name: postgres\n restart: unless-stopped\n environment:\n - POSTGRES_USER=app_user\n - POSTGRES_PASSWORD=${DB_PASSWORD}\n - POSTGRES_DB=app_db\n volumes:\n - pgdata:\/var\/lib\/postgresql\/data\n deploy:\n resources:\n limits:\n memory: 256M\n cpus: \"0.5\"\n networks:\n - backend\n\n redis:\n image: redis:7-alpine\n container_name: redis\n restart: unless-stopped\n command: redis-server --appendonly yes --maxmemory 64mb --maxmemory-policy allkeys-lru\n volumes:\n - redis_data:\/data\n deploy:\n resources:\n limits:\n memory: 96M\n cpus: \"0.25\"\n networks:\n - backend\n\nnetworks:\n backend:\n driver: bridge\n internal: true\n\nvolumes:\n pgdata:\n redis_data:<\/code><\/pre>\n\nStep 4: Deployment Workflow<\/h2>\n\n
Set up a deployment script that pulls the latest code, rebuilds the container, and restarts the service with minimal downtime:<\/p>\n\n
#!\/bin\/bash\n# deploy.sh - Production deployment\nset -euo pipefail\n\ncd \/opt\/myapp\n\n# Pull latest code\ngit pull origin main\n\n# Build the new image\ndocker compose build app\n\n# Restart only the app service (database stays running)\ndocker compose up -d --no-deps app\n\n# Wait for health check to pass\nfor i in {1..30}; do\n if curl -sf http:\/\/localhost:3000\/health > \/dev\/null; then\n echo \"App is healthy\"\n break\n fi\n echo \"Waiting for app to become healthy... ($i\/30)\"\n sleep 2\ndone\n\n# Clean up old images\ndocker image prune -f\n\necho \"Deployment complete\"<\/code><\/pre>\n\n--no-deps<\/code> restarts only the app container, leaving the database and Redis containers running. This reduces downtime to the time it takes for the new container to start and pass its health check \u2014 typically 5\u201310 seconds.<\/p>\n\nStep 5: Reverse Proxy with Nginx<\/h2>\n\n
Add an Nginx reverse proxy to handle TLS termination, static file serving, and load balancing between multiple app instances:<\/p>\n\n
# nginx\/conf.d\/app.conf\nserver {\n listen 80;\n server_name yourdomain.com;\n\n # Static files served directly by Nginx\n location \/static\/ {\n root \/var\/www\/app;\n expires 30d;\n add_header Cache-Control \"public, immutable\";\n }\n\n # Proxy to Node.js app\n location \/ {\n proxy_pass http:\/\/node-app:3000;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_read_timeout 60s;\n }\n}<\/code><\/pre>\n\nAdd the reverse proxy service to your docker-compose.yml:<\/p>\n\n
reverse-proxy:\n image: nginx:1.25-alpine\n container_name: nginx-proxy\n restart: unless-stopped\n ports:\n - \"80:80\"\n - \"443:443\"\n volumes:\n - .\/nginx\/nginx.conf:\/etc\/nginx\/nginx.conf:ro\n - .\/nginx\/conf.d:\/etc\/nginx\/conf.d:ro\n - .\/certbot\/www:\/var\/www\/certbot:ro\n - .\/certbot\/conf:\/etc\/letsencrypt:ro\n networks:\n - frontend\n - backend\n depends_on:\n app:\n condition: service_healthy\n deploy:\n resources:\n limits:\n memory: 64M\n cpus: \"0.25\"<\/code><\/pre>\n\nResource Requirements on a VPS<\/h2>\n\n
Here is the memory footprint of a typical Node.js + PostgreSQL + Redis + Nginx stack on a VPS:<\/p>\n\n