Skip to main content
You’ll deploy examples/basic-http, a small Go web server, as a rootless container on your own server. Then you’ll redeploy it, roll it back, and remove it.

​
Before you start

  • Finish Installation: russel ps should work, from the server or from your laptop.

​
1. Deploy

The control plane clones the repo, reads the Russelfile that --config points at, builds the folder it sits in (examples/basic-http) with Nix, and starts it. Nothing is cloned on your side, so this works the same from a laptop. The first build takes a minute or two while Nix fetches Go; later deploys take about a second. When it finishes you’ll see something like:
The service is called api because that’s the name in the example’s Russelfile.

​
2. Check it

PORTS shows host port → app port. Call the app on the host port:
Note: Russel picks a free host port (3100 and up), and an update can move the app to a new one, so use russel ps to find it. For a name that stays the same, use Traefik ingress. To keep one port, pin it with [ingress].port.

​
3. Update and roll back

After the first deploy, use russel update to ship changes. --refresh builds the latest commit on the repo’s default branch:
You can’t push to the example repo, so here this rebuilds the same code. With your own app, you push a commit and then run the same command. Without --refresh, update rebuilds the commit that is already running, which is how you pick up a changed secret. An update starts the new version next to the old one and switches traffic once the new one answers, so the app keeps serving. The old version keeps running for 2 more seconds. If the new version fails to start, or crashes within those 2 seconds, traffic stays on (or goes back to) the old one and update exits non-zero. When a deploy counts as ready has the details. Go back to the previous version yourself:
Russel keeps the last 20 deployments. russel rollback api --version N picks an older one. More: Update and rollback.

​
4. Clean up

russel stop api stops the app but keeps its history, so a later update or rollback can bring it back. Restarting the control plane (sudo systemctl restart russel-ctrl) doesn’t stop your apps.

​
Deploy your own app

The server clones the repo itself, so this works the same from your laptop. After that, push a commit and run russel update my-app --refresh to ship it. For a private repo, see Single-VPS checklist: Deploy from git. Deploying a folder that is already on the server is off by default. It needs RUSSEL_ALLOW_LOCAL_PATH_DEPLOY=1 in /etc/russel/env; see First deploy. If your project has no flake.nix, Russel generates one for Rust (Cargo.toml), Go (go.mod), and static sites. russel init --with-flake writes a starter flake you can edit instead. See Builds and the Russelfile reference.

​
Next steps