Prepare QSfera production release

Server/docs/raspberry-pi-5-docker.md

@@ -0,0 +1,107 @@
+# Raspberry Pi 5 Docker Run
+
+This server repository contains a Dockerized QSfera path for Raspberry Pi 5 and other
+64-bit ARM Linux hosts.
+
+Files used for this deployment:
+
+- `Dockerfile`
+- `docker-compose.rpi5.yml`
+- `.env.example`
+
+## What This Runs
+
+- QSfera server from this `Server` source tree.
+- QSfera config persisted under `/etc/qsfera` inside the container.
+- QSfera data persisted under `/var/lib/qsfera` inside the container.
+- Host-side config and data paths controlled by `QSFERA_RPI_CONFIG_PATH` and
+  `QSFERA_RPI_DATA_PATH`.
+- Host-side backend port bound only to `127.0.0.1:9200`; external access should go
+  through the reverse proxy and HTTPS domain.
+
+## Prerequisites On Raspberry Pi 5
+
+1. Install Docker Engine using the official Docker docs: `https://docs.docker.com/engine/install/debian/`.
+2. Install the Docker Compose plugin using the official Docker docs: `https://docs.docker.com/compose/install/`.
+3. Use a 64-bit OS. The compose file sets `platform: linux/arm64`, and the Dockerfile builds with `TARGETARCH=arm64`.
+4. Put `QSFERA_RPI_CONFIG_PATH` and `QSFERA_RPI_DATA_PATH` on durable storage, not on a nearly full SD-card root filesystem.
+5. Set `OC_URL` to the public HTTPS URL used by clients and the reverse proxy.
+
+## Start
+
+Run from the `Server` directory:
+
+```bash
+cp .env.example .env
+docker compose -f docker-compose.rpi5.yml up -d --build
+```
+
+## Stop
+
+```bash
+docker compose -f docker-compose.rpi5.yml down
+```
+
+## Logs
+
+```bash
+docker compose -f docker-compose.rpi5.yml logs -f qsfera-cloud-server
+```
+
+## Update After Pulling New Code
+
+```bash
+docker compose -f docker-compose.rpi5.yml up -d --build
+```
+
+## Verify
+
+Local backend status endpoint:
+
+```bash
+curl -k https://127.0.0.1:9200/status.php
+```
+
+External reverse-proxied status endpoint:
+
+```bash
+curl https://qsfera.example.com/status.php
+```
+
+## Data Location
+
+Docker bind mounts:
+
+- host config: `${QSFERA_RPI_CONFIG_PATH}`
+- container config: `/etc/qsfera`
+- host data: `${QSFERA_RPI_DATA_PATH}`
+- container data: `/var/lib/qsfera`
+
+For the current Raspberry Pi deployment inspected on 2026-06-08, the existing
+container uses:
+
+- host config: `/mnt/data/qsfera/cloud-server/config`
+- host data: `/mnt/data/qsfera/cloud-server/data`
+- public URL: `https://qsfera.kusoft.xyz`
+- loopback port: `127.0.0.1:9200`
+
+## Reverse Proxy
+
+The server is intentionally bound to loopback. Put Caddy, Nginx, Traefik, or another
+reverse proxy in front of it for external HTTPS access.
+
+The inspected Raspberry Pi uses Caddy with this QSfera route:
+
+```caddyfile
+qsfera.kusoft.xyz {
+    encode zstd gzip
+    handle {
+        reverse_proxy https://127.0.0.1:9200 {
+            transport http {
+                tls_insecure_skip_verify
+                versions 1.1
+            }
+        }
+    }
+}
+```