How to Set Up Stalwart Mail Server in an Offline (Air-Gapped) Environment?

Questions
1

Your question

Hi Stalwart Team,

I would like to deploy Stalwart Mail Server in an offline (air-gapped) environment where there is no internet access.

I have a few questions:

  1. Is it possible to install and run Stalwart completely offline?
  2. Which files or binaries should I download in advance?
  3. If using Docker, what is the recommended way to export the required Docker images from an internet-connected machine and import them into the offline server?
  4. Are there any dependencies or services that require internet access during installation or first startup?
  5. Is there any official documentation or recommended procedure for offline deployment?
  6. Are there any features that will not work in an offline environment?

Our goal is to deploy and operate Stalwart entirely within an isolated network without internet connectivity.

Any guidance or best practices would be greatly appreciated.

Thank you.

I understand that topics in this category are triaged by a bot first but a human reply will follow up. If I’d prefer a human-only reply, I’ll add the no-ai tag to my topic.

on

2

Let me pull the full outbound network requirements section for details.

Stalwart can run entirely offline once installed, but a few specific features rely on outbound internet access. Here’s what to plan for:

1. Can it run fully offline? Yes, the core mail/collaboration server (SMTP, IMAP, JMAP, POP3, WebDAV) has no runtime dependency on the internet. A handful of optional features do reach out over HTTPS, and you can work around each of them (details below).

2. What needs internet access, and how to avoid it:

  • WebUI: The admin console (/admin) and account manager (/account) are not bundled with the server binary. On first start, Stalwart downloads the WebUI bundle from https://github.com/stalwartlabs/webui/releases/latest/. If that download fails and no local copy exists, /admin and /account return 404 Not Found. Workaround: download the WebUI release bundle on an internet-connected machine, host it on an internal HTTPS server, and point the WebUI Application record’s resourceUrl at your internal server instead.
  • ACME (Let’s Encrypt): automatic TLS certificate issuance contacts the ACME directory (default https://acme-v02.api.letsencrypt.org/directory). In an air-gapped setup you’d instead supply your own certificates manually rather than using ACME.
  • Public DNS: SPF/DKIM/DMARC/MX lookups and DNSBL/DNSWL spam-list queries require outbound DNS. In a closed network you’d need an internal resolver serving whatever zones you rely on, and DNS-based blocklists simply won’t function without reachable public DNSBL providers (this is an optional spam-filter feature, not required to run mail).

3. Docker images: On an internet-connected machine, pull the image (docker pull stalwart/mail-server:vX.Y or GHCR equivalent), then export/import it for the air-gapped host:

docker pull stalwart/mail-server:v0.16
docker save stalwart/mail-server:v0.16 -o stalwart.tar
# transfer stalwart.tar to the offline host
docker load -i stalwart.tar

Pin to a specific v<major>.<minor> tag rather than latest for reproducibility. See the Docker install docs.

4. Files/binaries to download in advance:

  • The Stalwart server Docker image (or the Linux binary via the install script if not using Docker)
  • The WebUI release bundle (if you want the admin console/account manager to work)
  • Any TLS certificates you plan to use manually (since ACME won’t be reachable)

5. Official offline-specific procedure: There isn’t a dedicated “air-gapped deployment” guide, but the System Requirements / Outbound network requirements page documents exactly which features need egress and how to substitute internal endpoints, which covers your scenario.

6. Features that won’t work offline: WebUI/admin console (until you self-host the bundle), ACME automatic certificate issuance/renewal, DNS-based blocklist/allowlist spam checks, and any other hosted Applications that rely on external resourceUrls. Core mail delivery, storage, JMAP/IMAP/SMTP protocols, and CLI-driven management all work fine fully offline.

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong.

3

Yes, it runs fully offline. The one thing that will bite you on first boot is the WebUI: it ships as a downloadable Application bundle that the server fetches from GitHub on first start, and if that fetch fails then every WebUI route returns 404 while the mail server itself carries on working normally. That’s almost always what “I installed it air-gapped and the admin UI is 404” turns out to be.

The fix is to change resourceUrl on the WebUI’s Application record. It takes an internal HTTPS URL, and it also accepts file:///path/to/bundle.zip, so you can stage the zip on the host and skip running a web server for it entirely. Once one download has succeeded, later failures are non-fatal.

To stage: the server tarball or the Docker image, the WebUI bundle, and your licence string if you’re on Enterprise. Don’t run install.sh on the isolated box, it’s a downloader pointed at GitHub releases. For Docker, pull on a connected machine, then docker save and docker load across, keeping /etc/stalwart and /var/lib/stalwart as volumes.

There’s no offline deployment page at the moment. What degrades without internet: DNSBL and DNSWL lookups, MTA-STS and DANE, SPF/DKIM/DMARC verification of anything originating outside your network, ACME (use manually installed certificates), OIDC against an external IdP, and spam filter definition updates. Enterprise licensing is fine, it validates offline from the embedded signature with no call home.