Publish curated ITWorx-ModelForge source from 990401737f96c8d46a9f7b0d84994516cadcb6a0

docs/operations/SCHEDULED_BACKUPS.md

@@ -0,0 +1,45 @@
+# Scheduled backups
+
+The scheduled backup helper creates a recovery backup, verifies it, then applies retention. The
+recovery endpoints require the administrator role. Supply a key for an existing named administrator
+when the deployment no longer uses the legacy global operator key. Named deployment credentials and
+their lifecycle are described in [Operator access](OPERATOR_ACCESS.md).
+
+## Authentication settings
+
+Set `MODELFORGE_BACKUP_ADMIN_API_KEY` to a named administrator key for the scheduler. The key is
+sent only to the ModelForge API in the existing `X-ModelForge-Admin-Token` header. The helper does
+not print it. Keep the value in the deployment's protected environment or `.env` file; do not commit
+it. The API must already recognize the credential as an administrator.
+
+`MODELFORGE_OPERATOR_API_KEY` remains a backward-compatible fallback for existing deployments. If
+both settings are present, `MODELFORGE_BACKUP_ADMIN_API_KEY` takes precedence. If neither has a
+non-empty value, the helper exits before making an API request, so no backup or retention operation
+can be authorized.
+
+For a Compose deployment, add the dedicated key to the protected `.env` file used by Compose:
+
+```dotenv
+MODELFORGE_BACKUP_ADMIN_API_KEY=<existing named administrator key>
+```
+
+Then start or recreate the scheduler with the usual stack files:
+
+```sh
+docker compose -p modelforge --env-file .env \
+  -f docker-compose.yml -f docker-compose.backup.yml \
+  up -d --force-recreate backup-scheduler
+```
+
+For a host timer or Unraid User Script, export `MODELFORGE_BACKUP_ADMIN_API_KEY` in the protected
+job environment before invoking `scripts/modelforge_scheduled_backup.sh`. The legacy variable can
+continue to be used for direct invocations as well.
+
+## Credential lifecycle
+
+Use an administrator identity dedicated to scheduled recovery work. Backup and recovery endpoints
+currently require the administrator role; there is no narrower backup-only role. Keep the credential
+valid and unexpired, and rotate or revoke it through the named identity's supported lifecycle. After
+changing the scheduler's environment, recreate `backup-scheduler`. For deployment-owned named keys,
+apply the API's identity registry change and recreate the API as described in the operator access
+runbook.