.env.example

# ==============================================================================
# Bird CMS - Environment Configuration
# ==============================================================================
# Copy to .env and fill in your values. .env MUST NOT be committed to git.

# ==============================================================================
# Docker & Infrastructure
# ==============================================================================

# For local docker dev: leave APP_DOMAIN=localhost.
# For production behind Traefik / nginx-proxy / Caddy: set to your real domain.
APP_DOMAIN=localhost
TRAEFIK_ROUTER=example
TRAEFIK_SERVICE=example-service
CONTAINER_NAME=example

# ==============================================================================
# Application Settings
# ==============================================================================

APP_ENV=local

# REQUIRED. Signs HMAC preview tokens. Generate with:
#   php -r 'echo bin2hex(random_bytes(32));'
# Bird CMS refuses to boot if this is empty or set to a known-insecure default.
APP_KEY=

# Render full PHP stack traces to the browser on errors. NEVER enable in production.
DEBUG=false

# ==============================================================================
# Admin Panel
# ==============================================================================

ADMIN_USERNAME=admin

# Generate a fresh hash with:
#   php -r 'echo password_hash("YOUR_STRONG_PASSWORD", PASSWORD_DEFAULT);'
# Do NOT ship a default. Bird CMS does not enforce a forced first-login password
# change, so a shared example hash means all unconfigured installs are takeable.
ADMIN_PASSWORD_HASH=

# Admin panel IP allow-list. Default-deny: only loopback + docker bridge can
# reach /admin until you explicitly allow your real IP/CIDR. Empty = open to
# ALL (don't ship that). Unauthorized IPs receive the site's themed 404 page
# (admin existence is hidden).
#
# The default below works for local `docker compose up` (host -> container
# traffic crosses the docker bridge as 172.x). For production: replace with
# your real ops IP/CIDR. Examples:
#   ADMIN_ALLOWED_IPS=203.0.113.42         # single static IP
#   ADMIN_ALLOWED_IPS=10.0.0.0/8           # whole CIDR
#   ADMIN_ALLOWED_IPS=1.2.3.4,10.0.0.0/24  # multiple, comma-separated
ADMIN_ALLOWED_IPS=127.0.0.1,::1,172.16.0.0/12

# Admin UI mode: 'minimal' (Pages/Categories/Media/Settings) or 'full' (also Articles/Security/Audit)
# Default is 'minimal' -- the trimmed nav suits the typical markdown-first
# install. Hidden sections still respond at their direct URLs.
# ADMIN_MODE=minimal

# Reverse proxies whose X-Real-IP / CF-Connecting-IP we trust.
# WITHOUT this list, header values are ignored and only REMOTE_ADDR is used --
# this is what blocks attackers who spoof X-Real-IP from a non-proxy address.
# Default below covers loopback + Docker private space (where Traefik lives).
# Do NOT add VPN/client networks here -- they are clients, not proxies.
TRUSTED_PROXIES=127.0.0.1,::1,172.16.0.0/12

# ==============================================================================
# Site Identity
# ==============================================================================

SITE_NAME="My Site"
SITE_TAGLINE="Site tagline"
SITE_DESCRIPTION="Site description for SEO"
SITE_URL="https://example.com"
SITE_LOGO="/assets/images/logo.svg"
SITE_FAVICON="/favicon.ico"

# ==============================================================================
# Contact
# ==============================================================================

CONTACT_EMAIL_GENERAL="hello@example.com"
CONTACT_EMAIL_EDITOR="editor@example.com"

# ==============================================================================
# Theme
# ==============================================================================

ACTIVE_THEME=tailwind

# Tailwind CSS source. Empty = no <script> tag injected and the default
# `tailwind` theme breaks. Default below uses the Play CDN -- fine for
# evaluation; for production replace with a self-hosted build (e.g.
# /assets/tailwind.css).
TAILWIND_CDN_URL=https://cdn.tailwindcss.com

# ==============================================================================
# Features Toggle
# ==============================================================================

FEATURE_NEWSLETTER=false
FEATURE_SEARCH=true
FEATURE_COMMENTS=false
FEATURE_DARK_MODE=false

