Configuration

CertVault reads YAML from /config/config.yaml by default. The reference file includes every supported section with annotated examples.

• View the full configuration reference
• Download the YAML file

Administrator authentication is required

When the web console is enabled, configure a bootstrap administrator token or OIDC so administrators can sign in. Before exposing CertVault to an untrusted network, configure and verify OIDC; if you retain bootstrap access for emergencies, protect it as a long, random secret. See the authentication guide.

Core settings

Setting	Purpose
data_dir	SQLite database and encrypted certificate storage
server.listen	HTTP listen address
server.public_url	Browser-visible origin and OIDC callback base
server.ui_enabled	Web console and browser authentication routes; defaults to true
server.log_level	debug, info, warn, or error
server.trusted_proxies	Proxy IP addresses or CIDRs trusted to supply client IP headers
audit.retention	Age after which audit events are deleted; omitted means indefinitely
auth.session_duration	Browser session lifetime; defaults to 8h
acme.email	ACME account contact address
acme.directory_url	ACME v2 directory
acme.accept_terms	Must be true
acme.automatic_issuance	Global automatic issuance switch
notifications.apprise_url	Apprise REST notification endpoint

Durations accept Go duration syntax and whole days, such as 12h, 30d, and 90d.

Certificates

certificates:
  - name: homelab-wildcard
    domains:
      - example.com
      - "*.example.com"
    key_type: ec256
    renew_before: 30d
    credential: cloudflare_main
    automatic_issuance: true
    enabled: true

Certificates default to enabled. After restarting with enabled: false or removing a certificate definition, CertVault hides it from certificate listings and returns 404 for its details, version history, downloads, and renewal requests. Initial, scheduled, and manual issuance are blocked. Stored artifacts, version history, and API-key permissions are retained; restoring an enabled definition with the same name restores access to its previous versions. Revoke existing API keys separately if their access should not return when the certificate is re-enabled.

Supported key types are ec256 (default), ec384, rsa2048, rsa3072, and rsa4096.

Environment overrides

Variable	Purpose
CERTVAULT_CONFIG	Configuration path
CERTVAULT_DATA_DIR	Persistent data directory
CERTVAULT_LISTEN	HTTP listen address
CERTVAULT_PUBLIC_URL	Browser-visible origin
CERTVAULT_UI_ENABLED	Enable or disable the web console and browser authentication routes
CERTVAULT_LOG_LEVEL	Logging level
CERTVAULT_ACME_EMAIL	ACME account email
CERTVAULT_ACME_DIRECTORY_URL	ACME directory
CERTVAULT_ACME_DNS_RESOLVERS	Comma-separated DNS-01 resolvers
CERTVAULT_MASTER_KEY	Base64-encoded 32-byte encryption key
CERTVAULT_MASTER_KEY_FILE	File containing the master key
CERTVAULT_SESSION_DURATION	Browser session lifetime, such as 8h or 1d
CERTVAULT_BOOTSTRAP_ADMIN_TOKEN	Bootstrap UI credential
CERTVAULT_BOOTSTRAP_ADMIN_TOKEN_FILE	File containing the bootstrap credential
CERTVAULT_OIDC_ISSUER_URL	OIDC issuer
CERTVAULT_OIDC_CLIENT_ID	OIDC client ID
CERTVAULT_OIDC_CLIENT_SECRET	OIDC client secret
CERTVAULT_OIDC_CLIENT_SECRET_FILE	File containing the OIDC client secret
CERTVAULT_OIDC_SCOPES	Comma-separated OIDC scopes; must include openid
CERTVAULT_OIDC_ALLOWED_GROUPS	Comma-separated administrator groups
CERTVAULT_APPRISE_URL	Apprise REST notification endpoint
CERTVAULT_APPRISE_URLS	Comma-separated inline Apprise delivery URLs
CERTVAULT_APPRISE_TAGS	Comma-separated Apprise routing tags

Do not set both a direct secret and its _FILE counterpart.

Bootstrap authentication is optional. Omit CERTVAULT_BOOTSTRAP_ADMIN_TOKEN, CERTVAULT_BOOTSTRAP_ADMIN_TOKEN_FILE, and auth.bootstrap_token_file to disable it. Configure OIDC if administrators still need web-console access.

See Notifications for Apprise setup and delivery behavior.