Frappe Vault Production Setup

Before you begin, ensure your server meets the following requirements:

Installation

  1. Set up a new bench:
bench init --frappe-branch version-15 {{ bench name }} --python ~/.pyenv/versions/3.10.12/bin/python3
  1. Create a new site:
cd {{ bench name }}
bench new-site {{ site name }} --force --db-name {{ site name }}
  1. Download the Frappe Vault application:
bench get-app frappe_vault [email protected]:agritheory/frappe_vault.git
  1. Install the app to your site:
bench --site {{ site name }} install-app frappe_vault

# Optional: Verify installation
bench --site {{ site name }} list-apps
  1. Set up OpenBao:
bench setup-openbao --production --site {{ site name }}

bench setup-openbao handles the full setup in one command:

  • Generates config/openbao.hcl (static auto-unseal), config/openbao-seal.key, and config/openbao-data/
  • Writes /etc/supervisor/conf.d/openbao.conf and reloads supervisor (uses sudo tee if not running as root)
  • Starts OpenBao via supervisor and waits for it to be ready
  • Initialises OpenBao and saves recovery keys to config/openbao-recovery-keys.txt (0600)
  • Enables the KV v2 secrets engine at secret/
  • Writes vault_url and vault_token to {{ site name }}/site_config.json (feature flags are not enabled automatically)

Security note: setup-openbao writes the root token directly to site_config.json for convenience. For production, replace it with a restricted policy token once the site is running — see OpenBao Token Policy below. You can also supply the token via environment variable instead:

[program:frappe-bench-frappe-web]
environment=BAO_TOKEN="bao.xxxxxxxxxxxxx"
  1. Set the admin password (will be stored in OpenBao):
bench --site {{ site name }} set-admin-password {{ secure password }}

Security Checklist

  • OpenBao is bound to localhost only (127.0.0.1:8200)
  • Static seal is configured for auto-unseal (see OpenBao Setup Guide)
  • Seal key is protected (env var in supervisor config, or file with 0600 permissions)
  • OpenBao token is provided via environment variable, not site_config
  • OpenBao audit logging is enabled
  • OpenBao token has minimal required permissions (see below)
  • Recovery keys are stored securely offline (for emergencies only)
  • External access uses Frappe proxy API (TLS via nginx)

OpenBao Token Policy

Create a restricted policy for the Frappe application:

# frappe-vault-policy.hcl
# Secrets are namespaced by site: secret/data/frappe/{site}/{doctype}/{name}/{fieldname}
# This policy allows access to all sites - for multi-tenant isolation, create site-specific policies
path "secret/data/frappe/*" {
  capabilities = ["create", "read", "update", "delete"]
}

path "secret/metadata/frappe/*" {
  capabilities = ["list", "delete"]
}

Apply the policy and create a token:

bao policy write frappe-vault frappe-vault-policy.hcl
bao token create -policy=frappe-vault -period=24h

Monitoring

Health Check

Add a health check endpoint to your monitoring:

curl -s http://localhost:8200/v1/sys/health | jq .

Audit Log Monitoring

Ensure OpenBao audit logs are being collected and monitored:

bao audit list

Backup Considerations

  • OpenBao data should be backed up separately from Frappe database
  • Seal key: If using file-based seal key (file://), include /etc/openbao/seal.key in backups
  • Recovery keys: Store recovery keys securely offline (encrypted, physically secure location)
    • Recovery keys are for emergencies only (seal key loss, disaster recovery)
    • With static seal, recovery keys are NOT needed for routine restarts
  • Test recovery procedures regularly

Seal Key Security Comparison

Storage MethodBackup NeededNotes
Environment variable (env://)Supervisor configKey in supervisor config, protect with 0600 permissions
File-based (file://)/etc/openbao/seal.keySeparate file, protect with 0600 permissions

Important: Anyone with access to the seal key can unseal OpenBao. Treat the seal key with the same security as the secrets it protects.

Troubleshooting

OpenBao Connection Errors

Check connectivity:

curl -s -H "X-Vault-Token: ${BAO_TOKEN}" http://localhost:8200/v1/sys/health

Authentication Failures

Verify token is valid:

bao token lookup

Missing Passwords After Migration

Check if password exists in either location:

# bench console
from frappe_vault.vault_client import get_vault_client

# Check database
Auth = frappe.qb.Table("__Auth")
db_result = (
    frappe.qb.from_(Auth)
    .select(Auth.star)
    .where(Auth.name == "Administrator")
    .run(as_dict=True)
)
print("In DB:", db_result)

# Check OpenBao
client = get_vault_client()
vault_result = client.get_secret("User", "Administrator", "password")
print("In OpenBao:", "Yes" if vault_result else "No")

Please contact us for corrections, additions, questions, or to request a topic.

© 2026 AgriTheory. All Rights Reserved.