# 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](/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`.