Skip to main content
This is the path Russel v0.1 is built for: one person, one Linux VPS, apps running as rootless containers, deployed from a laptop over SSH. Tick the boxes as you go. Russel trusts whoever holds the API token completely. It is not built for sharing a server between people or teams.

​
1. The server

  • Linux x86_64 with systemd; Debian 12 or Ubuntu 22.04+ is easiest. No KVM needed.
  • We suggest 2 GB of RAM and 20 GB of disk or more. Nix builds and the Nix store take most of the disk.
  • An ordinary login user with sudo. The installer adds a separate russel account that runs everything; your user only needs sudo to install.
  • Firewall: allow SSH, plus 80 and 443 if you’ll serve web apps. Never open 7878, the control plane port.

​
2. Install

  • Follow Installation steps 1 and 2 on the server: Podman, Nix, install.sh check, then sudo install.sh host.
  • Log out and back in, so your user’s new russel group membership applies.
  • Check it’s running:

​
3. Connect from your laptop

  • Install the CLI on the laptop, copy the token, and open the tunnel:
  • Open http://127.0.0.1:7878/ on the laptop for the dashboard, and paste the token into Settings.
Rather use HTTPS than a tunnel? See TLS reverse proxy.

​
4. Deploy from git

A remote control plane can’t see your laptop’s files, so deploy from a git URL. The server clones and builds it:
These commands assume the app’s Russelfile says name = "app". For a private repo, use an ssh:// or git@host:path URL, and put a read-only deploy key for it in /var/lib/russel/.ssh/ (owned by russel, mode 0600). That is the home directory of the account that clones. Leave RUSSEL_ALLOW_LOCAL_PATH_DEPLOY off on a VPS you deploy to remotely.

​
5. Put apps on the internet

Russel publishes each app on a 127.0.0.1 port on the server, so nothing is public until you choose. Pick one:
  • Traefik (recommended for web apps). Russel writes a Traefik route for each service, so app.example.com reaches the right app. Traefik can also get TLS certificates from Let’s Encrypt. See Traefik ingress.
  • Your own reverse proxy. Pin the port with [ingress] and port = 8080, and point Caddy or nginx at 127.0.0.1:8080. The pin holds across updates, rollbacks, and restarts. An update of a pinned service stops the old version before starting the new one, so there is a short gap.

​
6. Secrets and data

  • Store secrets on the server, never in the repo:
    Then reference them in the Russelfile as DB_PASSWORD = "secret://DB_PASSWORD" under [service.env]. See Env + secrets.
  • Keep app data in [[volumes]] so it survives redeploys. See the Russelfile reference.

​
7. Backups and upgrades

  • Back up /etc/russel/env (your token) and /var/lib/russel (secrets, volumes, deployment history). Both need sudo to read.
  • Upgrade by re-running the installer with a new RUSSEL_VERSION. See Installation: Upgrade and Upgrades + backups.

​
Good first apps

Every example except microvm-http runs as a container on a no-KVM VPS. Deploy one straight from the Russel repo by pointing --config at its Russelfile:
To change an example, copy its folder into a repo of your own and deploy that. All of them: Examples.

​
What v0.1 doesn’t do

  • Several users or teams on one server
  • More than one server
  • Managed databases: run Postgres or Redis as ordinary services instead
  • TLS in the control plane itself: use SSH or a reverse proxy