Docs / GuidesUpdated MarkdownEdit on GitHub
Not in Lite. The admin console is part of Bulwark (not Lite). Lite reads its settings from config.json and policy.json.

Admin console

The admin console runs inside the same process as the user-facing app. It holds the server and sign-in settings, branding, the user policy, the Organisation pages, plugins, themes, the marketplace, updates, usage stats and the audit log. Each page has its own address under /admin.

API keys and app passwords are not here. Each user manages their own under Settings > Security; see Account security.

Note. Bulwark Lite has no admin console and no setup wizard. Its configuration is a config.json file next to index.html, and an optional policy.json for the settings policy. See static hosting.

First-time setup

The web setup wizard runs on first launch and sets the initial admin password along with JMAP, OAuth, branding, and the session secret. Point a browser at the running container and follow the steps; nothing needs to be in .env.local beforehand.

ADMIN_PASSWORD in the environment is a bootstrap value for env-driven deployments: it is read only while admin.json does not exist yet, then hashed and written there. Once a password exists, change it from the admin console.

File-based secrets

For Docker / Kubernetes secret mounts, the JSON config supports pointing at a file instead of inlining the secret. Set these keys to the path of a file holding the value: passwordHashFile in admin.json, the other two in config.json. Both files are in ADMIN_CONFIG_DIR.

  • passwordHashFile - admin password hash (alternative to inline passwordHash)
  • sessionSecretFile - session secret (alternative to SESSION_SECRET / SESSION_SECRET_FILE)
  • oauthClientSecretFile - OAuth client secret (alternative to OAUTH_CLIENT_SECRET / OAUTH_CLIENT_SECRET_FILE)

Admin storage split

Admin data lives in two directories, so the operator-authored config volume can be remounted read-only once the wizard has finished:

ADMIN_CONFIG_DIR=/app/data/admin        # config.json, policy.json, plugins, themes, branding uploads
ADMIN_STATE_DIR=/app/data/admin-state   # audit log, login timestamps, setup token
ADMIN_CONFIG_READONLY=true              # optional: produce clean errors instead of EROFS

Unset, they are ./data/admin and ./data/admin-state. If you set only ADMIN_CONFIG_DIR, state goes to ADMIN_CONFIG_DIR/state, so set ADMIN_STATE_DIR as well before you mount the config dir read-only. Existing pre-1.6.4 installs using the legacy single ADMIN_DATA_DIR continue to work without migration.

volumes:
  - bulwark-config:/app/data/admin            # rw during setup
  # - bulwark-config:/app/data/admin:ro       # ro after the wizard completes
  - bulwark-state:/app/data/admin-state       # always rw

Without a persistent volume a restart loses admin.json and config.json. Bulwark then takes the password from ADMIN_PASSWORD again. Without that variable there is no admin password, and only a Stalwart administrator can get in, through STALWART_ADMIN_ACCESS=auto (see below). If JMAP_SERVER_URL isn't set either, the setup wizard runs again with a new token in the logs. Losing the state dir also loses a session secret Bulwark generated, which signs everyone out.

Signing in

The admin console lives at /admin (below the base path if you set one). It uses a separate session from the user app, so you can be signed in as both a regular user and an admin in the same browser.

What a Stalwart administrator account is worth here is configurable, under Authentication in the admin console or with STALWART_ADMIN_ACCESS:

ValueEffect
auto (default)Stalwart admins see the admin shield in the app and are signed into /admin without the Bulwark admin password
passwordStalwart admins see the shield but must enter the Bulwark admin password like everyone else
offStalwart admin status is ignored; /admin is reachable only through /admin/login with the admin password

password and off need an admin password to exist, from the wizard or ADMIN_PASSWORD, or the admin console would have no way in.

Additional admin accounts, under Authentication > Admin access, lists mail accounts that get the same access as Stalwart admin accounts without an admin role in Stalwart, and follow the setting above. Each entry is tied to one configured mail server. The account has to match the name the mail server reports for the signed-in user; upper and lower case of ASCII letters count as the same. The list can only be set in the admin console, not in the environment. Removing an entry doesn't end an admin session that is already open.

