Posted on Sep 25

The Ultimate Checklist for Zero‑Downtime Deploys with Docker & Nginx

Introduction

Zero‑downtime deployments are a non‑negotiable expectation for modern web services. As a DevOps lead, you’ve probably wrestled with traffic spikes, rolling restarts, and the dreaded "service unavailable" page. This checklist walks you through a pragmatic, Docker‑centric workflow that leverages Nginx as a reverse‑proxy to achieve seamless blue‑green releases. Follow each step, automate where you can, and you’ll keep users blissfully unaware of any underlying changes.

1. Pre‑deployment Health Checks

Before you touch a container, verify that the current production stack is healthy. A quick health‑check script can save you from deploying into a fragile environment.

Ping the health endpoint: curl -f https://api.example.com/health
Validate DB connectivity: pg_isready -h $DB_HOST -p $DB_PORT
Confirm log aggregation: Ensure Loki/Prometheus are receiving metrics.

If any of these checks fail, halt the pipeline and investigate. A solid foundation prevents cascading failures during the rollout.

2. Docker Image Build & Tagging

Consistent image naming is the backbone of a reliable release process. Use semantic versioning combined with a latest tag for quick rollbacks.

# Build the image docker build -t myapp:${CI_COMMIT_TAG} . # Tag as latest for the current release docker tag myapp:${CI_COMMIT_TAG} myapp:latest # Push to registry docker push myapp:${CI_COMMIT_TAG} docker push myapp:latest

Checklist items

[ ] Dockerfile follows best practices (multi‑stage builds, non‑root user).
[ ] .dockerignore excludes test data and local configs.
[ ] Image size stays under 200 MB for faster pull times.
[ ] All secrets are injected at runtime, never baked in.

3. Nginx Configuration for Blue‑Green Routing

Nginx will act as the traffic director, sending requests to either the blue (current) or green (new) upstream based on a simple variable.

upstream blue { server 127.0.0.1:8001; } upstream green { server 127.0.0.1:8002; } map $http_x_deploy_target $backend { default blue; "green" green; } server { listen 80; location / { proxy_pass http://$backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }

Key points

The X-Deploy-Target header lets you switch traffic without reloading Nginx.
Keep both upstreams on the same host for simplicity, or use separate servers for true isolation.
Reload Nginx after any config change: nginx -s reload.

4. CI/CD Pipeline Steps

Automate the checklist with a CI system (GitHub Actions, GitLab CI, or Jenkins). Below is a minimal GitHub Actions workflow snippet.

name: Deploy on: push: tags: - 'v*.*.*' jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Docker Buildx uses: docker/setup-buildx-action@v2 - name: Log in to registry uses: docker/login-action@v2 with: username: ${{ secrets.REGISTRY_USER }} password: ${{ secrets.REGISTRY_PASS }} - name: Build & push image run: | docker build -t myapp:${{ github.ref_name }} . docker push myapp:${{ github.ref_name }} - name: Deploy green container run: | docker run -d --name myapp-green -p 8002:80 myapp:${{ github.ref_name }} - name: Switch traffic to green run: | curl -X POST -H "X-Deploy-Target: green" http://nginx-host/healthz - name: Verify green health run: | curl -f http://nginx-host/healthz - name: Retire blue container run: | docker stop myapp-blue && docker rm myapp-blue docker rename myapp-green myapp-blue

Pipeline sanity checks

Ensure the healthz endpoint returns 200 before flipping traffic.
Keep the blue container running until green passes all integration tests.
Tag the release in your version control system for traceability.

5. Observability & Rollback Strategy

Even with a perfect checklist, things can go sideways. Instrument both Nginx and your application.

Metrics: Export request latency, error rates, and active connections to Prometheus.
Logs: Forward Nginx access/error logs to Loki or Elastic Stack.
Alerting: Trigger a PagerDuty alert if error rate > 1% for 5 minutes.

Rollback steps

Send X-Deploy-Target: blue header to Nginx.
Verify blue health endpoint again.
Stop and remove the green container.
Optionally redeploy the previous Docker tag.

Having a one‑click rollback script reduces MTTR dramatically.

6. Final Thoughts

Zero‑downtime deployments aren’t magic; they’re the result of disciplined automation, clear health checks, and a reversible traffic switch. By following this checklist you’ll: