Updating Open Source setup docs

docs/self-hosted/apps.md

@@ -0,0 +1,67 @@
+---
+sidebar_position: 7
+title: Connecting the mobile apps
+---
+
+# Connecting the mobile apps to your server
+
+The Resgrid **Responder** and **Unit** apps from the App Store and Google Play work with self-hosted servers; you don't need special builds. Each user points the app at your server's API hostname once.
+
+## Before you start
+
+- The server's **API** and **events** hostnames must resolve on the phone's network (public DNS, or records on the WiFi router for LAN/offline installs) and present a certificate the phone trusts ([Certificates](./certificates)).
+- On **Android**, the apps only trust publicly issued certificates. Use Let's Encrypt or your own public certificate if Android phones must use the apps; the local CA works for Android browsers and for iPhones.
+- Create the users in the web app first (**Personnel > Add Person**, or invitations if the server sends email).
+- For offline deployments, install the apps while the phones still have internet.
+
+## Set the server URL
+
+### Resgrid Responder
+
+1. Open the app. On the login screen tap **Change Server URL**.
+2. In **Server**, choose **Custom**.
+3. In **Server URL** enter `https://<your API hostname>`, for example `https://dispatchapi.example.com`. Only the base URL: no `/api/v4`, no trailing slash. If the server serves HTTPS on a port other than 443 (`RESGRID_HTTPS_PORT` in `.env`, set when 443 was already taken), add the port: `https://dispatchapi.example.com:8443`.
+
+   A private name such as `https://rgapi.rick.internal` works for iPhones, which trust the local CA. It cannot work for the Android apps: `.internal` is reserved for private networks and no public CA will issue a certificate for it, so Android needs a hostname under a domain you own ([RICK: publicly trusted certificate](./rick#publicly-trusted-certificate-android-apps)).
+4. Save, then log in with your Resgrid user name and password.
+
+### Resgrid Unit
+
+1. On the login screen tap **Server URL**.
+2. Choose **Custom** and enter `https://<your API hostname>`, with the port if `RESGRID_HTTPS_PORT` is not 443 (`https://dispatchapi.example.com:8443`). The Unit app only accepts `https://` addresses.
+3. Save and log in with the unit's or user's credentials.
+
+You can change it later under **Settings > Server**; changing it signs you out. When the phone has no internet, the server sheet first tries to reach resgrid.com and can take up to 30 seconds before it lets you choose **Custom**.
+
+The app reads everything else from your server: the events hub address comes from `RESGRID__SystemBehaviorConfig__ResgridEventingBaseUrl`, so that hostname must be reachable from phones too.
+
+## On a WiFi network without internet
+
+When the phone joins a network without internet (a [RICK](./rick) kit, a field LAN):
+
+- **Android** shows *No internet access*: choose **Stay connected** / **Keep WiFi connection**, and turn off mobile data so Android doesn't route the apps over cellular. Turn off **Private DNS** if it is set to a provider.
+- **iPhone** asks to allow access to devices on your **Local Network** the first time: allow it (later: **Settings > Privacy & Security > Local Network**). Turn off iCloud Private Relay or VPNs for that WiFi.
+
+## What to expect
+
+| Feature | Online self-hosted server | Offline (laptop, RICK) |
+|---|---|---|
+| Log in, calls, dispatches, statuses, staffing, personnel and unit lists | Yes | Yes |
+| Real-time updates while the app is open (events hub) | Yes | Yes |
+| Location sharing to the server | Yes | Yes |
+| Messages and chat | Yes (chat needs the Chat feature enabled for the department) | Yes, while the app is open |
+| Push notifications when the app is closed | Only with a configured Novu instance and the apps' Firebase/APNs credentials (`RESGRID__ChatConfig__Novu*`); not configured by default | No (needs Google/Apple services) |
+| Maps in the apps | Mapbox; set `RESGRID__MappingConfig__ResponderAppMapboxKey` / `UnitAppMapBoxKey` | Only areas already cached on the phone |
+| Address search | Needs internet geocoding | No |
+
+Because push notifications aren't available on a typical self-hosted server, ask responders to keep the app open (and the screen on, with **Keep Alive** in the app settings) during an incident so they receive new dispatches immediately.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| "Network error" at login on Android | The certificate isn't publicly trusted. Use Let's Encrypt or your own public certificate. |
+| Login fails on iPhone | Install and enable the CA profile ([Certificates](./certificates#iphone-and-ipad)), check the Local Network permission. |
+| Logs in but nothing updates | The events hostname doesn't resolve or isn't trusted from the phone. |
+| "Invalid URL" in the Unit app | Use `https://`; the Unit app rejects `http://` servers. |
+| Can't resolve the server name | The phone uses another DNS (Private DNS, VPN, cellular). Fix the router records and the phone's DNS settings. |

docs/self-hosted/certificates.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 6
+title: Certificates and hostnames
+---
+
+# Certificates and hostnames
+
+Resgrid always runs over HTTPS on **three hostnames**: the web app, the API and the events hub (for example `dispatch.example.com`, `dispatchapi.example.com`, `dispatchevents.example.com`). Browsers and the mobile apps connect to all three, so on every device each hostname must:
+
+1. resolve to your server (DNS or a hosts-file entry), and
+2. present a certificate the device trusts.
+
+If either fails for the API or events hostname, the web app loads but logging in, chat, maps or live updates fail.
+
+## Choosing a certificate mode
+
+| Mode (`RESGRID_TLS` in `.env`) | When | What devices need |
+|---|---|---|
+| An email address → **Let's Encrypt** | Server reachable from the internet on ports 80 and 443, public DNS records | Nothing |
+| **Your own certificate** (`/certs/site/fullchain.pem /certs/site/privkey.pem`) | You have a certificate from your organization's CA, a wildcard, or one obtained with a DNS challenge | Whatever already trusts that certificate. Public certificates need nothing. |
+| `internal` → **Resgrid local CA** | LAN-only and offline installs (laptop, RICK) | Install the local CA certificate once |
+
+The installers set this up for you. For your own certificate, copy the full chain and key to `certs/site/fullchain.pem` and `certs/site/privkey.pem` (or pass `RESGRID_TLS_CERT_FILE` / `RESGRID_TLS_KEY_FILE` to `setup.sh`). The certificate must cover all three hostnames.
+
+If that certificate comes from your organization's own CA rather than a public one, trusting it on client devices is not enough: the containers call the public hostnames themselves (the web app's server-side calls to the API), so they must trust the CA too, or those calls fail. Mount the CA certificate into the containers and add its directory to `SSL_CERT_DIR` — [Trusting a private certificate authority](../reference/docker#trusting-a-private-certificate-authority). Do not turn certificate checks off instead: `RESGRID__ApiConfig__BypassSslChecks=true` makes the web, API and events containers refuse to start in Production.
+
+:::info Android apps need a public certificate
+The Resgrid **Responder** and **Unit** apps on Android only trust certificates from public certificate authorities; they ignore CAs installed by the user. If Android phones must use the apps, use Let's Encrypt or a publicly trusted certificate. Browsers on Android, and iPhones, can use the local CA. The [RICK guide](./rick#publicly-trusted-certificate-android-apps) shows how to get a public certificate for a kit that is never online.
+:::
+
+## The Resgrid local CA
+
+With `internal`, setup creates a small certificate authority:
+
+| File | Purpose |
+|---|---|
+| `certs/ca/resgrid-root-ca.crt` | The CA certificate. Install it on clients. It is public. |
+| `certs/private/resgrid-root-ca.key` | The CA private key. Never share it; anyone with it can create certificates your devices trust. |
+
+Caddy issues and renews the site certificates for the three hostnames from this CA by itself. The Resgrid containers trust the CA too (`SSL_CERT_DIR` in `.env`), so the web app's server-side calls to the API work without turning certificate checks off. The CA certificate is valid for 10 years.
+
+## Installing the CA certificate
+
+Copy `resgrid-root-ca.crt` to the device (USB stick, email, file share, `scp`), then:
+
+### Windows
+
+1. Double-click `resgrid-root-ca.crt` and choose **Install Certificate**.
+2. Choose **Local Machine** (or **Current User** if you are not an administrator) and **Next**.
+3. Choose **Place all certificates in the following store**, **Browse**, **Trusted Root Certification Authorities**, **OK**, **Next**, **Finish**.
+4. Restart the browser. Chrome and Edge use the Windows store. In Firefox open `about:config` and set `security.enterprise_roots.enabled` to `true`.
+
+The [laptop installer](./laptop) does this for your account automatically.
+
+### macOS
+
+1. Double-click `resgrid-root-ca.crt`; Keychain Access opens and adds it to the **login** keychain.
+2. Double-click **Resgrid Local CA** in the list, expand **Trust**, and set **When using this certificate** to **Always Trust**. Close the window and enter your password.
+
+### iPhone and iPad
+
+1. AirDrop or email the file to the device and open it; iOS says **Profile Downloaded**.
+2. **Settings > General > VPN & Device Management**, select the **Resgrid Local CA** profile, **Install**.
+3. **Settings > General > About > Certificate Trust Settings**, turn on **Resgrid Local CA**.
+
+### Android
+
+**Settings > Security > More security settings > Encryption & credentials > Install a certificate > CA certificate**, then pick the file (menu names vary by manufacturer). This makes Chrome trust the server; the Resgrid apps still need a public certificate (see above).
+
+### Linux
+
+```bash
+sudo cp resgrid-root-ca.crt /usr/local/share/ca-certificates/
+sudo update-ca-certificates
+```
+
+Firefox and Chrome on Linux keep their own store: import the file under **Settings > Privacy & Security > Certificates > View Certificates > Authorities > Import** (Firefox) or **Settings > Privacy and security > Security > Manage certificates** (Chrome).
+
+## Hostnames without DNS
+
+Without DNS records, add one line per device to its hosts file: `C:\Windows\System32\drivers\etc\hosts` on Windows (edit Notepad as Administrator), `/etc/hosts` on macOS and Linux.
+
+```text
+192.168.1.50  rg.mylocal rgapi.mylocal rgevents.mylocal
+```
+
+Phones can't edit a hosts file; create the records on your router or DNS server instead. Most routers call this *DNS rewrites*, *custom hosts* or *static DNS*.
+
+Hostname tips:
+
+- Names under `.localhost` (`rg.localhost`) always point at the computer itself in Chrome, Edge and Firefox; the [laptop install](./laptop) uses them so no hosts-file edit is needed.
+- Avoid `.local`: iPhones and Macs resolve it only with multicast DNS and ignore router records for it. `.internal` is reserved for private networks and works everywhere.
+- Every device's clock must be right: certificates are rejected when a clock is far off.