Docker Compose blue/green: health gates, proxy switch and rollback

Compose can wait for a container healthcheck, but that does not switch a reverse proxy or prove a release works for users. This disposable lab runs two stateless demo releases in two Compose projects, each with its own bridge network and loopback test port. A proxy in the blue project joins both networks and has a third loopback port. We explicitly switch its route to green and then restore blue.

Blue and green serve different tiny static markers using the same pinned Nginx runtime. This teaches release separation, health gates and routing evidence, not an application-image build pipeline. There is no database, migration, shared mutable state, real user traffic, TLS termination or production release. Keep both slots alive through the rollback window.

This is not a zero-downtime guarantee. Reloaded Nginx workers may coexist with draining old workers; long-lived connections, background jobs, cache state and schema compatibility need separate application design. A local green probe does not certify those behaviors.

Open the public-values form and apply one new lowercase project prefix, a new absolute lab directory and three distinct unprivileged TCP ports. Derived project names end in -blue and -green. All published addresses stay fixed to 127.0.0.1; this guide intentionally provides no public bind-address field.

Values remain in this tab for the selected tutorial/language/environment. Pending or invalid edits disable copying until Apply or Reset. Enter no registry credential or application secret. The checks below reject existing project containers/networks and the lab directory; a port can still be claimed by another process after inspection, so a later bind error is a stop, not permission to kill that process.

Blue and the gateway belong to one project, but only the gateway joins the external green network. The project-specific blue-app alias prevents the proxy from confusing identical service names across networks. The gateway healthcheck proves only that Nginx can serve its own readiness location; the blue dependency is a startup gate, not continuous routing control.

Each bind directory has one container owner and uses a private Z label when SELinux is active. No directory is shared between blue/green containers. Do not apply Z to system directories or existing content. Docker port publishing can affect host firewall rules even with loopback bindings; use the approved disposable daemon and keep its manager configuration intact.

services:
  blue:
    image: nginx:stable-alpine@sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
    restart: "no"
    ports:
      - "127.0.0.1:18081:80"
    volumes:
      - ./blue:/usr/share/nginx/html:ro,Z
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O - http://127.0.0.1/healthz | grep -qx BLUE_READY"]
      interval: 2s
      timeout: 2s
      retries: 10
    networks:
      default:
        aliases: [blue-app]
  gateway:
    image: nginx:stable-alpine@sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
    restart: "no"
    ports:
      - "127.0.0.1:18080:80"
    volumes:
      - ./proxy:/etc/nginx/conf.d:ro,Z
    depends_on:
      blue:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O - http://127.0.0.1/gateway-ready | grep -qx PROXY_READY"]
      interval: 2s
      timeout: 2s
      retries: 10
    networks: [default, green]
networks:
  default: {}
  green:
    external: true
    name: academybg-green_default

Green has a separate Compose project, default bridge network, content directory and loopback port. Its healthcheck reads the same small local readiness endpoint, not the public gateway route. There is no cross-project depends_on: the later explicit gate checks green from both the host and the gateway network.

The first create operation will prepare this project and its network without starting green. That lets the blue gateway attach to the external network while blue still serves traffic. No database initialization or traffic switch occurs during create.

services:
  green:
    image: nginx:stable-alpine@sha256:0e52bd054126cdc040b1276c0af347aeb02a41b9cfe305d6094767ac30e97949
    restart: "no"
    ports:
      - "127.0.0.1:18082:80"
    volumes:
      - ./green:/usr/share/nginx/html:ro,Z
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O - http://127.0.0.1/healthz | grep -qx GREEN_READY"]
      interval: 2s
      timeout: 2s
      retries: 10
    networks:
      default:
        aliases: [green-app]
networks:
  default: {}

The active file initially selects this template. The route marker header identifies the selected proxy configuration, while /release identifies the backend response. Neither is a business transaction. Static upstream names resolve when Nginx loads configuration; changing a container IP later can require another controlled reload.

upstream demo_release {
    server blue-app:80;
}
server {
    listen 80;
    location = /gateway-ready {
        default_type text/plain;
        return 200 "PROXY_READY\n";
    }
    location / {
        proxy_pass http://demo_release;
        proxy_set_header Host $host;
        proxy_connect_timeout 2s;
        proxy_read_timeout 5s;
        add_header X-Demo-Route blue always;
    }
}

Only the upstream and visible demo route marker differ. The templates live under versions with a .route extension, outside Nginx’s top-level *.conf include. Do not create a second server file in the included directory or leave an editor backup ending in .conf.

upstream demo_release {
    server green-app:80;
}
server {
    listen 80;
    location = /gateway-ready {
        default_type text/plain;
        return 200 "PROXY_READY\n";
    }
    location / {
        proxy_pass http://demo_release;
        proxy_set_header Host $host;
        proxy_connect_timeout 2s;
        proxy_read_timeout 5s;
        add_header X-Demo-Route green always;
    }
}