Environment Variables¶

How Variables Reach Services¶

Understanding the plumbing matters more here than in most stacks:

• Compose interpolation is the only .env channel. No compose file uses env_file:, and no service loads .env with dotenv. A variable in .env reaches a container only if that service's environment: block in docker-compose.yml (or the prod overlay) names it. Setting something in .env that no block references does nothing.
• There is no central Settings object. Each service reads its own os.getenv() calls — often with different defaults for the same name. Tables below note per-service defaults where they differ.
• Secrets live in secrets/ and are bind-mounted read-only: MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db_root_password (mysql), DB_ROOT_PASSWORD_FILE (secrets-check), ENCRYPTION_KEK_PATH (default /run/secrets/encryption_kek), ARCHIVE_AGE_IDENTITY_FILE (default /run/secrets/archive_age_identity).
• The secrets-check gate runs before everything else (dev compose) and refuses to start the stack if any of DB_ROOT_PASSWORD, DB_PASSWORD, WEBHOOK_SECRET, OAUTH_TOKEN_SECRET, URL_HMAC_SECRET, ADMIN_PASSWORD, ADMIN_TOKEN_SECRET, GRAFANA_ADMIN_PASSWORD is missing, shorter than 16 chars, or a known-weak value. scripts/generate-secrets.sh produces a compliant .env.
• Postfix pipe/spawn scripts (tracking injector, policy daemons) don't inherit container env; the entrypoint writes /etc/postfix/runtime.env with the DB_*, REDIS_*, TRACKING_*, DELIVERY_OPTIMIZER_*, WEBHOOK_SECRET, HOSTNAME set, and the scripts load that file.

Database¶

Consumed by nearly every service; set per-service in compose (DB_HOST=mysql, DB_PORT=3306).

Redis¶

Server Identity & Mail¶

API Service¶

Dovecot / doveadm / IMAP¶

SSL / cert_manager¶

Postfix Overrides (read by its entrypoint)¶

POSTFIX_MYNETWORKS (default 172.25.0.0/16 appended), POSTFIX_DEV_MODE, POSTFIX_TLS_SECURITY_LEVEL, POSTFIX_SMTP_TLS_SECURITY_LEVEL, POSTFIX_TLS_AUTH_ONLY, POSTFIX_TLS_PROTOCOLS, POSTFIX_TLS_CIPHERS, POSTFIX_TLS_EXCLUDE_CIPHERS, POSTFIX_TLS_LOG_LEVEL, POSTFIX_TLS_CACHE_TIMEOUT, POSTFIX_CONNECTION_RATE_LIMIT, POSTFIX_CONNECTION_COUNT_LIMIT, POSTFIX_MESSAGE_RATE_LIMIT, POSTFIX_RECIPIENT_RATE_LIMIT, POSTFIX_RATE_TIME_UNIT, POSTFIX_SMTP_TIMEOUT, POSTFIX_HELO_TIMEOUT, POSTFIX_MAIL_TIMEOUT, POSTFIX_RCPT_TIMEOUT, POSTFIX_DATA_TIMEOUT, POSTFIX_SOFT_ERROR_LIMIT, POSTFIX_HARD_ERROR_LIMIT, POSTFIX_JUNK_COMMAND_LIMIT, POSTFIX_DNS_TIMEOUT.

Tracking¶

Webhooks¶

Log Ingestor & SMTP Credentials¶

Rate Limiter¶

Service basics: RATE_LIMITER_HOST/RATE_LIMITER_PORT (0.0.0.0/8082), RATE_LIMITER_URL (http://rate_limiter:8082, Postfix policy client), RATE_LIMITER_TIMEOUT (5), RATE_LIMIT_CACHE_TTL (300), warning/critical/exceeded thresholds (80/95/100).

Default quotas are 36 vars of the form {ORG|DOMAIN|MAILBOX}_{INBOUND|OUTBOUND}_{SECOND|MINUTE|HOURLY|DAILY|MONTHLY|BURST}_DEFAULT — e.g. ORG_OUTBOUND_HOURLY_DEFAULT=10000, DOMAIN_OUTBOUND_HOURLY_DEFAULT=2000, MAILBOX_OUTBOUND_HOURLY_DEFAULT=200. See worker/rate_limiter/config.py for the full matrix; per-SMTP-credential limits live on the credential row, not in env.

Storage / Archive / DR¶

Security Services & Misc Secrets¶

RAG / AI Search¶

Logging & Runtime Mode¶

Removed / Nonexistent Variables¶

These appeared in older docs but are read by nothing: API_HOST, API_PORT, DB_READ_HOST (reader module is unimported), TRACKING_WORKERS, ANALYTICS_WORKERS, QUEUE_MANAGER_WORKERS, GRAFANA_PASSWORD, PROMETHEUS_RETENTION (retention is the --storage.tsdb.retention.time=30d flag in compose), CLOUD_PROVIDER, AWS_S3_BUCKET, DEFAULT_TENANT_ID.

Example .env¶

Generate it rather than writing it by hand:

./scripts/generate-secrets.sh   # writes a complete .env with strong secrets

Then set the identity values:

COMPOSE_PROJECT_NAME=mailyte-prod
HOSTNAME=mail.yourdomain.com
DOMAIN=yourdomain.com
ADMIN_EMAIL=admin@yourdomain.com
ACME_EMAIL=admin@yourdomain.com
ACME_STAGING=false
MAIL_HOSTNAME=mail.yourdomain.com
DOVEADM_API_KEY=<random string — enables SMTP-credential cache flushing>
WEBHOOK_URLS=https://your-app.com/webhooks/mailyte