HOSTNAME=0.0.0.0    # Default; use "::" for IPv6
PORT=3000

OAUTH_ENABLED=true
OAUTH_ONLY=true                   # hide the username/password form entirely
OAUTH_CLIENT_ID=webmail
OAUTH_CLIENT_SECRET=              # optional, for confidential clients
OAUTH_CLIENT_SECRET_FILE=         # path to a file containing the secret
OAUTH_ISSUER_URL=                 # optional, for external IdPs
OAUTH_AUTHORIZE_URL=              # override only the user-facing authorize endpoint
OAUTH_ALLOW_PRIVATE_ENDPOINTS=    # allow discovery to resolve to RFC-1918 addresses

OAUTH_SCOPES=                     # replace the requested scopes (space-separated)
OAUTH_EXTRA_SCOPES=               # append to the defaults instead of replacing them
AUTO_SSO_ENABLED=true             # skip the login form, go straight to the IdP

Endpoints are auto-discovered via .well-known/oauth-authorization-server or .well-known/openid-configuration. OAUTH_ALLOW_PRIVATE_ENDPOINTS is off by default as an SSRF guard. Enable it only for split-DNS deployments where the issuer's public hostname resolves to an internal IP.

BULWARK_TELEMETRY=on                 # opt-in; off by default
TELEMETRY_DATA_DIR=./data/telemetry  # instance id and consent; mount a volume

Off unless you turn it on, in the admin UI, the installer, or here. Heartbeats carry version, platform, bucketed account counts, and feature toggles. No email addresses, hostnames, or IPs. Setting the variable (to either value) locks the choice and disables the admin toggle.

SESSION_SECRET=                      # openssl rand -base64 32
SESSION_SECRET_FILE=/session-secret  # path to a file containing the secret

SETTINGS_SYNC_ENABLED=true
SETTINGS_DATA_DIR=./data/settings    # mount as a volume in Docker

Credentials are encrypted with AES-256-GCM and stored in an httpOnly cookie (30-day expiry). Settings sync stores per-account preferences encrypted at rest and requires SESSION_SECRET.

ALLOW_CUSTOM_JMAP_ENDPOINT=true

JMAP_SERVERS=[{"id":"eu","label":"Europe","url":"https://eu.example.com","domains":["example.com"]},{"id":"us","label":"US","url":"https://us.example.com"}]
JMAP_SERVER_AUTO_PICK_BY_DOMAIN=true

ALLOW_CUSTOM_JMAP_ENDPOINT shows a "JMAP Server" field on the login form. External servers must CORS-allow the webmail origin.

JMAP_SERVERS offers a fixed list instead; each entry needs id, label, and url, and may carry domains and its own oauth block. With JMAP_SERVER_AUTO_PICK_BY_DOMAIN, the domain of the address the user types selects the server. The admin dashboard manages the same list — the env form is for stateless deployments.

APP_NAME=My Webmail
APP_SHORT_NAME=Webmail
APP_DESCRIPTION=Your personal mail

FAVICON_URL=/branding/favicon.svg
PWA_ICON_URL=/branding/icon.svg      # falls back to FAVICON_URL
PWA_THEME_COLOR=#3b82f6
PWA_BACKGROUND_COLOR=#ffffff

APP_LOGO_LIGHT_URL=/branding/logo-light.svg
APP_LOGO_DARK_URL=/branding/logo-dark.svg
LOGIN_LOGO_LIGHT_URL=/branding/login-light.svg
LOGIN_LOGO_DARK_URL=/branding/login-dark.svg

LOGIN_COMPANY_NAME=My Company
LOGIN_WEBSITE_URL=https://example.com
LOGIN_IMPRINT_URL=https://example.com/imprint
LOGIN_PRIVACY_POLICY_URL=https://example.com/privacy

# Web push goes through a hosted relay, so no VAPID keys or Firebase project
# of your own. Point this at your own relay to opt out. Build-time variable.
NEXT_PUBLIC_PUSH_RELAY_URL=https://notifications.relay.bulwarkmail.org

# Per-domain overrides (optional). When the webmail is served on multiple
# hostnames, each host can override any subset of the branding fields above.
# Match is on the request Host (or X-Forwarded-Host). Use "*.example.com" to
# match any subdomain. Unset fields fall back to the global values.
DOMAIN_BRANDING=[{"host":"maildomain1.com","loginCompanyName":"Company One","loginLogoLightUrl":"/branding/one.svg"},{"host":"maildomain2.com","loginCompanyName":"Company Two"}]

