ModelForge-Public/docs/operations/SCHEDULED_BACKUPS.md

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.

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:

MODELFORGE_BACKUP_ADMIN_API_KEY=<existing named administrator key>

Then start or recreate the scheduler with the usual stack files:

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.