VelvetCMS Docs LATEST

Environment & Secrets

Tune env variables for each stage (local, staging, production).

Category: Configuration

Quick reference #

Key Effect
APP_ENV Informational environment label used by commands (e.g., migrate warns if set to production).
APP_DEBUG Enables verbose exception output (HTML+JSON stack traces). Always false in production.
APP_URL Base URL injected into theme variables and link helpers.
APP_NAME Appears in templates, CLI greetings, and meta tags.
DB_CONNECTION, DB_DATABASE, DB_HOST, DB_USERNAME, DB_PASSWORD Configure the active database connection as defined in config/db.php.
CACHE_DRIVER, CACHE_PREFIX Select cache backend (file, redis, …) and namespace keys per deployment.
CONTENT_DRIVER Choose file, db, hybrid, or auto for the page pipeline.
THEME Overrides config/theme.php’s active value so tenants can pick different themes.
SESSION_* Control cookie name, lifetime, SameSite/Secure flags (see config/session.php).
REDIS_* Host, port, password for Redis-backed cache/session drivers.

Cache & sessions #

  • CACHE_DRIVER: file (default) or redis. Provide Redis host/port/password via REDIS_* env keys defined in config/cache.php.
  • CACHE_PREFIX: differentiate multiple deployments sharing the same backend.
  • SESSION_LIFETIME, SESSION_COOKIE, SESSION_SECURE_COOKIE: control session persistence + cookie flags.

Database #

Pick a connection via DB_CONNECTION (sqlite/mysql/pgsql). Each driver honors its own env keys (see config/db.php). CLI commands use the same connection object—the diagnose command will prove whether the credentials work.

Content pipeline #

  • CONTENT_DRIVER toggles between file, db, hybrid, or auto (switches based on page count).
  • Markdown caching inherits TTL from content.markdown.cache_ttl; override with CONTENT_MARKDOWN_CACHE_TTL by adding it to .env and referencing via env() calls if needed.

Theme & modules #

  • THEME picks the folder under themes/ that ThemeService should load. Great for per-tenant overrides.
  • MODULE_PATHS isn’t an env var today, but you can extend config/modules.php to read one if you need runtime reconfiguration.

Deployment tips #

  • Keep secrets (DB_PASSWORD, API tokens) out of Git; inject via your orchestrator.
  • After editing .env, clear OPcache or restart PHP-FPM so the bootstrap sees new values.
  • Pair env changes with ./velvet config:cache in CI so the cached file matches the new values.

A disciplined .env strategy makes it trivial to run VelvetCMS locally, on staging, and in production without forking the codebase.

Previous Configuration Overview Next Helper Functions