Backup & restore

Understand the scope

Consistent physical backup supports bundled MySQL and MinIO. It includes private configuration, databases, object storage, workspace source, local data and TLS files. External databases or object storage need provider-managed consistency and recovery procedures.

Backup briefly stops production services and restarts them after archive verification. Schedule a quiet period and keep an independent off-host copy.

Configure S3-compatible storage

As system, open System settings → Data backup and add or edit a configuration.

Field	Value
Bucket	Backup bucket; Qiniu users supply the S3 space name
Region	Provider’s S3 region code
Endpoint	S3 API URL without a bucket or path; optional for AWS S3
Prefix	A dedicated directory such as kageos-backups
Credentials	Dedicated access to upload, read, list and delete backup objects

“Test connection” uploads, reads and deletes a small object; it does not save the configuration. Save after testing, choose the daily time and retention period, then enable the schedule as needed.

Verify completion

A host-side executor performs backups. The production timer checks schedules every five minutes; automatic backup is disabled by default.

“Back up now” uses saved settings and requires an enabled plan and a ready executor. Inspect the result for archive verification, service restart and upload completion. A connection test alone does not prove a full backup works.

Manual backup and verification

For source deployments, run as the deployment owner from the repository root:

go run ./cmd/kagectl backup --output /mnt/kageos-backups
go run ./cmd/kagectl backup list
go run ./cmd/kagectl backup verify /mnt/kageos-backups/kageos-backup-20260923T020000Z.tar.gz

Store archives outside the data root and restrict access: they contain recovery secrets and business data. backup list uses the default backup directory; verify custom-location archives by full path.

Preflight a restore

go run ./cmd/kagectl restore /mnt/kageos-backups/kageos-backup-20260923T020000Z.tar.gz --dry-run

Preflight checks the archive and image versions without stopping services or writing data. Match platform, user-app base, MySQL and MinIO images to the archive. Reserve space for both old and restored data.

Actual restoration requires --force and replaces current instance data. Keep a current backup and have the responsible administrator review the target and preflight results before proceeding. See the source recovery guide.