# Configuration

Source: https://bulwarkmail.org/docs/getting-started/configuration
Last updated: 2026-11-17

> Configure Bulwark for your environment.

**Not in Lite.** This page configures Bulwark (not Lite) through environment variables and the admin console. Lite reads config.json instead; see Bulwark Lite.

Bulwark has two configuration surfaces:

1. The **web setup wizard** and **admin console**, which is what new installs should use. The wizard runs on first launch when no `JMAP_SERVER_URL` is set in the environment and writes JSON config to `ADMIN_CONFIG_DIR`. The admin console manages the same file afterwards.
2. **Environment variables** in `.env.local` (or your container's env). Still fully supported, and the right choice for immutable / read-only / env-as-code deployments.

A value the wizard or the admin console has saved wins; the environment fills in every key the admin config leaves unset. The session secret is the exception: `SESSION_SECRET` or `SESSION_SECRET_FILE` in the environment wins over one the wizard saved. Setting `JMAP_SERVER_URL` in the environment before the first launch skips the wizard, which is how an env-only deployment stays env-only.

## Configuration model

Bulwark supports three configuration layers:

- **Admin-managed config:** written by the setup wizard or the admin console to `data/admin/config.json` (or `ADMIN_CONFIG_DIR/config.json`). Changes take effect on the next user session without a restart.
- **Runtime environment variables:** read by the server at request time. Used for every key the admin config does not set. Work well for Docker and reverse-proxy deployments.
- **Legacy build-time variables:** `NEXT_PUBLIC_*` fallbacks still supported for older deployments, but new setups should prefer the wizard or runtime variables.

The order of precedence is **admin config > env var > build-time fallback > built-in default**. If an environment variable seems to be ignored, look for the same key in `ADMIN_CONFIG_DIR/config.json`: a value saved there, even `false`, takes priority until you remove it.

Besides the session secret (see above), `NO_THIRD_PARTY_TRAFFIC` is the other exception: set to `true` in the environment, it can't be switched off from the admin console.

## Minimal setup

A basic deployment needs one variable:

```env
JMAP_SERVER_URL=https://mail.example.com
```

Most deployments also set a display name:

```env
APP_NAME=Bulwark Webmail
JMAP_SERVER_URL=https://mail.example.com
```

## Environment variables

| Variable                      | Required        | Default                                   | Description                                                                                |
| ----------------------------- | --------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------ |
| `HOSTNAME`                    | No              | `0.0.0.0`                                 | Address the server binds to; use `::` for IPv6                                             |
| `PORT`                        | No              | `3000`                                    | Port the server listens on                                                                 |
| `APP_NAME`                    | No              | `Webmail`                                 | Application name shown in the UI, browser tab, and PWA manifest                            |
| `APP_SHORT_NAME`              | No              | falls back to `APP_NAME`                  | Short name for the PWA install prompt and home screen                                      |
| `APP_DESCRIPTION`             | No              | generic Bulwark description               | Description shown in the PWA manifest                                                      |
| `JMAP_SERVER_URL`             | Yes¹            | -                                         | URL of your JMAP-compatible mail server                                                    |
| `JMAP_SERVERS`                | No              | empty                                     | JSON array of servers to offer on the login form (`id`, `label`, `url`, optional `domains` and `oauth`) |
| `JMAP_SERVER_AUTO_PICK_BY_DOMAIN` | No          | `false`                                   | Pick a server from `JMAP_SERVERS` by the domain the user types                             |
| `ALLOW_CUSTOM_JMAP_ENDPOINT`  | No              | `false`                                   | Show a "JMAP Server" field on the login form so users can specify their own server         |
| `STALWART_FEATURES`           | No              | `true`                                    | Enables the Stalwart-only parts: the account Security tab (password, two-factor, app passwords, API keys) and deleted-mail recovery |
| `STALWART_JMAP_PASSTHROUGH_ENABLED` | No        | `true`                                    | Server-side switch for the credential-bearing Stalwart JMAP passthrough, independent of the UI flag above |
| `STALWART_ADMIN_ACCESS`       | No              | `auto`                                    | What a Stalwart admin account grants in the admin console: `auto`, `password`, or `off`  |
| `OAUTH_ENABLED`               | No              | `false`                                   | Enables OAuth2 / OpenID Connect login                                                      |
| `OAUTH_ONLY`                  | No              | `false`                                   | Hides the username/password login form and requires OAuth                                  |
| `OAUTH_CLIENT_ID`             | OAuth only      | -                                         | OAuth client ID                                                                            |
| `OAUTH_CLIENT_SECRET`         | No              | empty                                     | OAuth client secret for confidential clients                                               |
| `OAUTH_CLIENT_SECRET_FILE`    | No              | empty                                     | Path to a file containing the OAuth client secret (Docker / Kubernetes secrets)            |
| `OAUTH_ISSUER_URL`            | No              | falls back to `JMAP_SERVER_URL` discovery | Explicit issuer URL for external IdPs                                                      |
| `OAUTH_AUTHORIZE_URL`         | No              | from discovery                            | Override only the user-facing authorize endpoint (per-brand login hosts)                   |
| `OAUTH_ALLOW_PRIVATE_ENDPOINTS` | No            | `false`                                   | Let OAuth endpoints on other hosts than the issuer resolve to RFC 1918 / loopback addresses |
| `OAUTH_SCOPES`                | No              | built-in default                          | Override OAuth scope string                                                                |
| `OAUTH_EXTRA_SCOPES`          | No              | empty                                     | Additional scopes appended to defaults                                                     |
| `SESSION_SECRET`              | No              | generated on first start                  | Encrypts Remember-me, settings sync, multi-account, and embedded SSO                       |
| `SESSION_SECRET_FILE`         | No              | empty                                     | Path to a file containing the session secret                                               |
| `COOKIE_SAME_SITE`            | No              | `lax`                                     | Cookie `SameSite` attribute (`lax`, `none`, `strict`)                                      |
| `COOKIE_SECURE`               | No              | derived from env                          | Force `Secure` flag on cookies                                                             |
| `SETTINGS_SYNC_ENABLED`       | No              | `false`                                   | Enables encrypted server-side settings sync across devices and accounts                    |
| `SETTINGS_DATA_DIR`           | No              | `./data/settings`                         | Directory for encrypted settings storage (resolves to `/app/data/settings` in Docker)      |
| `PLUGIN_SECRETS_DIR`          | No              | `plugin-secrets` next to the settings dir | Credentials users save for plugins, encrypted (`/app/data/plugin-secrets` in Docker)       |
| `ADMIN_PASSWORD`              | No              | set via wizard; admin console disabled without one | Bootstrap admin password, read only while `admin.json` does not exist yet             |
| `ADMIN_CONFIG_DIR`            | No              | `./data/admin`                            | Operator-authored: `config.json`, `policy.json`, `admin.json` (passwordHash), plugins, themes, branding uploads. Safe to mount read-only after setup |
| `ADMIN_STATE_DIR`             | No              | `./data/admin-state`                      | Runtime: `admin-state.json` (login timestamps), `audit.log`, setup token. Always read-write |
| `ADMIN_CONFIG_READONLY`       | No              | `false`                                   | Enforce read-only mode at the app layer (pair with `:ro` mount of the config volume)        |
| `ADMIN_DATA_DIR`              | No              | -                                         | Legacy single dir used by pre-1.6.4 installs. Honoured when neither split var is set        |
| `ADMIN_SESSION_TTL`           | No              | `3600`                                    | Admin session lifetime in seconds                                                          |
| `BULWARK_TELEMETRY`           | No              | `off`                                     | Set to `on` to enable the anonymous daily heartbeat. Setting it either way locks the admin toggle |
| `BULWARK_TELEMETRY_DISABLED`  | No              | -                                         | Legacy kill switch, honoured only when `BULWARK_TELEMETRY` is unset                         |
| `BULWARK_TELEMETRY_ALLOW_PRIVATE` | No          | -                                         | Let heartbeats reach a private or loopback collector (development only)                      |
| `TELEMETRY_DATA_DIR`          | No              | `./data/telemetry`                        | Where the instance id and consent live; mount a volume to survive upgrades                   |
| `BULWARK_UPDATE_CHECK`        | No              | `on`                                      | Set to `off` to stop the startup release check and the in-app update notice                 |
| `BULWARK_UPDATE_CHECK_URL`    | No              | project release feed                      | Point the check at your own feed; an empty value disables it                                |
| `VERSION_CHECK_DATA_DIR`      | No              | `./data/version-check`                    | Where the update check stores its state                                                     |
| `TRUSTED_PROXY_DEPTH`         | No              | `1`                                       | Number of `X-Forwarded-For` hops to trust                                                  |
| `REQUEST_BODY_BUDGET_MB`      | No              | `128`                                     | Megabytes of request bodies held in memory at once; over it, large requests get 503. `0` turns it off |
| `SEARCH_ENGINE_INDEXING`      | No              | `false`                                   | Allow search engines to index the app; off emits `noindex`/`nofollow`                      |
| `NO_THIRD_PARTY_TRAFFIC`      | No              | `false`                                   | Turn off every built-in outside host: telemetry, update check, hosted push relay, official extension directory, connector, sender favicons, MyMemory translation, map links, WKD |
| `EXTENSION_DIRECTORY_URL`     | No              | `https://extensions.bulwarkmail.org`      | Marketplace URL for browsing and installing plugins/themes; `NO_THIRD_PARTY_TRAFFIC=true` turns the official one off |
| `DEMO_MODE`                   | No              | `false`                                   | Serve fixture data instead of talking to a mail server                                      |
| `PLUGIN_DEV_DIR`              | No              | empty                                     | Load plugins from a source folder with hot reload during development                        |
| `WOPI_CLIENT_URL`             | No              | empty                                     | Base URL of a Collabora Online, OnlyOffice or EuroOffice server; empty turns office editing off |
| `WOPI_HOST_URL`               | No              | request origin                            | How the editor reaches this webmail when it sees a different host than the browser           |
| `ICAL_MAX_BYTES`              | No              | built-in cap                              | Size limit for fetched iCalendar subscription feeds                                          |
| `NODE_USE_ENV_PROXY`          | No              | unset                                     | `1` sends server-side requests through `HTTPS_PROXY` / `HTTP_PROXY`, except hosts in `NO_PROXY` |
| `LOG_FORMAT`                  | No              | `text`                                    | Log output format: `text` or `json`                                                        |
| `LOG_LEVEL`                   | No              | `info`                                    | Log verbosity: `error`, `warn`, `info`, or `debug`                                         |
| `FAVICON_URL`                 | No              | Bulwark favicon                           | Custom browser tab favicon (SVG, PNG, or ICO; 32-512px)                                    |
| `PWA_ICON_URL`                | No              | falls back to `FAVICON_URL`               | Source image used to generate PWA install icons                                            |
| `PWA_THEME_COLOR`             | No              | `#ffffff`                                 | PWA browser UI chrome color                                                                |
| `PWA_BACKGROUND_COLOR`        | No              | `#ffffff`                                 | PWA splash screen background                                                               |
| `PWA_SCREENSHOT_MOBILE_URL` / `_DESKTOP_URL` | No | bundled                              | Screenshots shown in the browser's install dialog                                          |
| `APP_LOGO_LIGHT_URL`          | No              | empty                                     | Sidebar logo for light mode (SVG, PNG, or WebP; 24-128px)                                  |
| `APP_LOGO_DARK_URL`           | No              | empty                                     | Sidebar logo for dark mode (SVG, PNG, or WebP; 24-128px)                                   |
| `LOGIN_LOGO_LIGHT_URL`        | No              | Bulwark light logo                        | Login page logo for light backgrounds (SVG, PNG, or WebP; 32-512px)                        |
| `LOGIN_LOGO_DARK_URL`         | No              | Bulwark dark logo                         | Login page logo for dark backgrounds (SVG, PNG, or WebP; 32-512px)                         |
| `LOGIN_COMPANY_NAME`          | No              | empty                                     | Company name shown on the login page                                                       |
| `LOGIN_IMPRINT_URL`           | No              | empty                                     | Login page imprint / legal notice link                                                     |
| `LOGIN_PRIVACY_POLICY_URL`    | No              | empty                                     | Login page privacy policy link                                                             |
| `LOGIN_WEBSITE_URL`           | No              | empty                                     | Login page website link                                                                    |
| `LOGIN_USERNAME_PLACEHOLDER`  | No              | translated example                        | Placeholder of the login email field, in every language                                    |
| `LOGIN_FORGOT_PASSWORD_URL`   | No              | empty                                     | "Forgot your password?" link on the login page, to where users reset it                    |
| `LOGIN_LOGO_MAX_HEIGHT` / `_WIDTH` | No         | natural size                              | Cap the rendered login logo; any CSS length                                                |
| `LOGIN_LAYOUT`                | No              | `centered`                                | `centered` (card over the background) or `split` (form in a side panel)                   |
| `LOGIN_BACKGROUND_LIGHT_URL` / `_DARK_URL` | No | none                                     | Picture behind the login form; dark mode falls back to the light one                       |
| `LOGIN_BACKGROUND_DIM` / `_BLUR` | No           | `0`                                       | Darken (0-80 %) and blur (0-24 px) the login background                                    |
| `LOGIN_SHOW_HEADING` / `_SUBTITLE` / `_TOTP` / `_VERSION` | No | `true`             | Hide individual login page elements                                                        |
| `LOGIN_SHOW_REMEMBER_ME`      | No              | `false`                                   | Show the "Remember me" box instead of remembering every sign-in                          |
| `DOMAIN_BRANDING`             | No              | empty                                     | JSON array of per-hostname branding overrides, matched on `Host`; `*.` wildcards allowed   |
| `NEXT_PUBLIC_DEFAULT_LOCALE`  | Build-time      | `en`                                      | Fallback UI locale when `Accept-Language` matches nothing supported                        |
| `NEXT_PUBLIC_LOCALE_PREFIX`   | Build-time      | `never`                                   | Locale URL prefix mode: `always`, `as-needed`, or `never`. Empty means `never`; any other value stops the build |
| `NEXT_PUBLIC_BASE_PATH`       | Build-time      | empty                                     | Mount Bulwark under a subpath (e.g. `/webmail`); read at build time by Next.js              |
| `NEXT_PUBLIC_PUSH_RELAY_URL`  | Build-time      | `https://notifications.relay.bulwarkmail.org` | Push relay used for web push; point at your own to avoid the hosted one                |
| `AUTO_SSO_ENABLED`            | No              | `false`                                   | Automatically start OAuth flow on login page (for embedded SSO)                            |
| `ALLOWED_FRAME_ANCESTORS`     | No              | `'self'` (no other site)                  | Other origins allowed to frame the app (CSP `frame-ancestors`); `'self'` is always added   |
| `NEXT_PUBLIC_PARENT_ORIGIN`   | No              | empty (bridge off)                        | Origin of the parent frame for the postMessage bridge; read at runtime                     |
| `BULWARK_JWT_AUTH_SECRET`     | No              | empty                                     | HS256 key enabling [master-user impersonation](https://bulwarkmail.org/docs/guides/impersonation.md); the route 404s while unset |
| `BULWARK_STALWART_MASTER_USER` / `_PASSWORD` | No | empty                                    | Stalwart `Admin`-role account used for impersonation                                       |
| `LIBRETRANSLATE_URL` / `_API_KEY` | No          | public MyMemory API                       | Point `/api/translate` at a LibreTranslate instance you control                            |
| `STALWART_VERSION`            | No              | empty                                     | Stalwart version to report in the telemetry heartbeat, which sends `null` without it       |
| `NEXT_PUBLIC_APP_NAME`        | Legacy fallback | -                                         | Legacy build-time fallback for `APP_NAME`                                                  |
| `NEXT_PUBLIC_JMAP_SERVER_URL` | Legacy fallback | -                                         | Legacy build-time fallback for `JMAP_SERVER_URL`                                           |

¹ Needed for env-only deployments. Otherwise the setup wizard stores the URL in the admin config, and with `ALLOW_CUSTOM_JMAP_ENDPOINT=true` users can supply it on the login form.

## Full reference

The table above is the short version. Every variable the server reads is written up individually, with defaults, dependencies, and the reasoning behind each one, on the [environment reference](https://bulwarkmail.org/docs/getting-started/configuration/environment-reference.md) page.

`STALWART_API_URL` is the one variable you may still find in old guides. Stalwart 0.16 dropped the REST self-service API it pointed at, Bulwark stopped reading it in 1.5.0, and it has since been removed from `.env.example` entirely. Delete it from your config.

## Stalwart server setup

Bulwark requires a Stalwart Mail Server with JMAP enabled, which it is by default: a fresh install serves JMAP on its HTTPS listener. [Stalwart setup](https://bulwarkmail.org/docs/getting-started/stalwart-setup.md) covers the supported versions and the server settings Bulwark depends on.

### CORS configuration

If Bulwark and Stalwart are on different domains, turn on CORS in Stalwart: **Permissive CORS policy** under **Settings > Network > HTTP > Security** in the web admin (`usePermissiveCors` on the `Http` object), or with the CLI:

```bash
stalwart-cli update Http --field usePermissiveCors=true
stalwart-cli create Action/ReloadSettings
```

## Authentication

Bulwark uses JMAP's built-in authentication. Users log in with their email credentials configured in Stalwart. Supported authentication methods:

- **Basic Auth:** username and password
- **OAuth 2.0:** if configured in Stalwart
- **App passwords:** per-client credentials users create in Settings > Security for mail and calendar apps that can't do OAuth. They don't sign in to Bulwark itself.

## Custom JMAP server endpoints

With `ALLOW_CUSTOM_JMAP_ENDPOINT=true`, the login page shows a JMAP Server field so users can connect to another server without an environment variable change. It's off by default. For a fixed list of servers, use `JMAP_SERVERS` instead.

## Theming

Light and dark themes both ship with Bulwark. The preference is stored in the browser's local storage and follows the system setting by default.

Admins pick the default theme and colour mode for new users on the admin console's Themes page, under Theme policy. The [Customization](https://bulwarkmail.org/docs/guides/customization.md) page covers building your own theme.
