first commit

docs/LOGS.md

@@ -0,0 +1,79 @@
+# Logging, retention and database maintenance
+
+ActivePush is designed so that nothing grows without bounds. This page lists every place where data
+accumulates and how it is limited.
+
+## Server log
+
+- Written to **stdout/stderr**, collected by **journald** under the systemd unit. ActivePush does not write
+  log files itself, so there is nothing to rotate with logrotate.
+- Level: `RUST_LOG` in `/etc/active-push/environment` (default `active_push=info,warn`).
+  `ACTIVE_PUSH_LOG_JSON=true` switches to JSON lines (ELK, Loki, Vector).
+- Size is controlled by journald. Recommended drop-in:
+
+  ```ini
+  # /etc/systemd/journald.conf.d/size.conf
+  [Journal]
+  SystemMaxUse=500M
+  SystemKeepFree=1G
+  MaxRetentionSec=30day
+  ```
+
+  then `systemctl restart systemd-journald`. Read the log with `journalctl -u active-push -f`.
+- Volume at `info` is roughly one line per notable event (new device, provisioning, failed login, sent
+  mail, errors) - routine Sync/Ping requests are not logged individually.
+- **Debug WBXML** (`logging.log_wbxml` or `logging.debug_users`) logs full requests and responses including
+  message bodies. Enable it only for a short diagnosis and for chosen mailboxes.
+
+If you redirect output to a file yourself (e.g. a container without journald), rotate it with
+`copytruncate`:
+
+```
+/var/log/active-push/active-push.log {
+    daily
+    rotate 14
+    compress
+    missingok
+    notifempty
+    copytruncate
+}
+```
+
+## In-memory buffers (panel)
+
+| Buffer | Limit |
+|---|---|
+| Log viewer | `logging.ring_size` lines (default 2000, 100..100000) |
+| Live request stream | last 500 requests |
+| Minute statistics | 24 hours (1440 buckets) |
+| Active mailbox tracking | entries older than 24 h are pruned every minute |
+| Failed login counters / lockouts / login cache | expire automatically, pruned every minute |
+| Loop detection, stale collections, time zone cache | bounded and expiring |
+
+All of these are lost on restart by design; persistent history is in the database.
+
+## Database
+
+`/var/lib/active-push/active-push.db` (SQLite, WAL). Hourly housekeeping:
+
+| Data | Retention |
+|---|---|
+| Hourly statistics | `logging.stats_retention_days` (default 90) |
+| Audit log | `logging.audit_retention_days` (default 365) |
+| Panel sessions, setup tokens | removed when expired |
+| Devices not seen for `panel.device_inactive_days` (default 180, `0` = never) | removed with their sync states and folder statistics; a device that returns later simply resynchronises |
+| Sync states | at most two per folder and device (current + previous for retries); removed with the device, on folder deletion and on FolderSync reset; states untouched for more than 400 days are dropped |
+| Folder/item id maps | removed for mailboxes that no longer have any device |
+| WAL file | checkpointed and truncated every hour |
+| Free pages | incremental auto-vacuum (databases from 0.1.0 are converted once automatically) |
+
+Typical size: a few hundred kilobytes per device, mostly sync states of large mail folders. The panel shows
+the database and WAL size on the Overview page (**Server** card).
+
+## Backups
+
+```bash
+sqlite3 /var/lib/active-push/active-push.db ".backup '/root/active-push-$(date +%F).db'"
+```
+
+Losing the database never loses mail data: devices perform a full resynchronisation.