Configuration

Where they go

With Docker, pass them with --env or under compose's environment. With Kamal, put them in your deploy file, or its secrets file for anything secret.

At a minimum you'll set the secret key, SSL, the app's own mail and the base URL.

Secret key base

Sessions and the links in mail are signed with a secret of your install's own. Any long random string works. Make it once and keep it: a new one signs everyone out, and the rating links in issues already mailed stop answering.

openssl rand -hex 64

docker run --env SECRET_KEY_BASE=abcdefabcdef ...

SSL

For the container to get its own certificate, set TLS_DOMAIN to the domain it runs on and open ports 80 and 443. With Kamal, leave it out: the proxy gets the certificate.

Behind a proxy that handles HTTPS, leave TLS_DOMAIN out and publish port 80 only. With no HTTPS at all, as on a laptop, also set DISABLE_SSL=true.

docker run --publish 80:80 --publish 443:443 --env TLS_DOMAIN=app.example.com ...

# Behind a proxy that handles HTTPS
docker run --publish 80:80 ...

# With no HTTPS at all
docker run --publish 80:80 --env DISABLE_SSL=true ...

The app's own mail

Sign-in codes and email changes go over SMTP. MAILER_FROM_ADDRESS is the address they come from, such as My Newsletter <[email protected]>, and is also shown as the help address; the app does not start without it. SMTP_ADDRESS, SMTP_PORT (587, or 465 with SMTP_TLS=true), SMTP_USERNAME and SMTP_PASSWORD are your provider's.

Until the first account exists, the sign-in code is shown on screen, so the first sign-in works before mail is set up. Less often you may need SMTP_TLS, SMTP_DOMAIN, SMTP_AUTHENTICATION (plain unless set) or SMTP_SSL_VERIFY_MODE.

docker run \
  --env "MAILER_FROM_ADDRESS=My Newsletter <[email protected]>" \
  --env SMTP_ADDRESS=smtp.example.com \
  --env SMTP_USERNAME=... \
  --env SMTP_PASSWORD=... \
  ...

Base URL

The links in mail are built from the app's public address, and a newsletter's own domain needs it. Set BASE_URL to the full address.

docker run --env BASE_URL=https://app.example.com ...

Newsletter mail

Issues, tests, confirmations and welcome emails never use SMTP_*, and no environment variable sets them. Each newsletter sets its own SMTP server, or a relay to send through, under Settings › Outgoing mail; without one it mails nothing. The details are in Mail.

S3 storage (optional)

Uploads are kept in the storage volume unless you set ACTIVE_STORAGE_SERVICE to s3, with S3_BUCKET, S3_REGION (us-east-1 unless set), S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY. A provider other than AWS may also need S3_ENDPOINT, S3_FORCE_PATH_STYLE, S3_REQUEST_CHECKSUM_CALCULATION and S3_RESPONSE_CHECKSUM_VALIDATION.

Uploads go from the browser straight to the bucket. With S3_ENDPOINT and S3_BUCKET set, the bucket's own host is allowed; for any other address, set CSP_CONNECT_SRC to it.

Multi-tenant mode

By default only the first account is made by signing up. After that, someone already signed in can start another newsletter from the account menu, and nobody new can sign up. To let anyone sign up and start a newsletter of their own, set MULTI_TENANT=true.