Environment Variables

Copy .env.example in the repository root to .env. The Docker image, Compose files and bun run scripts all read it from there.

cp .env.example .env

Only the four required variables must be set. Email, storage and integrations can also be set later in Admin → Settings.

Required

Variable	Description
`APP_URL`	Public address of your instance, without a trailing slash, e.g. `https://files.example.com`
`AUTH_SECRET`	Signs sessions. Generate with `openssl rand -base64 32`. Changing it signs everyone out.
`DATABASE_URL`	PostgreSQL connection string
`REDIS_URL`	Redis connection string

With Docker Compose, DATABASE_URL and REDIS_URL are set for you. Set POSTGRES_PASSWORD instead.

Older variable names

NEXTAUTH_URL, NEXT_PUBLIC_BASE_URL and NEXTAUTH_SECRET still work, but APP_URL and AUTH_SECRET replace them. Remove the old ones when you update, so they can't disagree.

Instance

Variable	Default	Description
`EMBERLY_LICENSE_KEY`	—	Your license key. Optional: you can also paste it in Admin → Settings → License & branding. See License & Branding.
`EMBERLY_LICENSE_CHECKIN`	`true`	Set to `false` on servers that can't reach licenses.embrly.ca
`EMBERLY_RUN_EVENT_WORKER`	`true`	Runs background jobs (emails, notifications, Discord alerts, OCR, malware scans) in the app process. Only set it to `false` if you run `bun run worker` as its own service.
`NEXTAUTH_TRUSTED_ORIGINS`	—	Extra origins allowed to sign in, comma separated
`NEXTAUTH_COOKIE_DOMAIN`	—	Share the session across subdomains, e.g. `.example.com`
`EMBERLY_SKIP_MIGRATIONS`	`false`	Docker only: skip running migrations when the container starts
`EMBERLY_PORT`	`3000`	Docker Compose only: the host port
`EMBERLY_IMAGE`	`ghcr.io/emberlyoss/emberly:latest`	Docker Compose only: the image to run

Background jobs run inside the app, so a single process is all you need. If you set EMBERLY_RUN_EVENT_WORKER=false, something else must run bun run worker, or emails and alerts are queued but never sent. Admin → Overview warns you when no worker is running.

Storage

Leave these empty to store uploads on local disk. Setting STORAGE_PROVIDER=s3 overrides the storage settings in the Admin Panel. See Storage.

Variable	Description
`DATA_DIR`	Where local uploads are kept. Defaults to `/data` in Docker and the repository root otherwise.
`STORAGE_PROVIDER`	Set to `s3` to use the S3 settings below
`S3_ENDPOINT`	S3 API address. Leave empty for AWS.
`S3_PUBLIC_ENDPOINT`	Address users' browsers and apps use to reach the bucket, if different from `S3_ENDPOINT`
`S3_BUCKET`	Bucket name. Emberly creates it if it doesn't exist.
`S3_REGION`	Defaults to `us-east-1`
`S3_ACCESS_KEY_ID`	Access key
`S3_SECRET_ACCESS_KEY`	Secret key
`S3_FORCE_PATH_STYLE`	Use path-style URLs. Defaults to `true` when `S3_ENDPOINT` is set.

Email

Used for verification, password resets and notifications. Settings in Admin → Settings → Integrations take priority over these.

Set up either Resend or SMTP; Emberly uses whichever one is configured. If both are, it uses the provider chosen in Admin → Settings → Integrations → Email. Admin → Overview shows which one is in use.

Variable	Description
`EMAIL_FROM`	Sender address, e.g. `Emberly <[email protected]>`
`RESEND_API_KEY`	Send through Resend
`SMTP_HOST`	Send through any SMTP server instead
`SMTP_PORT`	Defaults to `587`
`SMTP_SECURE`	`true` for port 465
`SMTP_USER`	SMTP username
`SMTP_PASSWORD`	SMTP password

Integrations

All optional.

Variable	Description
`VIRUSTOTAL_API_KEY`	Checks uploads against VirusTotal. Recommended for public instances.
`GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`	Lets users link GitHub. Callback: `https://your-domain/api/auth/link/github/callback`
`DISCORD_OAUTH_CLIENT_ID` / `DISCORD_OAUTH_CLIENT_SECRET`	Lets users link Discord. Callback: `https://your-domain/api/auth/link/discord/callback`
`NEXT_PUBLIC_SENTRY_DSN`	Sends errors to Sentry

Everyone signs in with email. GitHub and Discord are only for linking accounts.

Cloud Mode

These are for running Emberly as a hosted service and need a hosted-service license. Self-hosted instances leave them unset. .env.cloud.example lists them all.

Variable	Description
`EMBERLY_RUN_CLOUD`	Turns on billing, custom domains, squads and Discovery
`STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET`	Stripe billing. Can also be set up from Admin → Settings → Integrations → Stripe.
`CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ZONE_ID` / `CNAME_TARGET`	Custom domains

Example

APP_URL="https://files.example.com"
AUTH_SECRET="generated-secret"
DATABASE_URL="postgresql://emberly:password@localhost:5432/emberly"
REDIS_URL="redis://localhost:6379"

EMAIL_FROM="Emberly <[email protected]>"
RESEND_API_KEY="re_..."

VIRUSTOTAL_API_KEY="..."