Aller au contenu principal

Dokploy Zero Downtime Deployment Setup

Last Updated: 2025-11-23 Status: Ready for Implementation Applies To: EMTB Production Deployment

Quick Reference​

JSON Configurations (Copy-Paste Ready)​

API Service - Health Check​

{
  "Test": ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3001/health || exit 1"],
  "Interval": 30000000000,
  "Timeout": 10000000000,
  "StartPeriod": 40000000000,
  "Retries": 3
}

API Service - Update Config​

{
  "Parallelism": 1,
  "Delay": 10000000000,
  "FailureAction": "rollback",
  "Order": "start-first"
}

Frontend Service - Health Check​

{
  "Test": ["CMD", "curl", "-f", "http://localhost/health"],
  "Interval": 30000000000,
  "Timeout": 10000000000,
  "StartPeriod": 10000000000,
  "Retries": 3
}

Frontend Service - Update Config​

{
  "Parallelism": 1,
  "Delay": 10000000000,
  "FailureAction": "rollback",
  "Order": "start-first"
}

Configuration Checklist​

✅ API Service Configuration​

IMPORTANT: These settings are only available for "Application" type, NOT "Compose" type in Dokploy.

Navigation Path:

  1. Go to Dokploy Dashboard
  2. Click on "Applications" in the sidebar
  3. Click on your API application (emtb-api)
  4. Click the "Advanced" tab (at the top)
  5. Scroll down to find "Swarm Settings" section
  6. You should see fields for:
    • Health Check
    • Restart Policy
    • Update Config
    • Placement
    • Mode
    • Resources

Configuration Steps:

  • In the "Health Check" field, paste API health check JSON
  • In the "Update Config" field, paste API update config JSON
  • Click "Save" or "Apply" button
  • Click "Redeploy" to apply changes
  • Enable Rollbacks in Settings (Recommended)

✅ Frontend Service Configuration​

Navigation Path:

  1. Go back to "Applications" list
  2. Click on your Frontend application (emtb-frontend)
  3. Click the "Advanced" tab
  4. Scroll to "Swarm Settings" section

Configuration Steps:

  • In the "Health Check" field, paste Frontend health check JSON
  • In the "Update Config" field, paste Frontend update config JSON
  • Click "Save" or "Apply"
  • Click "Redeploy" to apply changes
  • Enable Rollbacks in Settings (Recommended)

✅ Testing​

  • Deploy application
  • Keep browser tab open on https://app.emtb.consulting
  • Continuously refresh during deployment
  • Expected: No "502 Bad Gateway" errors
  • Expected: Continuous availability throughout deployment

Time Values Reference​

DurationNanoseconds
10 sec10000000000
30 sec30000000000
40 sec40000000000
60 sec60000000000

How It Works​

Without Zero Downtime (Current)​

  1. Dokploy stops old container
  2. Dokploy starts new container
  3. Gap period: Container building, starting, running migrations
  4. Result: 502 Bad Gateway errors during gap

With Zero Downtime (After Configuration)​

  1. Dokploy starts new container (alongside old one)
  2. Health checks verify new container is ready
  3. After 3 successful health checks, traffic switches
  4. Old container is stopped
  5. Result: No downtime, seamless transition

Key Configuration Explained​

Order: "start-first"​

Most Critical Setting

  • Before: stop-first (causes downtime)
  • After: start-first (zero downtime)
  • Ensures new container is running before old one stops

StartPeriod​

Grace Period Before Health Checks

  • API: 40 seconds (needs time for migrations)
  • Frontend: 10 seconds (nginx starts quickly)
  • Prevents false failures during container initialization

Retries: 3​

Health Check Verification

  • Container must pass 3 consecutive health checks
  • If any check fails, counter resets
  • Ensures container is truly stable before cutover

FailureAction: "rollback"​

Automatic Recovery

  • If new container fails health checks
  • Automatically reverts to previous version
  • Prevents broken deployments from going live

Troubleshooting​

Issue: Still Seeing 502 Errors​

Check 1: Verify Health Endpoints​

# SSH into API container
docker exec -it emtb-api wget --spider http://localhost:3001/health

# SSH into Frontend container
docker exec -it emtb-frontend curl -f http://localhost/health

Expected: Both should return successfully

Check 2: Verify JSON Format​

  • No syntax errors
  • All numbers are plain integers (no quotes)
  • All strings use double quotes
  • Check for trailing commas

Check 3: Check Dokploy Logs​

  1. Go to application in Dokploy
  2. Click "Logs"
  3. Look for health check messages
  4. Look for error messages during deployment

Check 4: Increase Start Period​

If API takes longer to start:

"StartPeriod": 60000000000  // Increase to 60 seconds

Issue: Health Checks Failing​

Cause 1: curl/wget Not Available​

Frontend uses curl, API uses wget

Solution for Frontend:

# In apps/frontend/Dockerfile
RUN apk add --no-cache curl

Solution for API: Already included âś“

Cause 2: Port Mismatch​

  • API health check uses: localhost:3001
  • Frontend health check uses: localhost
  • Verify these match your exposed ports

Cause 3: Health Endpoint Not Responding​

Check application logs for errors in the /health endpoint

Current Status​

✅ Already Configured​

  • Docker health checks in docker-compose.yml
  • Health endpoints implemented:
    • API: /health
    • Frontend: /health
  • Traefik labels configured
  • Container networking (dokploy-network)

⚠️ Needs Configuration​

  • Dokploy Swarm health check settings (see checklist above)
  • Dokploy update config with start-first order
  • Optional: Enable rollbacks

Deployment Process​

Standard Deployment Flow​

  1. Push code to repository
  2. Dokploy detects changes (or manual deploy)
  3. New containers start with health checks
  4. Health checks monitor new containers
  5. After 3 successful checks, traffic switches
  6. Old containers stop gracefully
  7. Deployment complete - zero downtime âś“

First-Time Configuration Steps​

  1. Apply Swarm settings (one-time)
  2. Test deployment
  3. Verify zero downtime
  4. Enable rollbacks
  5. Document any adjustments needed

Additional Optimizations​

Building on the server consumes resources. Consider:

  1. Setup GitHub Actions:

    • Build Docker images in CI/CD
    • Push to Docker Hub / GitHub Container Registry
    • Dokploy pulls pre-built images

  2. Benefits:

    • Faster deployments
    • Less server resource consumption
    • No build-related downtime
    • Better resource management

Rollback Strategy​

With rollbacks enabled:

  • Each deployment creates a snapshot
  • Manual rollback to any previous version
  • Useful for quick recovery
  • Recommended for production

Success Criteria​

After configuration, you should experience:

âś… Zero downtime during deployments âś… No 502 errors when refreshing during deployment âś… Automatic rollback if deployment fails âś… Health verification before traffic switching âś… Graceful transitions between versions

Support​

If Issues Persist​

  1. Check Dokploy application logs
  2. Check container logs for health check failures
  3. Verify JSON configuration syntax
  4. Confirm health endpoints return 200 OK
  5. Check Traefik dashboard for routing status

Documentation​

End of Document