Admin sessions are protected with:

  • Strict session secret length validation
  • Configurable TTL via ADMIN_SESSION_TTL
  • Configurable trusted-proxy depth via TRUSTED_PROXY_DEPTH for accurate client IP attribution
  • All admin actions are written to the audit log

Sections

The admin console: server details and enabled features, with the section list on the left The admin console: server details and enabled features, with the section list on the left

The sidebar starts with Overview, Server, Authentication, Branding and User policy. Under Organisation are Domains and groups, Signatures, Templates, Security and Sharing; under Extensions, Plugins, Themes and Marketplace; under System, Updates, Usage stats and Audit log.

Overview

Warnings that need attention, the number of accounts, plugins and themes, the running version, the server details (application, storage, JMAP server, last admin login, whether settings sync, OAuth and the Stalwart integration are on) and the latest admin actions. Storage says "Local files on this server" for a single instance, or, with several instances, "Shared store" and how many instances checked in during the last minute.

Server, Authentication and Branding

Override runtime config without redeploying. These pages write to ADMIN_CONFIG_DIR/config.json (same file the setup wizard populates). Most of the keys below are on Server; the OAuth, SSO, admin access and framing keys are on Authentication, and the images and company details on Branding. Admin-managed values fill these keys:

  • appName
  • jmapServerUrl, plus the jmapServers list for multi-server deployments
  • oauthEnabled, oauthOnly, oauthClientId, oauthIssuerUrl
  • stalwartFeaturesEnabled, and separately stalwartJmapPassthroughEnabled, the server-side switch for the credential-bearing Stalwart JMAP passthrough. Turn it off to keep the client features but block the passthrough route entirely (env: STALWART_JMAP_PASSTHROUGH_ENABLED)
  • stalwartAdminAccess (see above)
  • settingsSyncEnabled
  • allowedFrameAncestors
  • parentOrigin
  • Branding (favicon, app and login logos, login company info)
  • Demo mode
  • allowCustomJmapEndpoint
  • autoSsoEnabled
  • searchEngineIndexing - allow search engines to index the webmail. Off by default (emits noindex/nofollow in the page head); recommended off for private deployments. Env override: SEARCH_ENGINE_INDEXING.

Order of precedence: admin config > env var > legacy build-time fallback > built-in default. A value saved here wins over the same key in .env.local; the admin console shows where each value currently comes from (admin, environment, or default). Changes from the admin console take effect on the next user session without a restart.

User policy

Which features users get, the push relays they may pick (from your list, rather than typed as a free URL), the default sidebar apps every user gets in addition to the ones they pin themselves, and the settings to lock, hide or preset. These are stored in policy.json, not config.json. The Organisation pages add per-domain and per-group settings; see Organisation settings.

The User policy page in the admin console, with some features switched off and settings locked to a value The User policy page in the admin console, with some features switched off and settings locked to a value

Recipient directory, on the same page (Features and settings in the sidebar), narrows the server accounts people see in the contacts directory, recipient suggestions, sharing, delegation, free/busy and plugins' directory lookups:

  • Own domains only: shows only accounts in the domains of the signed-in account's addresses, aliases included. Accounts whose name isn't an address are left out.
  • Hidden accounts: account names (the part before the @), separated by commas, hidden in every domain, such as noreply.

In policy.json they are directorySameDomainOnly and directoryHiddenLocalparts. Both change what Bulwark shows, not what Stalwart answers. With directory queries on, any signed-in user can still list all accounts through Stalwart's API.

Plugins

The Plugins section of the admin console The Plugins section of the admin console
  • Install plugins from the marketplace (the official directory unless EXTENSION_DIRECTORY_URL points elsewhere) or upload a ZIP. Plugins installed here are for every user.
  • Plugins as a whole are off until you turn on Plugins under Plugin policy.
  • Users can also upload plugins for their own account while Users may upload plugins is on (the default). With Require approval (also the default) each upload stays off until an admin approves it under Approval requests.
  • Turn an installed plugin on or off, or open it and turn on Force on for everyone so users can't turn it off.
  • Settings you save on a plugin's page apply to every user.
  • Review each plugin's manifest, declared permissions, frameOrigins, and httpOrigins.
  • Configure a plugin in its inline config panel, without leaving the page.
  • Hot-reload and PLUGIN_DEV_DIR dev-folder loading for live plugin development (esbuild bundles src/ on demand).

