Configuration Overview

Alta VMS reads config.yaml from its working directory, then overlays environment variables on top. Environment variables always win over file values, so secrets can stay out of the config file.

When installed via altavms install, the working directory is /etc/altavms/ and the service loads:

• /etc/altavms/config.yaml — non-secret settings
• /etc/altavms/altavms.env — secrets, loaded as environment variables by systemd

A missing config.yaml is fine — the server falls back to built-in defaults (development mode, port 3303, database at ./data/altavms.db).

Environment selection

The env value (development, staging, or production) changes validation strictness:

Behaviour	development	production
CORS allowed_origins	wildcard / empty allowed	concrete origins required
jwt_secret	optional (ephemeral)	required
Encryption key	optional (stub)	required
Security headers / strict CSP	relaxed	enforced

Required in production

A production deployment must provide three things (the installer generates all three automatically):

/etc/altavms/altavms.env

ALTAVMS_ENCRYPTION_KEY=<base64 32 bytes>     # openssl rand -base64 32
ALTAVMS_AUTH_JWT_SECRET=<base64 32 bytes>    # openssl rand -base64 32
ADMIN_BOOTSTRAP_EMAIL=admin@localhost
ADMIN_BOOTSTRAP_PASSWORD=<password>

And concrete CORS origins in config.yaml:

env: production
http:
  allowed_origins:
    - "https://vms.example.com"

Behind a reverse proxy

When Alta VMS sits behind a TLS-terminating proxy (nginx, Caddy, Traefik), set http.tls_enabled: true so it emits HSTS, and make sure the proxy forwards the original Host and the WebSocket/SSE upgrade headers. The Alta server’s WHEP callback origin is derived from the request origin used when you add the server, so add it through the same public URL your users will use.

Database & migrations

The database is SQLite (WAL mode). Schema migrations run automatically on every startup — there is no separate migrate step. Keep /var/lib/altavms/ on durable storage and include it in backups.

See the full reference for every option and its environment variable.