Horizontal Scaling: Running Multiple Replicas Behind Caddy

Running more than one replica

name: api
port: 8080
scale: 3

Neo names the containers app-api-0, app-api-1, app-api-2, joins them to the same Docker network, and configures Caddy to load-balance across all three round-robin. From the outside, app.example.com is one address; underneath, three containers share the load.

Deploys stay zero-downtime

A redeploy with scale: 3 starts three new -next containers, waits for all three to pass health checks, then switches Caddy to the new set and removes the old one — the same blue-green guarantee as a single-container app, just applied to the whole replica set at once.

The one thing that's different: release:

Release commands run once, in the first new replica, not once per replica. Three containers all running php artisan migrate --force concurrently against the same database is exactly the race condition you don't want — Neo picks one and the other replicas simply start once it's confirmed healthy.

Changing replica count

neo deploy   # scale: in .neo.yml already changed — this applies it

Editing scale: and redeploying adds or removes replicas the same way any other config change is picked up — no separate scaling command needed.

Per-environment scale

scale: 1

environments:
  production:
    scale: 3   # overrides the top-level value for this environment only

A staging environment can run a single replica while production runs several, from the same .neo.yml.