first commit

docs/PANEL.md

@@ -0,0 +1,109 @@
+# Administration panel
+
+The panel is a separate listener (default `127.0.0.1:9091`) embedded in the binary. Reach it through an SSH
+tunnel (`ssh -L 9091:127.0.0.1:9091 server`) or a VPN. It is in English by default; switch to Polish with the
+language selector (remembered per browser). Settings pages apply changes immediately, without a restart.
+
+## First login
+
+![First run](images/setup.png)
+
+On the first start there is no administrator. Generate a one-time token on the server and paste it together
+with the new login and password (at least 12 characters):
+
+```bash
+sudo -u active-push active-push admin setup-token     # valid 60 minutes, single use
+```
+
+Without a browser: `sudo -u active-push active-push admin init --username admin`.
+
+## 01 Overview
+
+![Overview](images/overview.png)
+
+- **Tiles** - requests per minute, active push connections, **devices** (physical phones, counted by DeviceId),
+  **mailboxes** (logins), mails sent, errors, failed logins and transfer. One person with several mailboxes on
+  one phone counts as one device and several mailboxes; the devices tile also shows the number of
+  partnerships (device x mailbox pairs).
+- **Charts** - traffic, synchronised items and data per minute (60 min / 6 h / 24 h), requests per hour for the
+  last 7 days. Hover a chart to read exact values.
+- **Commands**, **device types** and **server** (version, uptime, memory, IMAP pool, database and WAL size,
+  configured backends).
+
+## 02 Live
+
+![Live](images/live.png)
+
+Push connections (Ping or hanging Sync) with their heartbeat progress, requests in flight and a live stream of
+finished requests (Server-Sent Events). Filter the stream by mailbox, device or command; pause it while reading.
+
+## 03 Devices
+
+![Devices](images/devices.png)
+
+One row per **physical device**. Every mailbox configured on it is a chip; a green dot means that mailbox
+currently holds a push connection. Filters: push, pending approval, blocked, inactive for 30 days.
+
+Click a mailbox chip (or the row) to open the partnership:
+
+![Device](images/device.png)
+
+- details reported by the device (model, OS, IMEI, user agent, protocol, policy),
+- per-folder statistics (items, sent/received, last sync, window size, loop detection hits),
+- recent requests and free-form notes,
+- actions: **approve**, **full resync**, **force re-provision**, **block/unblock**, **remote wipe** (confirmed by
+  typing the device id), **cancel wipe**, **show recovery password**, **remove partnership**.
+
+All actions are written to the audit log.
+
+## 04 Mailboxes
+
+![Mailboxes](images/mailboxes.png)
+
+Every login that synchronises through ActiveSync, with its devices, the **other mailboxes on the same device**
+(useful to see one person's accounts together), push connections, requests, last activity and effective policy.
+Blocking a mailbox applies immediately on every device. Active login lockouts can be cleared here.
+
+## 05 Backends
+
+![Backends](images/backends.png)
+
+IMAP, SMTP, CalDAV and CardDAV. Each section has a **Test connection** button that uses the values currently in
+the form (also unsaved ones) and an optional test login; the password is never stored.
+
+## 06 ActiveSync
+
+![ActiveSync](images/activesync.png)
+
+Login format and default domain, e-mail address template, protocol version, synchronisation limits, push
+intervals, Autodiscover, logging and retention.
+
+## 07 Policies
+
+![Policies](images/policies.png)
+
+Provisioning switch, loose provisioning, named policies with every `policies.ini` option and per-mailbox
+assignments (`login=policy`, one per line). Changing a policy makes devices accept it again.
+
+## 08 Security
+
+![Security](images/security.png)
+
+Login lockout thresholds, trusted proxies and client IP header, network allow lists for ActiveSync and the
+panel, allowed/blocked mailboxes and device types, device approval, panel session lifetime, Prometheus token,
+administrator password change and signing out other sessions.
+
+## 09 Logs and audit
+
+![Logs](images/logs.png)
+
+Recent server log lines (level filter, search, auto refresh) and the audit trail of administrative actions.
+The log view is an in-memory ring buffer; the full log goes to journald. See [LOGS.md](LOGS.md).
+
+## Themes and small screens
+
+![Light theme](images/overview-light.png)
+
+The theme button switches between dark and light. On narrow screens the navigation collapses into a menu.
+
+<img src="images/mobile.png" alt="Mobile" width="320">