What .neo.yml Is, and Why You Want One

What lesson 4 left out

neo deploy with zero configuration works — you saw that. But the domain, port, and everything else about that deployment then live only in /etc/neo/state.json on the server, not in your repository. That's fine for a first test. It stops being fine the moment you want a second person, a CI pipeline, or future-you to know how the app is supposed to be deployed without SSHing in to check.

The fix: commit a .neo.yml

A minimal one is genuinely small:

name: my-app
domain: app.example.com
port: 3000

Every field is optional, and Neo falls back to a sensible default for anything you leave out — the directory name for name, the Dockerfile's EXPOSE for port. What changes is that these decisions now live in a file next to your Dockerfile, get reviewed in a pull request like any other config change, and reproduce the same deployment from a fresh clone.

Don't write it by hand

neo config init

scaffolds a commented starter file interactively — it asks a few questions and writes the answers. If you already have a docker-compose.yml:

neo config generate

reads it and produces a matching .neo.yml, warning about anything it couldn't carry over (bind mounts, extra env_file entries, that kind of thing).

Why this lesson is the hinge

Everything from here — real domains, environment variables and secrets, redeploys, workers, multiple environments — is a change to this one file, followed by neo deploy. Lessons 6 through 9 add to it piece by piece rather than introducing new commands. For the complete mental model of every field it supports, see Understanding .neo.yml: The File That Actually Describes Your Deployment — this lesson only needed to convince you it's worth having.

Next: Pointing a Real Domain at Your App (With Free HTTPS).