From 38abba39f871659690aea49095aca3dfeafa5bfd Mon Sep 17 00:00:00 2001 From: Steven RYDELL Date: Sat, 1 Aug 2026 17:54:24 +0200 Subject: [PATCH] docs(readme): document fork identity, deviations policy, and UI switching Rewrite everything below the project header to actually describe this fork instead of a generic copy of upstream's README: - "About this fork" + list of official Stalwart repositories. - Corrected the "Nothing is hardcoded" overclaim; Features now lists what's shared with upstream vs. this fork's own additions, and links to SCHEMA_DEVIATIONS.md for the tracked exceptions. - New "Switching your server to this fork's UI" section: how to point a Stalwart server's WEBAPP application at this fork's release build via stalwart-cli, and how to switch back. - Support section now distinguishes fork-specific issues (this repo) from Stalwart Mail Server support (upstream channels). - License/Copyright text left untouched; added one line noting fork changes stay under the same dual license per each file's SPDX header. The project header block (logo, title, badges) is unchanged. --- README.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 69 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 8b180d3..9e4b32c 100644 --- a/README.md +++ b/README.md @@ -32,29 +32,86 @@ Matrix

+## About this fork + +This is a community fork of [stalwartlabs/webui](https://github.com/stalwartlabs/webui) maintained by [LinkPhoenix](https://github.com/LinkPhoenix), focused on UI/UX improvements: mobile-friendly layouts, dark mode polish, additional color themes, a command palette, a calendar date/time picker, and several list/form refinements. Several of these have already been contributed back and shipped in official Stalwart WebUI releases. + +**Stalwart WebUI** is a schema-driven single-page application for administering [Stalwart](https://stalw.art). After authentication the panel fetches a JSON schema from the server and dynamically generates all forms, lists, navigation, and layouts from that schema — the schema is the single source of truth, not the UI code. + +This fork tries to stay aligned with that philosophy: any AI agent or contributor working on it follows the rules in [AGENTS.md](AGENTS.md), and the small number of deliberate exceptions where the UI does something the official schema doesn't (yet) support are tracked, with the ideal server-side fix for each, in [SCHEMA_DEVIATIONS.md](SCHEMA_DEVIATIONS.md). + +See [CHANGELOG.md](CHANGELOG.md) for the full list of changes in this fork. + +Official Stalwart repositories: + +- [stalwartlabs/stalwart](https://github.com/stalwartlabs/stalwart) — the mail server itself. +- [stalwartlabs/webui](https://github.com/stalwartlabs/webui) — the official admin WebUI this project forks. +- [stalwartlabs/cli](https://github.com/stalwartlabs/cli) — `stalwart-cli`, used below to point a server at a WebUI build. + ## Features -**Stalwart WebUI** is schema-driven single-page application for administering [Stalwart](https://stalw.art). After authentication the panel fetches a JSON schema from the server and dynamically generates all forms, lists, navigation, and layouts from that schema. Nothing is hardcoded. - -Key features: +Key features (shared with upstream): - **Schema-driven UI**: All forms, lists, and navigation are generated from a JSON schema fetched from `/api/schema` after login. No object types, field names, or layouts are hardcoded. - **JMAP protocol**: All data operations (queries, creates, updates, deletes, blob uploads) use JMAP (RFC 8620) with method chaining and result references. - **Permission-aware**: Every button, link, field, and section respects the user's permissions. Elements the user cannot access are hidden. +Additions in this fork: + +- **Usable on mobile**: admin lists, forms, and the sidebar work on narrow viewports instead of assuming desktop. +- **Selectable color themes** (Stalwart, Ocean, Forest, Violet, Rose, Amber, Teal) with a light/dark toggle and a square/rounded corners option. +- **`Ctrl+K` / `Cmd+K` command palette** to search pages, form sections, and fields across the admin panel. +- **Calendar date/time picker** replacing native date inputs, themed for dark mode. +- **Accounts list**: Role and Usage/Quota columns, with a highlight and recalculate hint for stale negative disk-usage values. +- **Mailboxes list**: shown as an indented hierarchy instead of a flat list. +- **Log Entries**: client-side Level/Event filters and a rate-limited manual refresh button. + ## Screenshots ## Get Started -Stalwart WebUI is included with Stalwart Mail Server, to install Stalwart Mail Server on your server by following the instructions for your platform: +Stalwart WebUI ships as part of Stalwart Mail Server. To install Stalwart Mail Server on your server, follow the instructions for your platform: - [Linux / MacOS](https://stalw.art/docs/install/linux) - [Windows](https://stalw.art/docs/install/windows) - [Docker](https://stalw.art/docs/install/docker) -All documentation is available at [stalw.art/docs/get-started](https://stalw.art/docs/get-started). +All documentation is available at [stalw.art/docs/get-started](https://stalw.art/docs/get-started). Note that a standard Stalwart install ships the **official** WebUI; see [Switching your server to this fork's UI](#switching-your-server-to-this-forks-ui) below to point your server at this fork instead. + +## Switching your server to this fork's UI + +Stalwart serves its admin UI as a managed `WEBAPP` application, downloaded from a URL you control — switching to this fork (or back to upstream) is a server-side config change, no rebuild or redeploy of Stalwart itself required. This is done with [`stalwart-cli`](https://github.com/stalwartlabs/cli). + +On your server: + +``` +export STALWART_URL=https://subdomain.domain.com +export STALWART_USER='user@domain.com' +export STALWART_PASSWORD='Password' +``` + +Find the id of your `WEBAPP` application: + +``` +stalwart-cli query Application +``` + +Point it at this fork's latest release instead of upstream's: + +``` +stalwart-cli update Application ID WEBAPP \ + --field https://github.com/LinkPhoenix/stalwart-webui-fork/releases/latest/download/webui.zip +``` + +Then trigger the update: + +``` +stalwart-cli create Action/UpdateApps +``` + +Every tagged release of this fork publishes a `webui.zip` build via CI (see [`.github/workflows/build.yml`](.github/workflows/build.yml)), so pointing at `releases/latest/download/webui.zip` always fetches the newest tested build. To go back to the official UI, repeat the `update` step with `https://github.com/stalwartlabs/webui/releases/latest/download/webui.zip`. ## Getting started @@ -134,10 +191,11 @@ npm run preview ## Support -If you are having problems running Stalwart Mail Server, you found a bug or just have a question, -do not hesitate to reach us on [Github Discussions](https://github.com/stalwartlabs/mail-server/discussions), +For bugs or questions about **this fork's UI changes**, please open an issue on [this repository](https://github.com/LinkPhoenix/stalwart-webui-fork). + +For anything related to Stalwart Mail Server itself, do not hesitate to reach the upstream team on [Github Discussions](https://github.com/stalwartlabs/mail-server/discussions), [Reddit](https://www.reddit.com/r/stalwartlabs), [Discord](https://discord.gg/aVQr3jF8jd) or [Matrix](https://matrix.to/#/#stalwart:matrix.org). -Additionally you may purchase a subscription to obtain priority support from Stalwart Labs LLC +Additionally you may purchase a subscription to obtain priority support from Stalwart Labs LLC. ## License @@ -147,7 +205,9 @@ This project is dual-licensed under the **GNU Affero General Public License v3.0 - The [Stalwart Enterprise License v1 (SELv1)](./LICENSES/LicenseRef-SEL.txt) is a proprietary license designed for commercial use. It offers additional features and greater flexibility for businesses that do not wish to comply with the AGPL-3.0 license requirements. Each file in this project contains a license notice at the top, indicating the applicable license(s). The license notice follows the [REUSE guidelines](https://reuse.software/) to ensure clarity and consistency. The full text of each license is available in the [LICENSES](./LICENSES/) directory. - + +As a fork, all changes made here — including new files added by this fork — remain under the same dual license as the upstream project; this is reflected in the SPDX license notice at the top of every source file. + ## Copyright Copyright (C) 2024, Stalwart Labs LLC