Configuration

Vardo uses a layered configuration system. Settings resolve in this order:

1. vardo.yml (and vardo.secrets.yml) — highest priority, overrides everything
2. DB system_settings — set via the admin UI, stored encrypted in PostgreSQL
3. Hardcoded defaults — sensible values that work out of the box

Only a handful of environment variables remain as infrastructure connections. Everything else — email, GitHub, feature flags, instance name — is managed via config files or the admin UI.

Environment variables

Copy .env.example to .env and fill in the values. The install script generates .env automatically for production.

Core (required)

Encryption (required)

Instance identity

TLS (production)

Provider restrictions (optional)

These environment variables control which provider types are allowed on the instance. All default to true if unset.

Analytics (optional)

vardo.yml — config as code

Place a vardo.yml file in your Vardo install directory (or wherever VARDO_CONFIG_DIR points) to configure system settings as code. This file takes priority over anything in the DB.

For secrets (API keys, passwords, private keys), use a separate vardo.secrets.yml file. It gets 0600 permissions automatically. The vardo.yml file is safe to version-control; the secrets file isn't.

File layout

vardo.yml structure

instance:
  name: "My Vardo"
  domain: "host.example.com"
  baseDomain: "example.com"
  serverIp: "1.2.3.4"

auth:
  registrationMode: closed   # closed | open | approval
  sessionDurationDays: 7

email:
  provider: mailpace          # smtp | mailpace | resend | postmark
  fromEmail: [email protected]
  fromName: Vardo

backup:
  type: s3                    # s3 | r2 | b2 | ssh
  bucket: my-backups
  region: us-east-1
  endpoint: https://s3.amazonaws.com  # optional, for S3-compatible providers

github:
  appId: "12345"
  appSlug: my-vardo-app
  clientId: Iv1.abc123

features:
  mesh: true
  passwordAuth: false

vardo.secrets.yml structure

encryptionKey: "..."       # ENCRYPTION_MASTER_KEY equivalent
authSecret: "..."          # BETTER_AUTH_SECRET equivalent
acmeEmail: [email protected]

email:
  apiKey: "..."            # Mailpace or Resend API key
  smtpPass: "..."          # SMTP password (if provider is smtp)

backup:
  accessKey: "..."
  secretKey: "..."

github:
  clientSecret: "..."
  privateKey: "..."        # PEM private key (base64 ok)
  webhookSecret: "..."

How config gets imported

On startup, Vardo reads vardo.yml and vardo.secrets.yml and merges them. The merged config takes priority over all DB system_settings. You can also import a config file into the DB via the admin UI — this copies all sections into system_settings, making them editable through the UI while the file is removed.

Config is cached in memory for 30 seconds. Changes to the files take effect within one cache TTL.

AES-256-GCM encryption

Sensitive settings stored in the database (env vars, deploy keys, system settings) are encrypted at rest using AES-256-GCM. The ENCRYPTION_MASTER_KEY env var provides the key material.

Feature flags

Feature flags control which capabilities are available system-wide. All flags default to enabled. Set a flag to false in vardo.yml (under features:) or toggle it in the admin UI.

Resolution: vardo.yml > DB system_settings > default (true).

Core features — projects, apps, deployments — can't be disabled. Metrics and logs are always available.

Feature flags gate both UI tabs and their corresponding API endpoints.

Example — enforce passkey/OAuth only

features:
  passwordAuth: false

Template format

Templates are TOML files in the templates/ directory. Each file defines a deployable service with sensible defaults.

Example: PostgreSQL

version = "1"
name = "postgres"
displayName = "PostgreSQL"
description = "Powerful open-source relational database"
icon = "https://cdn.simpleicons.org/postgresql/4169E1"
category = "database"
source = "direct"
deployType = "image"
imageName = "postgres:16"
defaultPort = 5432

[[envVars]]
key = "POSTGRES_PASSWORD"
description = "Superuser password"
required = true

[[envVars]]
key = "POSTGRES_USER"
description = "Superuser name"
required = false
defaultValue = "postgres"

[[envVars]]
key = "POSTGRES_DB"
description = "Default database name"
required = false
defaultValue = "postgres"

[[volumes]]
name = "data"
mountPath = "/var/lib/postgresql/data"
description = "PostgreSQL data files"

[[connectionInfo]]
label = "Connection URL"
value = "postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${project.name}:5432/${POSTGRES_DB}"

Template fields

[[envVars]] — default environment variables

[[volumes]] — default persistent volumes

[[connectionInfo]] — connection metadata

Shown in the app's Connect tab after deployment.

Docker Compose profiles

The dev environment uses docker-compose.override.yml to customize the stack:

• The host service is disabled (use pnpm dev for hot reload instead)
• PostgreSQL exposed on port 7100
• Redis exposed on port 7200
• cAdvisor exposed on port 7300
• Loki exposed on port 7400
• Traefik runs with an insecure dashboard on port 8080 (no TLS, no BasicAuth)

In production, the base docker-compose.yml runs with --env-file .env. All services communicate over the internal vardo-network Docker network and only Traefik exposes ports 80 and 443 to the host.