Configuration

Before Masthead can start, a small number of configuration values must be provided. This page describes every supported environment variable and the behavior it controls.

Required

The following variables are required. If any of them are missing, Masthead fails during startup rather than running in a partially configured state.

Variable	Purpose
DATABASE_URL	PostgreSQL connection string, for example ecto://USER:PASS@HOST/DATABASE.
SECRET_KEY_BASE	Used to sign and encrypt cookies and LiveView tokens. Generate one with mix phx.gen.secret.
RESEND_API_KEY	API key used to send transactional emails through Resend, such as account confirmations and password resets.
MAIL_FROM	Sender address for outgoing email. This must be a verified sender on your Resend account, for example noreply@example.com.

Serving traffic

The following variables control how Masthead serves HTTP traffic.

Variable	Default	Purpose
PHX_SERVER	unset	Set to true to start the HTTP server. Without this, the application starts but never accepts requests.
PHX_HOST	example.com	Canonical hostname used for URL generation and origin checks.
APP_HOSTS	value of PHX_HOST	Comma-separated list of hostnames that serve the Masthead application.
PORT	4000	HTTP port to bind to.

Multi-tenancy

Masthead resolves sites based on the incoming Host header.

Requests to one of the configured APP_HOSTS are treated as the Masthead application itself (marketing pages, authentication and administration). Requests to a subdomain of one of those hosts are resolved as a tenant and rendered using that site’s active theme.

APP_HOSTS is also used as the CNAME target when configuring custom domains, so it should point to a stable hostname you control.

APP_HOSTS=masthead.site

masthead.site       -> Masthead application
acme.masthead.site  -> Site with slug "acme"

Object storage

Masthead supports both local storage and S3-compatible object storage.

When BUCKET_NAME is configured, Masthead automatically switches to the S3 storage adapter. If it is omitted, uploads are stored on the local filesystem instead.

Variable	Default	Purpose
BUCKET_NAME	—	Bucket used to store uploaded files. Enables S3 storage when present.
AWS_ACCESS_KEY_ID	—	Access key used to authenticate with S3.
AWS_SECRET_ACCESS_KEY	—	Secret key used to authenticate with S3.
AWS_ENDPOINT_URL_S3	https://fly.storage.tigris.dev	URL of any S3-compatible storage provider.
AWS_REGION	auto	AWS region used by the client.
AWS_PUBLIC_URL_S3	derived automatically	Override when uploads are served from a CDN or custom domain.

The configured bucket must allow public access to uploaded files. Otherwise images and other uploaded assets cannot be served.

Local storage

When BUCKET_NAME is omitted, uploads are written to the local filesystem.

The storage location is configured in your application configuration rather than through an environment variable.

config :masthead, Masthead.Storage,
  root: "/data/uploads"

By default this path points to priv/uploads inside the release. On most container platforms this directory is ephemeral, so you should either configure a persistent storage location or mount a persistent volume to the configured path.

Optional

The following configuration values are optional.

Variable	Default	Purpose
POOL_SIZE	10	Database connection pool size.
ECTO_IPV6	disabled	Set to true or 1 to connect to PostgreSQL over IPv6.
DNS_CLUSTER_QUERY	—	DNS query used for node discovery in clustered deployments.
MAIL_FROM_NAME	Masthead	Display name used for outgoing email.

Social sign-in

OAuth providers are enabled only when their client credentials are configured.

Variable	Purpose
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Enables Sign in with Google.
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	Enables Sign in with GitHub.

Leaving these variables unset simply disables the corresponding sign-in option.

Custom domains (Fly.io)

Custom domain verification works on every deployment, but automatic TLS certificate provisioning currently relies on the Fly.io API.

Variable	Purpose
FLY_API_TOKEN	Fly.io API token used to create and remove certificates.
FLY_APP_NAME	Name of the Fly application certificates should be attached to.

If either variable is omitted, certificate provisioning is disabled. Domain verification continues to work, but TLS must be configured externally, for example by using a reverse proxy such as Caddy, Traefik or Nginx.

Minimal production configuration

DATABASE_URL=ecto://masthead:secret@db.internal/masthead
SECRET_KEY_BASE=<mix phx.gen.secret>
RESEND_API_KEY=re_xxxxxxxx
MAIL_FROM=noreply@example.com

PHX_SERVER=true
PHX_HOST=example.com
APP_HOSTS=example.com
PORT=8080

# Optional S3 storage
BUCKET_NAME=masthead-uploads
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_ENDPOINT_URL_S3=https://s3.your-provider.example
AWS_REGION=auto

Secrets

Never commit secrets such as SECRET_KEY_BASE, RESEND_API_KEY, AWS_SECRET_ACCESS_KEY or FLY_API_TOKEN to version control.

Instead, store them using your deployment platform’s secret management system, such as Fly secrets, Kubernetes Secrets or your cloud provider’s equivalent.