Docs: public README, setup guide and architecture, generic deploy files, and the T3 Code notice

docs/setup.md

@@ -0,0 +1,111 @@
+# Setting up WristCode
+
+This guide runs the gateway, connects your T3 Code machines to it, builds the watch app, and pairs
+your watch. It takes about an hour, most of it in Apple's developer portal.
+
+## 1. Run the gateway
+
+The gateway is one container with one SQLite file in `/data`. Run it on a machine that is always
+on and can reach every T3 Code server.
+
+```sh
+cd deploy
+cp .env.example .env      # fill in after step 2, or leave the APNS_ lines empty for now
+mkdir data
+docker compose up -d --build
+```
+
+`compose.yml` builds the image from `gateway/` and listens on `127.0.0.1:8080`. Podman works the
+same with `podman compose`. The image runs as uid 1000, which needs to be able to write `data/`.
+
+The watch needs to reach the gateway over cellular, so put it behind a reverse proxy that serves
+HTTPS on a public name, such as `wristcode.example.com`, and forwards to port 8080. Check it with:
+
+```sh
+curl https://wristcode.example.com/v1/health
+```
+
+Every route except health and pairing needs a device token, which only pairing hands out.
+
+## 2. Set up notifications
+
+The gateway sends notifications through Apple's push service (APNs) with a key from your developer
+account.
+
+1. In [Certificates, IDs & Profiles](https://developer.apple.com/account/resources/authkeys/list),
+   make a key with Apple Push Notifications service enabled, and download its `.p8` file.
+2. Put the file in `deploy/data/apns.p8`.
+3. Fill in `deploy/.env`: the key's ID, your team ID, and `APNS_TOPIC`, which is the watch app's
+   bundle ID from step 4.
+4. Restart the gateway with `docker compose up -d`.
+
+Without these settings the gateway still works. It logs each notification instead of sending it.
+
+## 3. Connect your T3 Code machines
+
+The gateway logs in to each T3 Code server with a one-time pairing credential. On the T3 Code
+machine:
+
+```sh
+t3 auth pairing create --scope orchestration:read --scope orchestration:operate --label "WristCode gateway"
+```
+
+Then, within a few minutes, on the gateway machine:
+
+```sh
+docker compose exec gateway wristcode host add https://t3-desktop.example.com <credential> --label "Desktop"
+```
+
+The gateway trades the credential for a 30 day session that can read and drive threads, and the
+credential stops working. The label is what the watch shows.
+
+A machine you can reach several ways can list fallbacks with `--alt-url`, preferred first. The
+gateway uses the first route that answers, so put a LAN or VPN address first and a public URL
+last:
+
+```sh
+docker compose exec gateway wristcode host add http://desktop.lan:3773 <credential> \
+  --label "Desktop" --alt-url https://t3-desktop.example.com
+```
+
+`wristcode host list` shows each host and when its session expires. T3 sessions cannot be renewed,
+so a week before one expires the watch gets a notification. To renew, run `host add` again with a
+fresh credential, or let `scripts/renew-hosts.sh` do every host over SSH. Copy
+`scripts/hosts.conf.example` to `scripts/hosts.conf` and list your machines in it first.
+
+## 4. Build the watch app
+
+You need a Mac with Xcode and [XcodeGen](https://github.com/yonaskolb/XcodeGen).
+
+1. Copy `watch/Local.xcconfig.example` to `watch/Local.xcconfig`, which git ignores, and set your
+   team ID and a bundle ID prefix you own, such as `com.example`. The watch app's bundle ID is
+   `<prefix>.wristcode.watchkitapp`, which is the `APNS_TOPIC` from step 2.
+2. Generate the project and open it:
+
+   ```sh
+   cd watch
+   xcodegen generate
+   open WristCode.xcodeproj
+   ```
+
+3. Run the `WristCode` scheme on your watch. Xcode registers the bundle IDs and the push
+   capability for you with automatic signing.
+
+To install it without Xcode attached, upload a build to TestFlight with
+`watch/scripts/testflight.sh`. It needs an App Store Connect API key and an app record for
+`<prefix>.wristcode`. [watch/README.md](../watch/README.md) has the details, plus a demo mode
+that runs without a gateway.
+
+## 5. Pair your watch
+
+On the gateway machine:
+
+```sh
+docker compose exec gateway wristcode pair
+```
+
+It prints a 6 digit code that works once, for 5 minutes. On the watch, enter your gateway's URL
+and the code. The watch then asks to send notifications. Allow it, and send a test notification
+from the gear button, then Notifications, to check the whole chain.
+
+`wristcode device list` shows paired watches, and `wristcode device revoke <name>` unpairs one.