# 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.