Vault variables¶

Every secret the stack needs lives in Ansible Vault (ansible/inventory/group_vars/all/vault.yml), one vault_<name> key per secret, each individually encrypted (ansible-vault encrypt_string) rather than the whole file. vault.yml.example is the template listing every key a production deploy needs, with a CHANGEME placeholder value.

Every key follows the same indirection: vault_<name> in the vault file becomes a plain variable <name> in group_vars/swarm_managers.yml (or group_vars/all/vars.yml for the couple that aren't manager-only), guarded with | default('') so an unset secret renders empty rather than breaking templating. See Configuration for how that layering works, and each service's own page for exactly how its variables reach the running container (Swarm secret file vs. plain env var).

Source vs. generate. Two kinds of value:

external — comes from outside this repo (an API token, an SMTP password) and must be obtained from that system.
generate — an arbitrary secret this repo invents; safe to generate with openssl rand -hex 32 or similar, the specific value doesn't matter to anything outside this stack.

Setting a value¶

cd ansible
ansible-vault encrypt_string --name vault_<name> 'the-real-value'
# paste the resulting `vault_<name>: !vault |` block into
# inventory/group_vars/all/vault.yml

Or edit the whole file in place: ansible-vault edit inventory/group_vars/all/vault.yml.

vault.yml.test (git-ignored, plaintext) holds a full set of generated test-only values for the disposable test Proxmox host, loaded as an extra-vars overlay (-e @inventory/group_vars/all/vault.yml.test) rather than being the real vault. Never treat its values as production secrets, and never commit it.

Infrastructure¶

Required for any provision-vms.yml run.

Variable	Kind	Purpose
`vault_proxmox_api_host`	external	Proxmox API host/IP
`vault_proxmox_api_user`	external, default `root@pam`	Proxmox API user
`vault_proxmox_api_token_id`	external	Proxmox API token ID
`vault_proxmox_api_token_secret`	external	Proxmox API token secret
`vault_sysadmin_password`	generate	Cloud-init VM user (`sysadmin`) password

Core stack (traefik, authentik, vaultwarden, gitea)¶

Variable	Kind	Purpose
`vault_cloudflare_dns_api_token`	external	Traefik's DNS-01 challenge (Cloudflare DNS-edit scope)
`vault_authentik_secret_key`	generate	Authentik's internal secret key
`vault_authentik_postgres_password`	generate	Authentik's Postgres password
`vault_authentik_bootstrap_password`	generate	Initial `akadmin` password
`vault_authentik_bootstrap_token`	generate	Initial Authentik API token
`vault_authentik_saml_signing_cert`	external, PEM block	Shared SAML signing certificate (kimai, snipe-it, fleet)
`vault_authentik_saml_signing_key`	external, PEM block	Shared SAML signing private key
`vault_vaultwarden_postgres_password`	generate	Vaultwarden's Postgres password
`vault_vaultwarden_admin_token`	generate	Vaultwarden admin panel token
`vault_vaultwarden_oidc_client_secret`	generate	Vaultwarden's Authentik OIDC client secret
`vault_gitea_postgres_password`	generate	Gitea's Postgres password
`vault_gitea_secret_key`	generate	Gitea's internal secret key
`vault_gitea_oidc_client_secret`	generate	Gitea's Authentik OIDC client secret

Apps tier¶

Variable	Kind	Purpose
`vault_mealie_oidc_client_secret`	generate	Mealie's Authentik OIDC client secret
`vault_duplicati_settings_encryption_key`	generate	Encrypts Duplicati's settings database
`vault_duplicati_ui_password`	generate	Duplicati web UI login
`vault_firefly_postgres_password`	generate	Firefly-III's Postgres password
`vault_firefly_app_key`	generate, exactly 32 characters	Laravel app key
`vault_kimai_db_password`	generate	Kimai's MariaDB password
`vault_kimai_app_secret`	generate	Symfony app secret
`vault_kimai_admin_password`	generate	Initial Kimai admin password
`vault_matomo_db_password`	generate	Matomo's MariaDB password
`vault_matomo_oidc_client_secret`	generate	Configured post-deploy via the LoginOIDC plugin UI, not read by the stack itself
`vault_netbox_db_password`	generate	NetBox's Postgres password
`vault_netbox_secret_key`	generate, at least 50 characters	Django secret key
`vault_netbox_superuser_password`	generate	Initial NetBox superuser password
`vault_netbox_oidc_client_secret`	generate	NetBox's Authentik OIDC client secret
`vault_paperless_db_password`	generate	Paperless-ngx's Postgres password
`vault_paperless_secret_key`	generate	Django secret key
`vault_paperless_admin_password`	generate	Initial Paperless-ngx admin password
`vault_paperless_oidc_client_secret`	generate	Paperless-ngx's Authentik OIDC client secret
`vault_immich_db_password`	generate	Immich's Postgres password
`vault_immich_oidc_client_secret`	generate	Immich's Authentik OIDC client secret

Appliances and shared services¶

Variable	Kind	Purpose
`vault_pihole_web_password`	generate	Pi-hole web UI login
`vault_smtp_password`	external	Shared outbound SMTP relay password
`vault_mqtt_password`	generate	Zigbee2MQTT's MQTT broker password (must match the Home Assistant Mosquitto add-on's own config)

Deferred (media/experimental tier)¶

Not part of the current deploy — populate before swarm-media is brought online and deploy_stack_tiers includes media/experimental.

Variable	Kind	Purpose
`vault_linkding_oidc_client_secret`	generate	Linkding's Authentik OIDC client secret
`vault_linkding_superuser_password`	generate	Initial Linkding superuser password
`vault_nagios_admin_password`	generate	Nagios admin login
`vault_snipeit_db_password`	generate	Snipe-IT's MariaDB password
`vault_snipeit_app_key`	generate, Laravel `base64:`-prefixed	Snipe-IT app encryption key
`vault_fleet_mysql_password`	generate	Fleet's MySQL password
`vault_fleet_server_private_key`	generate, exactly 32 bytes	Fleet server private key
`vault_openproject_secret_key_base`	generate, long hex string	Rails secret key base
`vault_openproject_admin_password`	generate	Initial OpenProject admin password
`vault_openproject_oidc_client_secret`	generate	OpenProject's Authentik OIDC client secret

Current state of the live vault¶

Only three of these keys are populated in the live, encrypted inventory/group_vars/all/vault.yml, all Proxmox-related: vault_proxmox_api_host, vault_proxmox_api_token_id, vault_proxmox_api_token_secret — the values for the disposable test Proxmox host. Every other key defaults to empty, so a real deploy of the core/apps stacks will not authenticate anything until they are set (tracked in the STATUS.md "Before first deploy" checklist).

vault_sysadmin_password is currently stored as a plain, unencrypted value (testpass) in that file, unlike its neighbours which use !vault blocks — confirm this is intentional for the disposable test host before treating it as vault-protected, and encrypt it with ansible-vault encrypt_string before this stack is used against anything that matters.