EXTENSION_DIRECTORY_URL=https://extensions.bulwarkmail.org
PLUGIN_DEV_DIR=../my-plugins          # load plugins from disk instead of ZIPs

EXTENSION_DIRECTORY_URL enables the admin marketplace for browsing and installing plugins and themes. PLUGIN_DEV_DIR is for plugin authors: each immediate subfolder is one plugin with a manifest.json, and an entrypoint under src/ is bundled on demand with esbuild, so editing sources needs only a browser refresh.

Sandboxed plugins that integrate provider-side labels can use the native api.keywords facade exposed by @plugin-host:

const api = require('@plugin-host');

const known = await api.keywords.list();                 // settings:read
const scan = await api.jmap.getKeywords();               // email:read
const providerLabel = scan.labels
  .find((label) => label.id.startsWith('$label:'));
if (providerLabel) {
  await api.keywords.add([{                              // settings:write
    id: providerLabel.id.slice('$label:'.length),
    label: providerLabel.name,
    // color is optional; Bulwark picks a palette colour when omitted
    visibility: 'show',
  }]);
}
const counts = await api.keywords.refreshCounts();        // email:read

// Complete replacement: keywords omitted here are removed from the message.
await api.jmap.setKeywords('email-id', {                 // email:write
  '$seen': true,
  '$label:provider-label-id': true,
});
await api.jmap.setKeyword('email-id', '$label:work');     // email:write
await api.jmap.removeKeyword('email-id', '$label:work');  // email:write

jmap.getKeywords() is a narrow read-only facade rather than an arbitrary JMAP request API. When the JMAP server advertises https://bulwarkmail.com/ns/jmap/keywords, it returns all cached keywords with exact total/unread counts and provider-label metadata, including empty provider labels. On servers without the capability it falls back to a bounded scan of message keywords. keywords.discover() retains its original message-scan response for compatibility.

jmap.setKeywords() replaces one message's complete keyword map via Email/set. Omitted keywords are removed, so extensions should use the existing jmap.setKeyword() and jmap.removeKeyword() methods for incremental edits. The existing email.setKeyword() and email.removeKeyword() names remain as compatibility aliases.

keywords.add() is append-only and case-insensitive by id: it returns added and skipped definitions without overwriting the user's existing label name, colour, visibility, or order. Keyword discovery reports whether its bounded scan was complete.

STALWART_FEATURES=true               # password change, Sieve filters, etc.

LOG_FORMAT=text                      # "text" or "json"
LOG_LEVEL=info                       # error | warn | info | debug

ADMIN_CONFIG_DIR=./data/admin        # operator-authored: config.json, policy.json, plugins/, themes/
ADMIN_STATE_DIR=./data/admin-state   # runtime: audit log, login timestamps, setup token
ADMIN_CONFIG_READONLY=true           # enforce read-only mode at the app layer

The split lets you mount the config volume read-only after the setup wizard completes. Legacy installs that pre-date the split keep working through ADMIN_DATA_DIR.

The UI language follows each visitor's Accept-Language header and their stored preference. NEXT_PUBLIC_DEFAULT_LOCALE sets the fallback used when neither matches a supported locale (default en):

NEXT_PUBLIC_DEFAULT_LOCALE=de

Supported: ar, ca, cs, da, de, en, es, fa, fr, he, hu, it, ja, ko, lv, nl, pl, pt, ro, ru, sk, tr, uk, zh. An unsupported value falls back to en.

Like NEXT_PUBLIC_BASE_PATH, this is read at build time. To use it with the published Docker image, build your own:

docker build --build-arg NEXT_PUBLIC_DEFAULT_LOCALE=de -t bulwark-webmail .

To serve the webmail at a subpath (e.g. https://example.com/webmail):

NEXT_PUBLIC_BASE_PATH=/webmail
NEXT_PUBLIC_LOCALE_PREFIX=always     # avoids next-intl rewrite loops

Unlike most other variables, NEXT_PUBLIC_BASE_PATH is read at build time because Next.js bakes it into emitted asset URLs. To use it with the published Docker image, build your own image with the variable set:

docker build --build-arg NEXT_PUBLIC_BASE_PATH=/webmail -t bulwark-webmail .

Then point your reverse proxy at the container without stripping the prefix. The app expects requests under /webmail/... and serves every route (/webmail/api/..., /webmail/_next/static/..., /webmail/sw.js, and so on) accordingly.