Docker Swarm

Docker Swarm is the recommended high-availability deployment for Docker environments. Swarm’s ingress routing mesh provides VIP load balancing and automatic failover without keepalived, and the stack file (docker-swarm.yml) declares replica counts, placement constraints, and health checks.

When to use Swarm

For a single-host non-HA deployment, the Quick Start Docker Compose flow is simpler. For Kubernetes, see Kubernetes.

Prerequisites

• A Linux host (or cluster) with Docker Engine and Swarm mode initialized
• Ports 80, 443, 3000, 8000, 8404 available (configurable)
• For multi-node: a container registry reachable from all nodes, or images manually loaded on each node

1. Initialize the Swarm

On the manager node:

docker swarm init

If you have multiple network interfaces, specify the advertise IP:

docker swarm init --advertise-addr <manager-ip>

Join worker nodes using the token printed by docker swarm init:

docker swarm join --token <worker-token> <manager-ip>:2377

Retrieve the join token later with docker swarm join-token worker.

2. Configure Environment

Copy the example environment file and edit it:

cp .env.example .env

At minimum set the secrets (SECRET_KEY, ADMIN_PASSWORD, DATAPLANE_API_PASSWORD). For HA, also set:

HA_ENABLED=true
SWARM_MODE=true

See the Quick Start environment reference for the full variable list, including the Swarm-specific section.

3. Make Images Available

Images must be present on every node that will run a replica. Either:

Option A — Use a registry (recommended for multi-node):

docker tag corex-api:latest registry.example.com/corex-api:v1.0
docker push registry.example.com/corex-api:v1.0
# Set in .env:
#   SWARM_API_IMAGE=registry.example.com/corex-api:v1.0
#   SWARM_HAPROXY_IMAGE=registry.example.com/corex-haproxy:v1.0
#   SWARM_FRONTEND_IMAGE=registry.example.com/corex-frontend:v1.0

Option B — Load images on each node manually:

# On the build node:
docker save corex-api:latest corex-haproxy:latest corex-frontend:latest | gzip > corex-images.tar.gz
# Transfer and load on each Swarm node:
docker load < corex-images.tar.gz

4. Deploy the Stack

Single-node Swarm

docker stack deploy -c docker-swarm.yml corex

Multi-node Swarm with HA (via deploy.py)

The deploy.py script handles rsync, selective rebuilds, and docker stack deploy:

python3 deploy.py --target swarm \
  --host <manager-ip> --user admin \
  --stack-name corex \
  --registry registry.example.com \
  --image-tag v1.0

Manual HA stack deploy

# Ensure HA_ENABLED=true and SWARM_MODE=true in .env, then:
docker stack deploy -c docker-swarm.yml corex

5. Verify the Stack

docker stack services corex       # list services and replicas
docker stack ps corex              # list tasks (per-replica status)
docker service logs corex_api      # view API logs

All services should show REPLICAS as x/x (e.g. 2/2). A 0/x replica count or FAILED task state indicates a scheduling or health-check failure — inspect with docker service ps --no-trunc <service>.

HA Behavior

When HA_ENABLED=true + SWARM_MODE=true:

Adjust replica counts in .env (the SWARM_*_REPLICAS variables) and redeploy.

Service URLs

After deployment, the services are available at:

With the ingress mesh, any Swarm node accepts traffic on the published ports and routes to a healthy replica. The peer port (10000) uses endpoint_mode: dnsrr so HAProxy instances discover each other directly for stick-table sync.

Managing the Stack

docker stack services corex       # list services
docker stack ps corex             # list tasks
docker service logs corex_api     # view logs
docker service scale corex_corex=3   # scale HAProxy to 3 replicas
docker stack rm corex              # remove the stack

Deploy Script Options

The deploy.py Swarm-specific options:

The script shares the same selective-rebuild change detection as the Docker target: a manifest of file hashes is compared against the last deploy, and only services whose files changed are rebuilt. See deploy.md in the corex_manager repo for full details.

Next Steps

• Kubernetes — Deploy via the Helm chart
• Listeners & Backends — Configure TLS, HTTP/2, QUIC, and load balancing
• Metrics & Logging — Monitor the HAProxy and WAF dashboards
• Audit & Snapshots — Track changes and revert config