Configuration
Every environment variable. Exactly one is required.
The container boots with just AUTH_SECRET. Everything else unlocks a feature when present, and the app tells you in the UI when something it needs is missing.
| Variable | Status | What it does |
|---|---|---|
AUTH_SECRET | Required | 32+ random characters. Signs sessions and derives the key that encrypts stored integration secrets. Generate with openssl rand -base64 48. Back it up with the database. |
APP_URL | Recommended | Public origin, e.g. https://analytics.example.com. Used in share and invite links, OAuth callbacks, and as the license hostname. Required to activate. |
PIQO_LICENSE_KEY | Optional | Activates the install on first boot so the /activate screen is skipped. |
PORT | Optional | Port the app listens on. Defaults to 3000 in the image. Set it explicitly on platforms that inject their own. |
DATABASE_PATH | Optional | SQLite file. Defaults to /app/data/piqo.db. Leave it and mount a volume at /app/data. |
MAXMIND_LICENSE_KEY | Optional | City-level geolocation. Free key from maxmind.com. Downloaded on first boot into the volume. Without it, country comes from proxy headers where available. |
SMTP_URL | Optional | Any SMTP server, e.g. smtp://user:[email protected]:587. Enables invite emails, password reset and insight digests. Without it, invite links are shown to copy. |
EMAIL_FROM | Optional | Sender for the above, e.g. "Piqo Analytics <[email protected]>". |
ANTHROPIC_API_KEY | Optional | Turns on Ask AI and the MCP server. Billed to your Anthropic account. |
AI_CHAT_MODEL | Optional | Model for Ask AI. Defaults to claude-haiku-4-5. |
GOOGLE_OAUTH_CLIENT_ID | Optional | With the secret below: Google Search Console and GA4 import. Redirect URI is $APP_URL/api/integrations/gsc/callback. |
GOOGLE_OAUTH_CLIENT_SECRET | Optional | See above. |
TELEGRAM_BOT_TOKEN | Optional | With TELEGRAM_CHAT_ID: ops alerts (failed jobs, license problems) to a Telegram chat. Otherwise they go to the container log. |
TELEGRAM_CHAT_ID | Optional | See above. |
DATA_RETENTION_DAYS | Optional | Events older than this are deleted nightly. 0 (default) keeps everything. |
BACKUP_DIR | Optional | Where nightly backups go. Defaults to /app/data/backups. |
BACKUP_KEEP_N | Optional | How many nightly backups to keep. Defaults to 7. |
DISABLE_CRON | Optional | 1 turns off the in-process scheduler (rollups, syncs, insights, retention, backups, license check-in). Only for running those elsewhere. |
Minimal example
AUTH_SECRET=xK3...48 random characters...
APP_URL=https://analytics.example.com
PIQO_LICENSE_KEY=PIQOSH-XXXXX-XXXXX-XXXXX-XXXXXBehind a proxy
The collector reads the visitor's IP from X-Real-IP or the first entry of X-Forwarded-For, so country lookups work behind Caddy, Nginx, Cloudflare and the platform proxies. Nothing to configure.
Changing
AUTH_SECRET logs everyone out and makes stored integration secrets (Search Console tokens, payment provider keys) unreadable. Treat it like the database itself. See Updates & backups.