Configuration Reference
All configuration is done through environment variables in the app/.env file (or via container environment variables).
Required Variables
| Variable | Description |
|---|---|
VAULT_ADDR | HashiCorp Vault server URL (e.g. http://vault:8200) |
At least one of the following is required for background services:
| Variable | Description |
|---|---|
VAULT_SYSTEM_TOKEN | Static Vault token for system operations |
VAULT_K8S_AUTH_ROLE | Kubernetes auth role name (preferred in K8s deployments) |
Application Settings
| Variable | Default | Description |
|---|---|---|
PORT | 3001 | HTTP port to listen on |
NODE_ENV | production | development or production |
VAULT_SKIP_TLS_VERIFY | false | Skip TLS certificate verification |
CORS_ORIGIN | — | Allowed CORS origin (only needed if frontend is on a different origin) |
Config Storage
VaultLens stores its own configuration (branding, webhooks, rotation schedules, AppRole credentials) in a local file backend (config.ini).
| Variable | Default | Description |
|---|---|---|
VAULTLENS_CONFIG_PATH | /config | Directory for config.ini and logo blobs |
VAULTLENS_BACKUP_PATH | /backups | Directory for backup JSON files |
Kubernetes Auth
| Variable | Default | Description |
|---|---|---|
VAULT_K8S_AUTH_ROLE | — | K8s auth role (replaces VAULT_SYSTEM_TOKEN) |
VAULT_K8S_AUTH_MOUNT | kubernetes | Vault Kubernetes auth mount path |
VAULT_K8S_TOKEN_PATH | /var/run/secrets/kubernetes.io/serviceaccount/token | Service account token path |
Rate Limiting
| Variable | Default | Description |
|---|---|---|
RATE_LIMIT_MAX | 500 | Max API requests per window (all /api/* routes) |
RATE_LIMIT_WINDOW_MS | 900000 | Rate limit window in ms (15 minutes) |
SHARING_RATE_LIMIT_MAX | 20 | Per-minute limit for the public sharing endpoint |
Audit & Webhooks
| Variable | Default | Description |
|---|---|---|
VAULT_AUDIT_LOG_PATH | — | Path to Vault audit log file (required for webhook notifications) |
System Token Resolution Order
VaultLens resolves the system token in this priority order:
- Kubernetes auth (
VAULT_K8S_AUTH_ROLE) — auto-renews at 75% TTL - AppRole — credentials generated by the setup wizard and stored encrypted in config storage
- Static token (
VAULT_SYSTEM_TOKEN) — fallback for simple deployments
Example: Minimal Docker Setup
bash
VAULT_ADDR=http://vault:8200
VAULT_SYSTEM_TOKEN=hvs.your-token-hereExample: Kubernetes Setup
bash
VAULT_ADDR=http://vault.vault.svc.cluster.local:8200
VAULT_K8S_AUTH_ROLE=vaultlens