docs: admin guide (install, voip.ms, network, E911, troubleshooting, updating)

docs/admin-guide/: install and the setup wizard, voip.ms with screenshots, NAT and SIP
ALG, firewall (ufw, nftables limited to the voip.ms POP), fail2ban and CrowdSec, E911
duties, recording consent, troubleshooting (08 §3.3), updating, backup and restore,
monitoring and log rotation. scripts/update.sh as 08 §3.1 describes. The e2e checks
fail2ban's and CrowdSec's stock Asterisk rules against a real failed sign-in, takes the
screenshots and checks every link and anchor.

Task: M11-T7

docs/admin-guide/README.md

@@ -0,0 +1,114 @@
+# SelfPhoneNG admin guide
+
+This guide takes you from an empty server to working inbound and outbound calls, then covers
+keeping the system safe, legal and up to date.
+
+1. **Install** (this page)
+2. [voip.ms setup](voipms.md): the sub-account, numbers and the trunk
+3. [Network, firewall and attacks](network.md): NAT, SIP ALG, ports, firewall, fail2ban / CrowdSec
+4. [Emergency calls and recording law](legal.md): E911 duties and call recording consent
+5. [Troubleshooting](troubleshooting.md)
+6. [Updating, backups and monitoring](maintenance.md)
+
+---
+
+## What you need
+
+- A Linux server (a VM is fine) with a **public IP** or a router you can forward ports on.
+  A small office needs very little: 1–2 CPUs and 2 GB of memory is plenty.
+- **Docker Engine with the compose plugin**: <https://docs.docker.com/engine/install/>.
+  Check with `docker compose version`.
+- `git` and `openssl` (both are on almost every Linux install).
+- A **DNS name** for the server, e.g. `pbx.example.com`, with an A record pointing at its public IP.
+  Browsers need HTTPS for the microphone, so the browser phone only works through this name.
+- A **voip.ms account** with at least one phone number (DID). Other SIP providers work as a
+  "generic" trunk, but this guide uses voip.ms.
+
+## Ports
+
+Open these to the internet (on the server's firewall, and forwarded on your router if the
+server is behind one; see [Network](network.md)):
+
+| Port | Protocol | For |
+|---|---|---|
+| 443 | TCP | Web app, browser phone, phone setup files |
+| 80 | TCP | Only with the bundled Caddy: getting the HTTPS certificate |
+| 5060 | UDP (+TCP) | SIP: voip.ms and desk phones |
+| 5061 | TCP | Only if you turn on SIP over TLS |
+| 10000–20000 | UDP | Call audio (RTP) |
+
+Everything else (the database, the api on 8080, Asterisk's 5038 and 8088) listens on
+127.0.0.1 only. Don't open them.
+
+## Install
+
+```sh
+git clone https://git.dou.bet/spng/selfphoneng.git
+cd selfphoneng
+./scripts/install.sh
+```
+
+The script:
+
+1. Checks Docker is there.
+2. Writes `.env` with random passwords and asks for:
+   - the **public host name** (`pbx.example.com`),
+   - the **first admin's email and password** (at least 10 characters).
+3. Makes the `data/` folders.
+4. Asks **"Use bundled Caddy for HTTPS?"**
+   - **Yes**: Caddy gets a Let's Encrypt certificate for your host name by itself. Ports 80 and
+     443 must reach the server and nothing else may use them.
+   - **No**: you already run a reverse proxy. Copy `deploy/nginx/selfphoneng.conf.example`,
+     put in your host name and certificate paths, and reload nginx. Any proxy works if it sends
+     `/ws` to `127.0.0.1:8088` (the browser phone's WebSocket) and everything else to
+     `127.0.0.1:8080`, with WebSocket upgrades allowed on both.
+5. Builds and starts everything. The first build compiles Asterisk, so it takes a while.
+
+When it's done, check the health URL on the server:
+
+```sh
+curl http://127.0.0.1:8080/healthz      # {"ok":true}
+```
+
+> **Keep `.env` safe and never change `APP_SECRET`.** It encrypts the SIP and trunk passwords in
+> the database, and backups can only be restored with it. Copy `.env` somewhere safe (a password
+> manager) now.
+
+## First sign-in: the setup wizard
+
+Open `https://pbx.example.com/` and sign in with the admin email and password you gave the
+script. You're asked to pick a new password, then the setup wizard walks you through:
+
+| Step | What to do |
+|---|---|
+| Company | Name and time zone (office hours and reports use it). |
+| Network | The **public IP** (Detect fills it in) and the **local networks**. Do the router steps shown there: SIP ALG off and the port forwards ([Network](network.md)). |
+| Email | Your SMTP server, then **Send test**. Voicemail-to-email and alerts need it. |
+| Trunk | Your voip.ms sub-account ([voip.ms setup](voipms.md)). Wait for **Registered**. |
+| Phone numbers | Add your DIDs, or **Import numbers from voip.ms** if you gave API details. |
+| Users | People and their extensions. |
+| Main number | Where calls to your main number go. |
+| Emergency | The **default emergency caller ID** (required once a trunk exists) and who's told when someone dials 911 ([E911](legal.md#emergency-calls-e911)). |
+
+You can leave the wizard and come back; everything it sets is also in the admin pages.
+
+Then:
+
+- **Place a test call out.** From a desk phone, or from the browser phone (a user with an
+  extension signs in and calls from **My phone**), call your mobile.
+- **Place a test call in.** From your mobile, call your main number.
+
+If either fails, see [Troubleshooting](troubleshooting.md).
+
+## Phones
+
+- **Desk phones (Yealink, Grandstream, Polycom/Poly, Snom, Fanvil):** add them on **Phones** with
+  their MAC address. The page shows the setup URL and password to enter on the phone.
+- **Any other SIP phone:** use the details on the user's **Credentials** tab.
+- **Browser phone:** every user with an extension gets one on **My phone** after signing in. There
+  is nothing to set up.
+
+## Turning on two-step sign-in
+
+Admins can (and should) turn on two-step sign-in: header → **Account** → **Turn on two-step sign-in**. Keep
+the recovery codes somewhere safe.