feat: complete platform operations roadmap

PORTAINER.md

@@ -10,6 +10,8 @@ To let instructors upload protected course videos, configure these API environme
 BUNNY_STREAM_LIBRARY_ID=123456
 BUNNY_STREAM_API_KEY=your-bunny-library-api-key
 BUNNY_EMBED_TOKEN_KEY=your-bunny-embed-view-token-key
+BUNNY_WEBHOOK_SECRET=your-bunny-read-only-api-key
+BUNNY_EMBED_TOKEN_TTL_SECONDS=600
 BUNNY_MAX_UPLOAD_MB=5120
 ```
 
@@ -26,6 +28,16 @@ After deploying the new images:
 
 The API key and embed-token key never reach the browser. The instructor browser uploads to the authenticated Academy API, which sends the file to Bunny; learners receive only a signed iframe URL.
 
+### Bunny processing webhooks
+
+The editor can poll Bunny while a video encodes, but production should also configure Bunny's webhook so the Academy records the result even when no instructor page is open. In the library webhook settings, use:
+
+```text
+https://YOUR-DOMAIN/api/v1/webhooks/bunny
+```
+
+Set `BUNNY_WEBHOOK_SECRET` to Bunny's **Read-Only API key**. The Academy checks Bunny's HMAC signature against the unmodified request body and rejects unsigned requests. Do not use the normal library API key for this setting.
+
 This is a Docker Swarm stack: Portainer pulls prebuilt API and web images from the Gitea Container Registry. It never builds Dockerfiles itself.
 
 ## Gitea Actions registry secrets
@@ -45,6 +57,7 @@ The built-in Actions job token can be disabled or lack registry scope on self-ho
 - `SUPERADMIN_EMAIL`: email address for the initial platform administrator.
 - `SUPERADMIN_PASSWORD`: password for that administrator (at least 12 characters).
 - `AUTH_RATE_LIMIT_MAX` and `AUTH_RATE_LIMIT_WINDOW_SECONDS` are optional login and public-auth throttling controls (defaults: 10 attempts per 900 seconds per source IP).
+- `JWT_SESSION_TTL`, `INVITATION_TTL_HOURS`, `PASSWORD_RESET_TTL_HOURS`, `BUNNY_EMBED_TOKEN_TTL_SECONDS`, and `AUDIT_LOG_PAGE_SIZE` tune operating policy without changing code.
 
 Optional variables:
 
@@ -63,4 +76,11 @@ Optional variables:
 5. Place the web service behind HTTPS, normally through your existing reverse proxy (Traefik, Nginx Proxy Manager, or Cloudflare Tunnel), and set `FRONTEND_ORIGIN` to that HTTPS address.
 6. Back up the `compor_postgres_data` volume before updates.
 
+## Reliability checklist
+
+- Keep the API at one replica until PostgreSQL capacity and upload traffic justify scaling. Auth throttling is database-backed, so it will remain consistent if you later add replicas.
+- Point an external monitor at `https://YOUR-DOMAIN/api/v1/ready`; alert when it returns anything other than HTTP 200.
+- Test a PostgreSQL backup restoration into a separate temporary database at least once per quarter. A backup is only proven when it restores.
+- Create a separate Portainer stack and database for staging. Use a different `FRONTEND_ORIGIN`, `JWT_SECRET`, Bunny library, and `WEB_PORT`; never point staging at production PostgreSQL or video credentials.
+
 Do not expose port 5432 or port 3001 publicly.