Inability to access Web UI due to network failure when downloading webui.zip at runtime (v0.16 Docker image)

[sweetlazyboy]

Hi everyone,

I’ve been testing the official Docker image stalwartlabs/stalwart:v0.16 (including the -alpine variant) and encountered a critical issue in environments where the container cannot reach GitHub.

Problem description

When the container starts for the first time, it runs in bootstrap mode and attempts to download webui.zip from
https://github.com/stalwartlabs/webui/releases/latest/download/webui.zip.
If the download fails (due to proxy settings, firewalls, or any network restriction), the web UI is never served. The /admin endpoint returns a 404 JSON response, and there is no way to complete the initial setup.

The logs show:

ERROR Resource error ... Failed to fetch https://github.com/.../webui.zip

This makes it impossible to use the mail server in air‑gapped or restricted networks, even though the container itself runs perfectly fine.

Why this is a problem

Container images are expected to be self‑contained. Downloading essential components at runtime breaks reproducibility and adds an external dependency that many production environments cannot satisfy.

The setup wizard is the only documented way to perform the initial configuration for most users; without it, the software is essentially unusable.

Even when a proxy is configured for Docker, the container’s internal environment may not inherit it, forcing users to debug networking inside the container.

Proposed solution

Please consider bundling the web UI directly inside the Docker image (e.g., in /opt/stalwart/webui) or provide an official “full” image variant that includes the UI.

Alternatively, if the dynamic download is kept for size reasons, the image should at least:

Fall back to a local copy when the download fails (e.g., by allowing users to mount a pre‑downloaded webui.zip into a well‑known location).

Clearly document the required URLs and proxy requirements in the startup guide.

Workarounds attempted

Manually entering the container and downloading/unzipping webui.zip to /opt/stalwart/webui solves the issue, but this is non‑obvious and contradicts the principle of immutable containers.

Thank you for considering this improvement. Stalwart is a great project, and making it more robust in restricted environments would benefit many self‑hosters and enterprises.

Best regards

[mdecimus]

You need network access to use the WebUI, if that is not possible then you'll have to rely on the CLI.

[Jip-Hop]

Perhaps it would be an idea to release the webui as a docker image instead of a zip file (suggested here)? That way we could let the container runtime worry about retrieving the data.

[jakguel]

Honestly, who thinks that downloading a part of the code in Runtime is good and safe practice? When I take something productive, I expect a finished product or container that doesn't download and run anything else via sideloading.
I have to build my own Container now and maintain a clone just because of this.

Just to show what you have to deal with in a enterprise environment:

• Container Images need to be mirrored and scanned before going produktive. WEB UI Content is completely missing here whilst the scan.
• Containers are not allowed sideloading executable code form external sources : This is an attack vector!
• Even if we would allow sideloading and ignore the fact that the webui code is not scanned before we run it: I can not even mirror the zip file, so when github is not reachable my services fail when starting.