Environment Configuration

Dracory applications load configuration through internal/config.NewFromEnv. The loader initializes github.com/dracory/env, hydrates encrypted values when requested, and then validates the required keys before wiring the runtime configuration.

The flow is:

1. env.Load(".env") reads the plain .env file in the project root.
2. If ENVENC_USED is true, the loader derives a key from ENVENC_KEY_PRIVATE and hydrates secrets from .env.<APP_ENV>.vault (local file or embedded resource) using github.com/dracory/envenc.
3. Each configuration section is validated. Missing required variables cause the load to fail before the app boots.

Required .env Keys

Populate these keys before starting the application:

Key	Requirement
APP_HOST	Host interface the HTTP server binds to
APP_PORT	Port exposed by the HTTP server
APP_ENV	Environment name (e.g. development, production, testing)
APP_NAME, APP_URL, APP_DEBUG	Optional but recommended for metadata and logging
DB_DRIVER	One of sqlite, turso, postgres, mysql
DB_DATABASE	Database name or file path

When DB_DRIVER is not sqlite or turso, also provide DB_HOST, DB_PORT, DB_USERNAME, and DB_PASSWORD. SSL mode defaults to require; adjust at the database layer if needed. For turso and sqlite, SSL mode is not required.

Optional database keys: DB_DSN (direct DSN override), DB_PREFIX (table prefix), DB_DEFAULT_CONNECTION (default connection name for multi-connection setups).

CSRF Secret

The AUTH_CSRF_SECRET key is required in production and staging environments. If it is not set in those environments, configuration loading fails with a descriptive error. In other environments (development, local, testing), a random secret is generated automatically and a warning is logged. Set AUTH_CSRF_SECRET explicitly for persistent CSRF protection across restarts.

Login Methods

AUTH_LOGIN_METHODS is a comma-separated runtime environment key listing the enabled authentication mechanisms. The first entry is the primary method rendered at /auth/login; additional methods are offered as alternatives at method-specific routes such as /auth/password-login and /auth/magiclink-login. The deprecated singular AUTH_LOGIN_METHOD is still honoured as a fallback when AUTH_LOGIN_METHODS is not set. Supported values:

• otp (default) – in-house email one-time-password login.
• magiclink – in-house email magic-link login.
• password – in-house email/password login.
• authknight – delegates authentication to the external AuthKnight service.

Maintenance Mode

Maintenance mode can be toggled via environment variables:

• APP_MAINTENANCE_ENABLED – Set to true to enable maintenance mode.
• APP_MAINTENANCE_FILE_PATH – Path to a maintenance page file to serve when enabled.

Encrypted Secrets (EnvEnc)

To store secrets in an encrypted vault:

1. Set ENVENC_USED=true.
2. Provide ENVENC_KEY_PRIVATE – this is the password used to derive the working key.
3. Create .env.<APP_ENV>.vault with the encrypted values. The loader checks the file system first and then embedded resources (internal/resources).

If any of the above is missing, configuration loading fails early with a descriptive error. Testing environments skip vault hydration, so you do not need vault files when APP_ENV=testing.

See the Security & Secrets guide for a step-by-step walkthrough of creating and rotating vaults.

Feature Toggles

Dracory ships many optional stores and services. Database stores are toggled at compile time via the <name>StoreUsed constants in internal/config/stores_config.go (for example userStoreUsed, cmsStoreUsed, vaultStoreUsed). Some toggles introduce additional environment requirements that are validated during load:

• cmsStoreUsed = true ⇒ set CMS_STORE_TEMPLATE_ID.
• vaultStoreUsed = true ⇒ set VAULT_STORE_KEY.
• userStoreVaultEnabled = true ⇒ also set vaultStoreUsed = true and provide VAULT_STORE_KEY.
• LLM providers are enabled via env flags (ANTHROPIC_API_USED, GEMINI_API_USED, OPENAI_API_USED, OPENROUTER_API_USED, VERTEX_AI_API_USED) and require the associated API key and default model variables. Stripe requires STRIPE_KEY_PRIVATE and STRIPE_KEY_PUBLIC. Missing dependencies are reported during load.

Review internal/config/stores_config.go for the full list of store toggles and internal/config/constants.go for the env key names.

Local Development Checklist

1. Copy .env.example to .env.
2. Fill in the required keys and any optional toggles you plan to use.
3. For encrypted secrets, generate .env.<APP_ENV>.vault with envenc tooling.
4. Run task dev-init (or task dev) to bootstrap the application. The task fails fast if configuration validation does not pass.

Troubleshooting

• Configuration load failed – read the error returned by config.NewFromEnv; it lists the missing key reported by the accumulator in internal/config.
• Vault hydration errors – confirm ENVENC_KEY_PRIVATE is correct and the vault file exists either on disk or embedded.
• Database connection errors – verify non-sqlite/turso drivers have host, port, username, and password configured.
• CSRF secret error in production – set AUTH_CSRF_SECRET in your .env or environment.

Keeping .env files out of version control and managing vault passwords securely are still best practices; however, the mechanics above reflect how the loader operates today.