# Configuration

Set a few environment variables once and Mailpiece runs. Most are optional.

Paste this into your agent:

> Check the environment variables of my Mailpiece install and tell me what's missing. Read mailpiece.dev/docs/configuration.md first.

## 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.

```sh
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`.

```sh
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 <hello@example.com>`, 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`.

```sh
docker run \
  --env "MAILER_FROM_ADDRESS=My Newsletter <hello@example.com>" \
  --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.

```sh
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](https://mailpiece.dev/docs/relay), under Settings › Outgoing mail; without one it mails nothing. The details are in [Mail](https://mailpiece.dev/docs/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`.

Still need help? Ask on [GitHub](https://github.com/mailpiece/mailpiece).