Provision

Prepare a server to host Vela apps. Any Debian-based host reachable over SSH can be used. Run this once per server, before the first deploy.

Syntax

$ vela provision <target>
$ vela provision root@example.com

The target is an SSH destination: an alias from ~/.ssh/config, or user@host. Provisioning is idempotent — running it again on a prepared server brings it up to date rather than starting over.

Options

  • -i, --identity <file> - SSH private key to authenticate with
  • --ssh-port <port> - SSH port
  • --accept-host-keys - Trust an unknown host key on first connect (CI)
  • --pb-version <version> - PocketBase version to install, defaults to the one this CLI develops against
  • --node-major <version> - Node.js major version to install, defaults to 22

Stack

Vela installs the following on the server:

  • Node.js
  • Caddy, with automatic HTTPS
  • PocketBase
  • systemd units for the app and the database

A system user vela is created to own and run the apps. Caddy gets an import /etc/vela/caddy/*.caddy line appended to its existing Caddyfile — an existing configuration is otherwise left alone, and the result is validated before Caddy is reloaded.

Layout

Apps live under /var/lib/vela, with configuration in /etc/vela:

/var/lib/vela/apps/<app>       releases and data, per app
/var/lib/vela/state            server-wide state: port assignments, one lock per target
/var/lib/vela/script-versions  the server scripts, one directory per CLI version
/var/lib/vela/trash            data removed by a purge, kept for two weeks
/etc/vela/apps                 environment files, readable only by root
/etc/vela/caddy                generated Caddy snippets, one per app

Each deployed target runs two systemd services, vela-web@ for the Node server and vela-pb@ for the database, on an internally assigned port. Several apps and several targets of the same app can share one server.

Requirements

For HTTPS to be provisioned automatically on deploy, the server must have a public IP address and the domain must point at it. This is what lets Caddy obtain certificates. Provisioning needs root, either directly or through sudo.