Environment Variables
ArchVault is configured through environment variables. In Docker deployments, set these in your .env file (see .env.production.example). In development, use apps/web/.env.
Required
Section titled “Required”These must be set for ArchVault to start.
| Variable | Description |
|---|---|
BETTER_AUTH_SECRET | Secret key for session signing. Generate with openssl rand -base64 32. |
BETTER_AUTH_URL | Public URL where ArchVault is accessible (e.g. https://archvault.example.com). No trailing slash. |
DATABASE_URL | PostgreSQL connection string. In compose.prod.yaml, this is constructed automatically from the Postgres variables below. |
Database (Docker Compose)
Section titled “Database (Docker Compose)”Used by both the app and db services in compose.prod.yaml. The app service builds DATABASE_URL from these automatically.
| Variable | Default | Description |
|---|---|---|
POSTGRES_USER | archvault | PostgreSQL username. |
POSTGRES_PASSWORD | (required) | PostgreSQL password. |
POSTGRES_DB | archvault | PostgreSQL database name. |
Application
Section titled “Application”| Variable | Default | Description |
|---|---|---|
AUTO_MIGRATE | true | Run database migrations on container startup. Set to false to manage migrations manually. |
APP_VERSION | dev | Set automatically during Docker builds to the git commit SHA. |
DOMAIN | (empty) | Domain for the Traefik host rule (e.g. archvault.example.com). Required when using the built-in Traefik Compose profile. |
ACME_EMAIL | (empty) | Email for Let’s Encrypt certificate notifications. Required when using the built-in Traefik Compose profile. |
OAuth Providers
Section titled “OAuth Providers”Configure one or more OAuth providers for social login. A provider auto-enables when both its client ID and secret are set. Use the toggle variables to override this behavior.
| Variable | Default | Description |
|---|---|---|
GITHUB_CLIENT_ID | (empty) | GitHub OAuth app client ID. |
GITHUB_CLIENT_SECRET | (empty) | GitHub OAuth app client secret. |
GOOGLE_CLIENT_ID | (empty) | Google OAuth client ID. |
GOOGLE_CLIENT_SECRET | (empty) | Google OAuth client secret. |
MICROSOFT_CLIENT_ID | (empty) | Microsoft Entra ID client ID. |
MICROSOFT_CLIENT_SECRET | (empty) | Microsoft Entra ID client secret. |
MICROSOFT_TENANT_ID | common | Microsoft tenant ID. Use common for multi-tenant, or a specific tenant UUID. |
AUTH_SOCIAL_GITHUB_ENABLED | (auto) | Explicitly enable/disable GitHub OAuth. |
AUTH_SOCIAL_GOOGLE_ENABLED | (auto) | Explicitly enable/disable Google OAuth. |
AUTH_SOCIAL_MICROSOFT_ENABLED | (auto) | Explicitly enable/disable Microsoft OAuth. |
Email (SMTP)
Section titled “Email (SMTP)”Required for email verification, password resets, and organization invitations.
| Variable | Default | Description |
|---|---|---|
SMTP_HOST | (empty) | SMTP server hostname. |
SMTP_PORT | (empty) | SMTP server port (typically 587 for STARTTLS). |
SMTP_USER | (empty) | SMTP username. |
SMTP_PASS | (empty) | SMTP password. |
EMAIL_FROM | noreply@archvault.dev | Sender address for outgoing emails. |
Blocks Registry
Section titled “Blocks Registry”Used for the community blocks registry (Phase 5).
| Variable | Default | Description |
|---|---|---|
GITHUB_PAT | (empty) | GitHub personal access token for registry operations. |
REGISTRY_REPO | (empty) | GitHub repository for the blocks registry. |
OpenTelemetry (optional)
Section titled “OpenTelemetry (optional)”ArchVault supports OpenTelemetry for distributed tracing, metrics, and logs. These variables set the defaults — admin users can override most of them at runtime via the Admin Panel → Platform → Observability page.
SDK-level settings (endpoint, service name, auth, TLS) require a server restart after changing. Runtime settings (enabled, sample rate) take effect immediately when changed through the admin panel.
| Variable | Default | Description |
|---|---|---|
OTEL_ENABLED | false | Set to true to enable the OpenTelemetry SDK at startup. |
OTEL_SERVICE_NAME | archvault | The service name reported in traces, metrics, and logs. |
OTEL_EXPORTER_OTLP_ENDPOINT | (empty) | Base URL of your OTLP collector (e.g. https://otel.example.com:4318). The SDK appends /v1/traces, /v1/metrics, /v1/logs automatically. |
OTEL_EXPORTER_OTLP_HEADERS | (empty) | Comma-separated key=value pairs sent as headers (used when OTEL_AUTH_TYPE=custom_headers). |
OTEL_TRACES_SAMPLER | parentbased_traceidratio | Sampler type (standard OTel env var). |
OTEL_TRACES_SAMPLER_ARG | 1.0 | Sampling ratio (0.0–1.0). 1.0 = sample everything. |
OTEL_METRICS_EXPORT_INTERVAL | 60000 | How often metrics are flushed (milliseconds). |
OTEL_CONSOLE_EXPORTER | false | Set to true to also log spans to the server console (useful during development). |
OTEL_LOGS_ENABLED | false | Set to true to enable the OTLP logs pipeline. |
Authentication
Section titled “Authentication”ArchVault supports multiple authentication methods for OTLP exporters. Set OTEL_AUTH_TYPE and the corresponding variables for your chosen method.
| Variable | Default | Description |
|---|---|---|
OTEL_AUTH_TYPE | none | Auth method: none, custom_headers, bearer, basic, api_key, or mtls. |
OTEL_AUTH_BEARER_TOKEN | (empty) | Bearer token (used when OTEL_AUTH_TYPE=bearer). Sends Authorization: Bearer <token>. |
OTEL_AUTH_BASIC_USER | (empty) | Username for Basic Auth (used when OTEL_AUTH_TYPE=basic). |
OTEL_AUTH_BASIC_PASS | (empty) | Password for Basic Auth. Combined as Authorization: Basic base64(user:pass). |
OTEL_AUTH_API_KEY_HEADER | x-api-key | Header name for API key auth (used when OTEL_AUTH_TYPE=api_key). |
OTEL_AUTH_API_KEY_VALUE | (empty) | The API key value sent in the configured header. |
TLS / mTLS
Section titled “TLS / mTLS”These follow the standard OTel TLS env vars.
| Variable | Default | Description |
|---|---|---|
OTEL_EXPORTER_OTLP_CERTIFICATE | (empty) | Path to the CA certificate PEM file for verifying the collector’s TLS certificate. |
OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE | (empty) | Path to the client certificate PEM file for mTLS. |
OTEL_EXPORTER_OTLP_CLIENT_KEY | (empty) | Path to the client private key PEM file for mTLS. |
OTEL_TLS_INSECURE_SKIP_VERIFY | false | Set to true to skip TLS certificate verification. Not recommended for production. |
Auto-Instrumentation
Section titled “Auto-Instrumentation”The backend automatically instruments:
- HTTP — all incoming/outgoing HTTP requests (via
@opentelemetry/instrumentation-http) - PostgreSQL — all database queries through Drizzle/pg (via
@opentelemetry/instrumentation-pg) - DNS — DNS resolution lookups (via
@opentelemetry/instrumentation-dns)
Browser Telemetry
Section titled “Browser Telemetry”When OTel is enabled, the browser SDK automatically instruments page loads, user interactions, and fetch requests. Browser spans are sent through a server-side proxy (/api/telemetry) to avoid CORS issues and to keep collector credentials server-side.
OAuth2 Note
Section titled “OAuth2 Note”OAuth2 Client Credentials is a Collector extension (oauth2clientauthextension), not a JS SDK feature. To use OAuth2 authentication, deploy an OTel Collector with the OAuth2 extension as a proxy between ArchVault and your backend.