Environment variables

Every env var Maillayer reads, what it does, and which are required vs optional.

Required

AUTH_SECRET — encryption key for stored credentials. Auto-generated on first boot if not set; persisted to /app/data/.auth_secret. Don't rotate. Rotating breaks every encrypted credential.

Optional but recommended

APP_URL — public URL (e.g. https://mail.example.com). Used in tracking pixels, click rewrites, unsubscribe links, invitation emails. Falls back to RAILWAY_PUBLIC_DOMAIN on Railway.
MAXMIND_LICENSE_KEY — free MaxMind license key for IP geolocation. Build downloads GeoLite2-City. Without it, geo lookups return null.

Operational

PORT — listen port. Default 3000.
HOST — bind address. Default 0.0.0.0.
NODE_ENV — production in the official image.
DATABASE_PATH — SQLite file path. Default /app/data/maillayer.db.
GEOIP_PATH — override the bundled GeoLite2 file location.

Cron + retention

DISABLE_CRON — set to 1 to disable all background jobs. Don't use in production — sequences won't advance, campaigns won't send.
BACKUP_DIR — nightly backup destination. Default /app/data/backups.
BACKUP_KEEP_N — how many backups to retain. Default 14.
JOB_RETENTION_DAYS — old job rows pruned after this many days. Default 30.
DATA_RETENTION_DAYS — events / send history pruned after this many days. Default 365.

Setting these in Docker Compose

environment:
  AUTH_SECRET: ${AUTH_SECRET}
  APP_URL: https://mail.example.com
  MAXMIND_LICENSE_KEY: ${MAXMIND_LICENSE_KEY:-}
  BACKUP_KEEP_N: "30"