Leveling Up .neo.yml: Workers, Volumes, and Multiple Environments

You've been using a small slice of the file

Everything so far — name, domain, port, env — covers a stateless app with no background jobs and one target server. Real projects usually need more. Here's what the rest of .neo.yml is for, briefly enough to know when to reach for each one.

workers: — background containers that share the app's image but run a different command, like a queue worker. Same env, same volumes, separate process.

sidecars: — separate containers with their own image, like Redis, running on the same Docker network as the app so they can reach each other by container name. Sidecars get their own env, not the app's.

volumes: — named Docker volumes or bind mounts, so data (uploads, a SQLite file, whatever) survives a redeploy instead of vanishing with the old container.

release: — one-off commands, like php artisan migrate --force, that run inside the new container after it passes its health check but before Caddy switches traffic to it. A failed release command aborts the deploy and leaves the old version serving — this is what makes automating migrations safe.

environments: — named blocks (staging, production, whatever you call them) that override the top-level config, so one .neo.yml can deploy the same project to multiple servers with different domains, secrets, and Dockerfiles.

Where to go deeper

Each of these has a full article once you need one: Setting Up Background Workers and Queues in .neo.yml, Persistent Volumes: Don't Lose Data on Redeploy, and Multi-Server Deployments: Environments and Server Groups. For the definitive field-by-field reference now that you understand why each section exists, see A Complete .neo.yml Reference Walkthrough.

Next: You've Finished Neo 101 — Here's the Rest of the Library.