Deploy Stride with encrypted manual and scheduled Garmin sync

docs/DEPLOYMENT.md

@@ -0,0 +1,45 @@
+# Dokku deployment
+
+App: `stride`; database: `stride-db`; domain: `stride.peterstockings.com`.
+The Dockerfile installs locked dependencies on Python 3.12. Dokku runs database
+migrations in the predeploy step, then one web container and one sync worker.
+
+Mount `/var/lib/dokku/data/storage/stride:/storage` with ownership 1000:1000 and
+mode 0700. Set APP_ENV=production, INSTANCE_PATH=/storage/instance,
+DATA_ROOT=/storage/data, SECRET_KEY (random secret), TOKEN_ENCRYPTION_KEY
+(Fernet key). Linking PostgreSQL supplies DATABASE_URL. Preserve the encryption
+key separately from database backups; losing it requires Garmin reconnection.
+
+Push to Gitea, then deploy with `dokku git:sync --build stride
+https://gitea.peterstockings.com/peterstockings/Stride.git main` on the server.
+Enable HTTPS using `dokku letsencrypt:enable stride`.
+
+## Sync
+
+Upload a garminconnect 0.3.17 session JSON in Settings & imports. Credentials are
+validated with Garmin, encrypted, and assigned to the authenticated owner.
+Manual sync queues durable work; the worker polls every 30 seconds. Automatic
+sync runs hourly and checks the latest 100 activities, reusing download manifests
+and unique activity source keys to avoid duplicates. Older activities can be
+imported with FIT uploads or the operator's local import command.
+
+Shared storage file locks prevent overlapping jobs and disconnect races. A crash
+releases the lock; due or pending work is retried after restart. Refresh tokens
+are persisted before downloading and after download failures. Transient failures
+back off up to six hours; rejected authentication pauses scheduling until the
+user reconnects and enables it again. Disconnect removes credentials and keeps
+previously imported activities. Only garmin.com is supported by the web connector.
+
+Inspect `dokku logs stride -p worker`, the status in Settings, and `/health`.
+Run `dokku run stride flask --app app sync-worker --once` for an operator check.
+Do not run the local sync simultaneously using a copy of the same Garmin session.
+
+Back up PostgreSQL, `/storage`, and configuration securely. Rate limiting still
+uses per-process memory; email verification and password recovery are not yet
+implemented. For a larger public deployment configure shared rate-limit storage.
+
+## Validation
+
+Local automated suite: 39 passing tests, including manual/scheduled jobs,
+encryption, retry/authentication failure, locking, CSRF, and access control.
+Live deployment and Garmin results will be recorded after verification.