# ==============================================================================
# SEO Settings
# ==============================================================================

SEO_TITLE_SEPARATOR="--"
SEO_DEFAULT_OG_IMAGE="/assets/images/og-default.jpg"

# ==============================================================================
# Anti-bot ingest (powers /admin/blacklist + /admin/sandbox)
# ==============================================================================
# Bird CMS parses the nginx access log into storage/analytics/visits.db and
# auto-blocks scanner patterns. The visits.db itself is NOT a user-facing
# analytics dashboard -- those live in Statio (see below). It's anti-bot
# fuel that nginx reads via a generated blacklist.conf.
#
# On non-nginx deploys (Apache shared hosting, managed PaaS) this pipeline
# does not run; admin blacklist/sandbox UIs render empty but harmless.

# Max visits to retain in visits.db. SQLite trigger drops the oldest rows
# above this cap. Set 0 to keep everything (only on disks with room to spare).
ANALYTICS_RETENTION_VISITS=50000

# ==============================================================================
# Tracking + lead capture (Statio integration)
# ==============================================================================
# Statio (https://statio.click, MIT, self-hostable) is the canonical
# analytics + lead inbox for Bird CMS. The /api/lead endpoint forwards
# every form submission to STATIO_LEADS_ENDPOINT with bearer auth.
#
# Without these set: /api/lead returns 503 with a hint, and the lead-form
# partial in your theme should self-disable. The site keeps rendering.
#
# See docs/recipes/integrate-statio.md for the 5-minute setup.

STATIO_LEADS_ENDPOINT=
STATIO_API_SECRET=
STATIO_SITE_GUID=

# ==============================================================================
# Rate limiting (/api/lead, /api/subscribe, /api/search, /api/track-event)
# ==============================================================================
# Application-level rate limits backed by SQLite (storage/data/rate-limit.db).
# Per-endpoint caps in config/rate-limit.php; sliding-window algorithm.
# Returns HTTP 429 with Retry-After header on overflow.
#
# Note: /admin/login has its own (stricter) lockout in app/Admin/Auth.php and
# is NOT controlled by this flag.
RATE_LIMIT_ENABLED=true

# ==============================================================================
# Performance caches (opt-in)
# ==============================================================================
# CONTENT_CACHE memoises parsed meta-arrays (article/page/service/area indexes)
# under storage/cache/. mtime-based invalidation, opcache-friendly PHP-array
# files. Default off; flip on once you have a baseline. See
# docs/perf/benchmarks/README.md for the 500-article reference numbers.
CONTENT_CACHE=false

# HTML_CACHE stores the fully rendered HTML body for stable-URL frontend
# pages under storage/cache/html/. A repeat GET echoes the file verbatim
# and skips the render pipeline entirely. Default off; the cache is
# repository-invalidated on save + flushed on settings change, and every
# entry expires after 300s as a safety net. Bypassed for query strings,
# non-GET, /admin /api /install /health paths, and requests with an
# admin session cookie. See docs/perf/html-cache.md.
HTML_CACHE=false

# ==============================================================================
# Engine Pin (dockerized engine deployments only -- ignored for static-extracted sites)
# ==============================================================================

# REQUIRED when using docker/entrypoint.sh: URL of the engine git repo to clone.
# No default -- point this at your fork or the upstream you trust.
# Example: https://github.com/your-org/bird-cms.git
ENGINE_REPO=

# REQUIRED when using docker/entrypoint.sh: git tag/branch to clone. No silent default.
# Use a tag (e.g. v3.0.0-rc.1) for stable production. Use main only if you trust
# upstream commits to land in your container on every restart.
ENGINE_REF=

# REQUIRED for scripts/check-update.sh: path to the engine checkout inside the
# container/host (e.g. /engine when running under the docker entrypoint).
ENGINE_DIR=

# REQUIRED for scripts/update.sh: directory where versioned site backups are
# written before each update. No default -- set to a path you control.
BIRD_BACKUP_DIR=

# Auto-update cron. Default off. Opt in only if you accept the risk of upstream changes
# auto-applying to a running site (with health-check + rollback via scripts/check-update.sh).
ENABLE_AUTO_UPDATE=false