first commit

docs/MIGRATION.md

@@ -0,0 +1,58 @@
+# Migrating from Z-Push
+
+## 1. Import the configuration
+
+```bash
+python3 /usr/share/active-push/zpush-import.py /usr/share/z-push > zpush.json    # source installation
+python3 /usr/share/active-push/zpush-import.py /etc/z-push > zpush.json          # Debian packages (*.conf.php)
+less zpush.json                                                                  # review and complete
+sudo -u active-push active-push config apply zpush.json
+```
+
+The importer reads `config.php`, `backend/{imap,caldav,carddav,combined}/config.php`, `autodiscover/config.php`
+and `policies.ini`. Comments on stderr point out what needs attention (e.g. `IMAP_SMTP_METHOD = 'mail'` ->
+sendmail; switching to SMTP submission on 587 is recommended).
+
+## 2. Switch the traffic
+
+1. Install ActivePush, create the administrator, verify the backends with **Test connection** in the panel.
+2. Check the protocol with a real account:
+   `active-push probe --url https://mail.example.com/Microsoft-Server-ActiveSync --user jan@example.com`
+   (through nginx after the switch) or directly against `http://127.0.0.1:8081/...` before it.
+3. In nginx replace the `fastcgi_pass ... z-push/index.php` and `autodiscover.php` blocks with `proxy_pass`
+   (see INSTALL.md), then `nginx -t && systemctl reload nginx`.
+4. Disable the Z-Push PHP-FPM pool and the `z-push-admin` cron jobs.
+
+## 3. What happens to devices
+
+Z-Push states are not transferred (their format depends on the PHP backends). On the first connection:
+
+- the device sends its old `X-MS-PolicyKey` -> new provisioning (HTTP 449, or status 142/144 for AS >= 14),
+- the old hierarchy `SyncKey` -> `FolderSync` status 9 -> the device downloads the folder list again,
+- old folder keys -> `Sync` status 3 -> full folder synchronisation,
+- folder ids that only existed in Z-Push (e.g. `a6271970`) -> `Sync` status 12, and the next FolderSync sends a
+  **Delete** for them so the device stops using them.
+
+iOS, Android (Gmail, Samsung, Nine), Outlook and Windows Mail handle this automatically. Large mailboxes may
+take a few minutes - limit `sync.filter_time_max` or the policy `maxemailagefilter` if needed.
+
+## 4. `z-push-admin` equivalents
+
+| z-push-admin | ActivePush |
+|---|---|
+| `-a list` | `active-push device list` / panel **Devices** |
+| `-a wipe -d ID` | `active-push device wipe <id>` / **Remote wipe** button |
+| `-a remove -d ID` | `active-push device remove <id>` |
+| `-a resync -d ID` | `active-push device resync <id>` / **Full resync** |
+| `-a clearloop` | automatic - loop counter in the device details |
+| `-a fixstates` | `panel.device_inactive_days` + hourly housekeeping |
+| `z-push-top` | panel **Live** |
+
+## 5. Functional differences
+
+- **Kopano/Zarafa (MAPI)** is not supported - only IMAP/SMTP + CalDAV/CardDAV (`combined`).
+- **LDAP/SQL as sender source** (`IMAP_FROM_SQL_*`, `IMAP_FROM_LDAP_*`) is replaced by `general.email_template`.
+- **searchldap** -> GAL through CardDAV (`carddav.gal_path`); SOGo/Nextcloud expose the directory as a book.
+- **Out of office** - reading returns "disabled", setting returns an error; configure vacation in Sieve.
+- **AS 16.x** is not announced (like Z-Push with IMAP by default) - devices use 14.1.
+- Notes and SMS are not synchronised (Z-Push IMAP did not do this either).