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.
This commit is contained in:
Steven RYDELL
@@ -32,29 +32,86 @@
|
||||
<a href="https://matrix.to/#/#stalwart:matrix.org"><img src="https://img.shields.io/matrix/stalwartmail%3Amatrix.org?label=Join%20Matrix&logo=matrix&style=flat-square" alt="Matrix"></a>
|
||||
</p>
|
||||
|
||||
## 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
|
||||
|
||||
<img src="./img/demo.gif">
|
||||
|
||||
## 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
|
||||
|
||||
@@ -148,6 +206,8 @@ This project is dual-licensed under the **GNU Affero General Public License v3.0
|
||||
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user