See Plugins for the full architecture.

Themes

  • Upload theme ZIP bundles, or install them from the marketplace, for every user. Users can upload their own themes while Users may upload themes is on (the default).
  • Turn installed themes on or off, or force one on for everyone.
  • Set the default theme and colour mode, lock the colour mode, and hide the themes you don't want users to pick under Offered to users.
  • Theme API v2, with a token compiler and a skin slot.

Audit log

Every admin action (sign-in, config and policy changes, plugin and theme changes) is recorded. Audit log shows the time, the action, its details (old and new values for config changes) and the client IP (after TRUSTED_PROXY_DEPTH resolution).

The Audit log in the admin console, listing admin actions with their time, details and client IP The Audit log in the admin console, listing admin actions with their time, details and client IP

OAuth auto-setup

Where the Stalwart server supports it, a dialog validates the origin and issuer URLs and configures the OAuth client end to end, which gets SSO working without hand-editing config. It is under Authentication, OAuth / OpenID Connect, as Set up with Stalwart. It runs as the Stalwart account signed in to the webmail in the same browser, which needs admin permissions. On Stalwart 1.0.3 and later, or with no account signed in, the dialog asks for a Stalwart admin sign-in instead: a password, an app password or an API key, used for this setup only and not stored.

On Stalwart 1.0, run it once even if you don't use SSO. It gives Bulwark's client the access users who sign in with a two-factor code need for their account security settings: Stalwart's full scope (or security and settings when you aren't a superuser) on 1.0.3 and later, first-party on 1.0.0 to 1.0.2. Everyone who is signed in then has to sign in again. Turn Enabled off afterwards if you don't want the SSO button. See Upgrading to Stalwart 1.0.

On Stalwart 1.0 the setup also registers a client for Bulwark Mobile: bulwark-mobile, with the same access, no secret and the redirect URI org.bulwarkmail.mobile:/auth/callback. The app signs in through it and can then show the account security settings. Without it the app registers a client of its own, which reaches mail, contacts, calendars and files but not those settings. Don't add the app's redirect URI to the bulwark-webmail client instead: that client has a secret the app can't send, so its sign-in fails.

Usage stats

Usage stats (under System) shows the exact JSON the next heartbeat would send, turns heartbeats on or off, sends one now while they are on (Send now), changes the collector URL and shows when the last one went out. Setting BULWARK_TELEMETRY in the environment, to either value, locks the choice and greys out the toggle; no-third-party mode locks it off. See Anonymous usage stats for the full schema.

Behind a reverse proxy

If Bulwark sits behind multiple reverse proxies, set TRUSTED_PROXY_DEPTH so audit logs and rate-limiting see the real client IP:

TRUSTED_PROXY_DEPTH=2   # CDN -> ingress -> app

Restricting access

The admin console is part of the running Bulwark process, so it cannot be turned off. Restrict it instead:

  • Block /admin and /api/admin at your reverse proxy and only allow your management network.
  • Use a strong admin password and change it from time to time with Change password in the console. Changing ADMIN_PASSWORD later has no effect once admin.json exists.
  • Keep it off the public internet in production. A VPN or an IP allowlist is the right gate.

Troubleshooting

"Admin password reset on restart"

You haven't mounted a persistent volume for ADMIN_CONFIG_DIR (or ADMIN_DATA_DIR on legacy installs), so the password hash file is lost on container recreation. Mount the volume and either rerun the setup wizard or (re)set ADMIN_PASSWORD.

"Settings > Security missing"

Account security, API keys and app passwords are user settings, not part of the admin console. They need Stalwart 0.16 or newer, STALWART_FEATURES and the JMAP passthrough (STALWART_JMAP_PASSTHROUGH_ENABLED) left on (both are on by default), and on Stalwart 1.0 Bulwark 1.18.0 or newer with OAuth auto-setup run once. Stalwart versions before 0.16 do not expose the JMAP x: methods Bulwark uses for self-service management.

"Admin login fails with correct password"

Check that SESSION_SECRET hasn't changed since you last signed in (which would invalidate stored sessions) and that the admin data directory is on a writable filesystem.

Next step

For the settings an organisation makes for its users, such as signatures, external mail and sign-out times, go on to Organisation settings.