Why Neo? What Problem It Actually Solves

The itch this scratches

You have one VPS. You want to run an app on it, get HTTPS working, and not think about it again until you deploy the next change. Two paths tend to show up.

Do it by hand. docker run, an nginx config copied from the last project, certbot renew on a cron job you'll forget exists until a certificate expires on a weekend. It works, but every server ends up configured slightly differently, and "how did I set this up" becomes an exercise in reading your own shell history.

Reach for a platform. Kubernetes, or a PaaS with an agent running on the box, a control plane somewhere, and a dashboard you now depend on staying up. For a fleet of a hundred services that's the right call. For one app on a $6 VPS, it's a lot of machinery to keep patched for a problem you don't have.

What Neo actually is

Neo is a small Go binary that runs on your laptop. It doesn't install a daemon on your server, doesn't phone home to a control plane, and doesn't ask you to trust a new dashboard with access to your infrastructure. Every command it runs — deploying an app, checking status, reading logs — is a plain SSH connection to a machine you already administer, running Docker commands and talking to Caddy's local API.

You already trust SSH to manage this box. That's the whole security model Neo needs: nothing new to secure, nothing new to patch beyond Docker and Caddy themselves, and nothing that keeps working against you if some third-party account gets compromised somewhere you don't control.

What you get instead of the manual approach

Structure, without the platform. neo deploy builds your image, ships it, health-checks the new container, and only switches traffic to it once the new version proves it's alive — the same pattern you'd want to hand-roll, just done the same way every time instead of half-remembered from the last project. .neo.yml describes the deployment in your repo instead of in your head. HTTPS is automatic because Caddy handles it, not because you configured certbot correctly this time.

None of this is new technology running on the server — it's still Docker and Caddy, both boring, both things you could operate by hand if you had to. Neo just runs the same commands you'd type yourself, in the same order, every time, and writes down what it did.

Where this series goes

The next nine lessons install Neo, connect to a server, deploy something real, and build up a .neo.yml piece by piece. Nothing here assumes you've used Neo before — just SSH access to a server and something with a Dockerfile.

Next: Installing Neo and Activating Your License.