Concepts

Concepts

Three nouns. Everything in the tool is one of them or an operation on one.

VM

A machine you already own. Registering one records its host, SSH user, port and the path to a private key.

baryovm vm add oracle --host 203.0.113.10 --user opc --key ~/.ssh/id_ed25519
baryovm vm ping oracle

BaryoVM never reads the key. It hands the path to the SSH client, the same way your own ssh does.

vm bootstrap installs Docker if it is absent. vm harden applies an SSH hardening policy. vm threats reports what has been attacking the machine. vm exec <name> -- <command> runs a one-off command on it over the same key; there is no --sudo flag, so put sudo -n in the command.

The first connection records the VM's SSH host key in ~/.baryovm/known_hosts, and every later connection must match it. A changed key stops the command, because a rebuilt VM and someone else answering on that address look the same from here. vm forget-key <name> drops one recorded key after a rebuild. In CI, set BARYOVM_STRICT_HOST_KEYS=1 (or pass --strict-host-keys) so an unknown host is refused instead of learned, and pin the key before the job runs.

Stack

A Docker Compose project in a directory on a VM. Registering a stack says where that directory is, and optionally how to back it up and how to release into it.

baryovm stack add app --vm oracle --path /opt/app \
  --db-container app-postgres-1 --db-name app --env-file .env

Field	What it is for
--path	the compose project directory on the VM
--db-container, --db-name	what a backup dumps before anything changes
--env-file	a config file copied into the backup alongside the dump
--sudo	run this stack's remote commands as root, for a root-owned directory or .env
--release-file	the release manifest, see below

--sudo, and what changes with it

Intended for a stack whose .env or deploy root is root-owned, which is a reasonable posture for a file holding a database password. It covers compose, docker, the backup's dump and .env copy, and a release's image builds, hooks and remote rsync.

Three consequences worth knowing before you turn it on:

• The receiving rsync runs as root, so -a starts honouring -o and -g, and synced files can arrive with the local source's ownership rather than the SSH user's.
• Hooks run under a root shell, so sudo's env_reset and secure_path apply: $PATH is root's and $HOME is /root, so a hook calling a per-user tool needs its absolute path.
• The SSH user needs sudo rights to run a shell, not only the individual programs. A sudoers line granting one command passwordless refuses the whole hook with "a password is required", which reads like a password problem and is a permissions one.

All sudo is sudo -n. Under -o json there is no terminal to answer a prompt, so a bare sudo would hang until the session timed out.

Release

A release manifest is JSON describing how source becomes a running stack: what to sync, what to build, what to run before and after, and how to verify.

{
  "localRoot": ".",
  "remoteRoot": "/opt/app",
  "sudo": false,
  "builds": [{ "context": "api", "dockerfile": "api/Dockerfile", "tag": "app-api:latest" }],
  "preDeploy":  ["docker system prune -f"],
  "postDeploy": ["nginx -t && systemctl reload nginx"],
  "verify":     ["grep -q MODE=prod .env"],
  "healthUrl":  "http://127.0.0.1:8080/health"
}

stack release then, in order: backs up the database, syncs localRoot to remoteRoot, runs preDeploy, builds the images on the VM, brings the stack up, runs postDeploy, and verifies.

Building on the VM is deliberate: no registry to run, no images pushed across your uplink, and the build sees the same architecture it will run on.

Updates, and the rules around unattended ones

stack update pulls newer images and recreates only if something actually changed, so a nightly job is not a nightly restart. If the health check fails afterwards it puts the previous images back.

--auto is the form a scheduler runs, and it refuses four things, all for the same reason: an unattended update must be able to tell a healthy start from a crash loop, and to go back when it cannot.

• a stack not marked autoUpdate
• a stack with no healthUrl
• --auto together with --no-backup
• a stack with no database backup configured at all

A stack that genuinely has no database says so once, deliberately:

baryovm stack set-update app --no-database

A --dry-run is exempt from the backup refusals, since it recreates nothing.