Environment variables

Where settings live

The installer writes ./opensend/.env with mode 0600. Manual installs also use .env, which Compose reads automatically. Source setup uses .env.docker; pass --env-file .env.docker to Compose. .env.example describes .env.local for pnpm dev and direct CLI/editor use.

Keep secrets private and back them up with your data. Do not add NEXT_PUBLIC_ to secret names. Installer reruns preserve existing values and never rotate existing secrets.

Release and images

OPENSEND_VERSION is the release tag, such as v0.1.0. Each release's images carry the same tag. Source setup saves local image overrides; updating only OPENSEND_VERSION does not replace those images.

DOCUMENT_RETENTION_DELAY is a backend container setting, not the application's email retention policy. The Compose backend also fixes DISABLE_BEACON=true and REDACT_LOGS_TO_CLIENT=true.

Origins

The backend maps CONVEX_BACKEND_ORIGIN to CONVEX_CLOUD_ORIGIN and CONVEX_PUBLIC_SITE_URL to CONVEX_SITE_ORIGIN. These advertised origins must be reachable from inside the backend container. Caddy requires all three public URLs as HTTPS origins. The optional dashboard gets NEXT_PUBLIC_DEPLOYMENT_URL from CONVEX_PUBLIC_URL.

SITE_URL=https://mail.example.com
CONVEX_PUBLIC_URL=https://realtime.mail.example.com
CONVEX_PUBLIC_SITE_URL=https://api.mail.example.com
CONVEX_BACKEND_ORIGIN=https://realtime.mail.example.com

Your client application's REST base URL is CONVEX_PUBLIC_SITE_URL, without an /api suffix. It is different from the Convex query/WebSocket origin.

Credentials and backend environment

The no-argument migrate job sends non-empty values for SITE_URL, BETTER_AUTH_SECRET, SSO_ENCRYPTION_KEY, SES_ENCRYPTION_KEY, SES_CALLBACK_ORIGIN, ALLOW_LOCAL_OIDC, LOG_AUTH_LINKS, all three DOMAIN_CONNECT_* settings, and SMTP_HOST to Convex before deployment. Empty Compose defaults do not erase existing backend settings. For settings changed directly with migrate env set, keep any non-empty .env counterpart in sync.

Without LOG_AUTH_LINKS, bootstrap logs expose account links only for the first installation administrator before a system sender exists. Never enable LOG_AUTH_LINKS=true on a real installation. See account recovery.

Ports and SMTP

Compose fixes SMTP_CONVEX_SITE_URL=http://convex:3211, SMTP_TLS_KEY_PATH=/certs/privkey.pem, and SMTP_TLS_CERT_PATH=/certs/fullchain.pem in the gateway. See SMTP gateway for its opt-in smtp profile and certificates.

CLI and source helpers

migrate receives CONVEX_SELF_HOSTED_URL=http://convex:3210 from Compose. Direct CLI/editor use needs CONVEX_SELF_HOSTED_URL and CONVEX_SELF_HOSTED_ADMIN_KEY in .env.local. Do not also set CONVEX_DEPLOYMENT. The migrate entrypoint clears CONVEX_DEPLOYMENT and CONVEX_DEPLOY_KEY before passing commands to the CLI.

OPENSEND_ENV_FILE overrides the source helpers' environment file. OPENSEND_BACKEND_ONLY=1 starts only backend services in source setup; OPENSEND_SKIP_BUILD=1 skips its image build. These are helper options, not container settings.

The oidc-test profile is for local testing. OIDC_PORT defaults to loopback 8080, OIDC_ADMIN_PASSWORD defaults to local-test-only, and OIDC_REALM_FILE defaults to ./docker/oidc-realm.json. That realm file is part of the source checkout, not a release asset.

Installer options

These configure the shell installer; they are not backend settings:

The installer saves image overrides, app/backend ports, and COMPOSE_PROJECT_NAME in .env. Existing settings take precedence on install. Upgrade can replace app, migrate, and SMTP image overrides supplied in its environment. uninstall --purge always needs a terminal and typed PURGE; there is no environment variable to bypass it.