Overview

The WebUI is the browser interface of a Stalwart server. Administrators use it to configure the server and inspect its operation, and users use it to manage their own accounts.

The WebUI is a web application served by the server itself. It is installed as an Application, found in the WebUI under Settings › Web Applications, and mounted at two paths:

/admin, the administration interface, for configuring the server, managing accounts and domains, and inspecting its operation
/account, the Account Manager, in which users manage their own credentials and settings

Both paths serve the same bundle. After sign-in, each opens the first area the account may use, so an administrator lands in the administration screens and a user in the Account Manager. The WebUI is available in English only.

Because the WebUI is an ordinary Application, its installation, download location, update interval and unpack directory are settings of the Application object. Applications and Updates describe them.

URLs

The WebUI and the services it relies on are reached at these URLs:

URL	Purpose
`https://<host>/admin`	Administration interface
`https://<host>/account`	Account Manager for users
`https://<host>/login`	The OAuth authorization page; it is opened by applications during sign-in and is not a page to bookmark
`https://<host>/jmap`	The JMAP API, used by the WebUI, the CLI and JMAP clients

The first start is an exception. Before any administrator exists, the server runs in bootstrap mode and serves the WebUI over plain HTTP on port 8080, reachable by IP address. This lets the setup wizard be completed before TLS certificates exist.

Administration interface

The /admin interface is a front end to the server’s configuration objects. Every form corresponds to an object, and saving the form sends a set call for that object through the management API. Anything done in a form can therefore also be done with the CLI or the API.

This documentation gives the location of each object in the WebUI, for example Management › Directory › Accounts for accounts. The interface has two main areas:

Management: the dashboard; accounts, groups, mailing lists, tenants, roles and OAuth clients; domains and DKIM signatures; the outbound queue, delivery history and delivery tests; received and sent DMARC, TLS and ARF reports; live tracing and logs; tasks and the index queue; cluster nodes; and actions, such as reloading the settings or updating the applications.
Settings: listeners, TLS, storage, authentication and directories, the MTA, the spam filter and the other server objects.

A search field at the top of the interface finds settings by name. An account that signs in at /admin without administrative permissions is sent to the Account Manager.

The WebUI signs in through the server’s built-in OAuth server, like any other OAuth application: the user authenticates on the server’s sign-in page, and the WebUI receives a token for the account.

As an installed application that ships an oauth-client.json document, the WebUI is a first-party client. The sign-in page shows its name and logo and asks for no consent, and the WebUI receives the full permissions of the account. Its client id is the static oauthClientId of the Application when one is set, and otherwise the URL of its client document, https://<host>/<prefix>/oauth-client.json. Set oauthClientId only for an external identity provider that does not support Client ID Metadata Documents (Applications).

The WebUI is recognised as a first-party client only on the server’s trusted hosts: the host of its public https URL and the hostnames of the configured JMAP, CalDAV, CardDAV and WebDAV services. Opened on another hostname, sign-in fails. To use that hostname, either add it as a service hostname, or register an OAuthClient with firstParty enabled for it. In bootstrap and recovery mode, the WebUI works on any address on which it is opened.

Two cases change the sign-in page. When the user’s domain is served by an OpenID Connect directory, the WebUI signs in at the external identity provider instead (Signing in to the WebUI). Users with two-factor authentication enter their code on the sign-in page.

Access and listeners

The WebUI needs no listener of its own. It is served by every NetworkListener with the http protocol, found in the WebUI under Settings › Network › Listeners, alongside JMAP, WebDAV and the .well-known endpoints.

Because every HTTP listener serves the WebUI, the administration interface is reachable wherever JMAP is. To expose it only internally, restrict /admin with HTTP access control and leave the other paths public.

Loading failures

The WebUI depends on a bundle that the server downloads and unpacks, so it can fail while the rest of the server works. The two common failures have different causes.

Outbound network requirement

The WebUI bundle is not part of the server binary. On the first start, the server downloads it from https://github.com/stalwartlabs/webui/releases/download/v2/webui.zip, the resourceUrl of the default Application. The server stores the bundle and reuses it until autoUpdateInterval expires or an UpdateApps action forces a download.

The server therefore needs outbound HTTPS access to GitHub’s release downloads. These are served from github.com and from the GitHub hosts that deliver release assets.

If the first download fails, there is no bundle to serve. Both /admin and /account then return 404 Not Found, while the rest of the server works normally. This is a common symptom on new installations behind a restrictive firewall. There are two fixes:

Allow the outbound access.
Download the bundle separately, copy it to the server and set resourceUrl to its file:// URL, for example file:///var/lib/stalwart/webui.zip (Outbound network access).

After one successful download, failed refreshes leave the WebUI in service.

A WebUI that shows its sign-in page but reports, after sign-in, that it could not fetch or import a module has a different cause. The files in the unpack directory have been deleted by a cleanup of /tmp, and the linked section describes the fix.