Environment Variables

Emberly is configured through a combination of environment variables (required at startup) and the Admin Panel UI (applied at runtime, stored in the database). This page covers the environment variables.

Copy .env.template to .env to get started:

cp .env.template .env

Required Variables

These must be set before the app will start.

Database

Variable	Description	Example
`DATABASE_URL`	PostgreSQL connection string	`postgresql://user:pass@localhost:5432/emberly?schema=public`

Cache

Variable	Description	Example
`REDIS_URL`	Redis connection string	`redis://default:password@localhost:6379`

Authentication

Variable	Description	Notes
`NEXTAUTH_URL`	The canonical URL of your instance	`https://yourdomain.com`
`NEXT_PUBLIC_BASE_URL`	Same as `NEXTAUTH_URL` — used client-side	`https://yourdomain.com`
`NEXTAUTH_SECRET`	Random secret for JWT signing	Minimum 32 characters. Generate with `openssl rand -base64 32`
`NEXTAUTH_TRUSTED_ORIGINS`	Comma-separated list of trusted origins	`https://yourdomain.com`

OAuth Providers

Required only if you want OAuth login. Both are optional — users can always sign up with email and password.

GitHub OAuth

Variable	Description
`GITHUB_OAUTH_CLIENT_ID`	Client ID from your GitHub OAuth app
`GITHUB_OAUTH_CLIENT_SECRET`	Client secret from your GitHub OAuth app

Create a GitHub OAuth app at github.com/settings/applications/new. Set the callback URL to https://yourdomain.com/api/auth/callback/github.

Discord OAuth

Variable	Description
`DISCORD_OAUTH_CLIENT_ID`	Client ID from your Discord application
`DISCORD_OAUTH_CLIENT_SECRET`	Client secret from your Discord application

Create a Discord application at discord.com/developers/applications. Set the redirect URL to https://yourdomain.com/api/auth/callback/discord.

Feature Flags

Variable	Default	Description
`EMBERLY_RUN_CLOUD`	`false`	Enables cloud-specific features (marketing pages, managed billing UI). Set to `false` for self-hosted instances.
`EMBERLY_RUN_EVENT_WORKER`	`false`	Runs the background event worker in-process. Set to `true` to enable async jobs (OCR, email, bucket provisioning).

In production, set EMBERLY_RUN_EVENT_WORKER=true so that background jobs (OCR, expiration emails, storage bucket provisioning) actually run. Without it, uploads still work but async processing is skipped.

Optional Variables

Error Tracking (Sentry)

Variable	Description
`NEXT_PUBLIC_SENTRY_DSN`	Sentry DSN for frontend and API error reporting
`SENTRY_ORG`	Sentry organization slug (build-time only, for source map upload)
`SENTRY_PROJECT`	Sentry project name (build-time only)
`SENTRY_AUTH_TOKEN`	Sentry auth token (build-time only, for CI source map upload)

Leave all Sentry variables empty to disable error tracking entirely.

File Scanning

Variable	Description
`VIRUSTOTAL_API_KEY`	VirusTotal API key for malware scanning

Without this key, VirusTotal scanning is skipped and only local extension/MIME checks run. Uploads are still processed normally. For production instances, a VirusTotal API key is strongly recommended.

Admin Panel Configuration

The following are not environment variables. They are configured after the app is running via the Admin Panel under Settings → Integrations, and stored in the database:

Integration	Configured in Admin Panel
S3 / Object storage	Provider, bucket name, endpoint, access keys, public URL
Stripe	Secret key, webhook secret, price IDs
Resend / SMTP email	API key, from address, SMTP credentials
Cloudflare	Zone ID, API token, CNAME target
Storage pools (Vultr, Linode, OVHcloud)	API keys, pool configuration

This means you do not need to restart the application to change integrations — they update live from the database.

Development vs Production

Variable	Development	Production
`NEXTAUTH_URL`	`http://localhost:3000`	`https://yourdomain.com`
`NEXT_PUBLIC_BASE_URL`	`http://localhost:3000`	`https://yourdomain.com`
`EMBERLY_RUN_CLOUD`	`false`	`false` (unless you are running the managed cloud service)
`EMBERLY_RUN_EVENT_WORKER`	optional	`true`
`VIRUSTOTAL_API_KEY`	optional	recommended

Example Production `.env`

DATABASE_URL="postgresql://emberly:strongpassword@localhost:5432/emberly?schema=public"
REDIS_URL="redis://default:strongpassword@localhost:6379"

NEXTAUTH_URL="https://files.yourdomain.com"
NEXT_PUBLIC_BASE_URL="https://files.yourdomain.com"
NEXTAUTH_SECRET="your-generated-secret-here"
NEXTAUTH_TRUSTED_ORIGINS="https://files.yourdomain.com"

GITHUB_OAUTH_CLIENT_ID="ghp_..."
GITHUB_OAUTH_CLIENT_SECRET="..."
DISCORD_OAUTH_CLIENT_ID="..."
DISCORD_OAUTH_CLIENT_SECRET="..."

EMBERLY_RUN_CLOUD=false
EMBERLY_RUN_EVENT_WORKER=true

VIRUSTOTAL_API_KEY="..."
NEXT_PUBLIC_SENTRY_DSN="https://...@sentry.io/..."

On this page