Backing Up Docker Volumes

Use the In-App Backup First

For nearly all cases, use the in-app backup at System > Backup — see Backup & Restore. It runs without stopping Koios, supports scheduled retention, and produces a single archive you can download.

This page exists for the cases where the in-app backup isn't an option.

When You'd Use This

Scenario	Why direct volume access
Koios won't start or is otherwise unreachable	The in-app UI is unavailable, so the only way to capture state is directly from the volumes
Migrating to a new host	Lets you move the raw volumes between machines without going through the app
Host-level disaster-recovery scripts	Volumes can be snapshotted from the host on the same schedule as the rest of your infrastructure

If none of these apply, stop here and use the in-app backup instead.

Docker Volumes

All Koios data lives in seven Docker volumes:

Volume	Contents	Priority
`koios_data_postgres`	Configuration database (devices, tags, users, models)	Critical
`koios_data_influxdb`	Time-series database (historical tag values)	Critical
`koios_secrets`	Auto-generated credentials (database passwords, Django secret key, time-series database token)	Critical
`koios_media`	Uploaded files (ML models, component packages)	High
`koios_license`	License activation file	High
`koios_certs`	SSL certificates	Medium
`koios_logs`	Application log files	Low

The three Critical volumes are enough to rebuild a working install. The others carry uploads and configuration that are convenient to keep but recoverable from elsewhere.

Backup

Stop Koios First

Stop the container before backing up the database volumes. Backing up a live database can produce a corrupt archive.

sudo systemctl stop docker.koios.service   # if running as a service
docker stop koios                           # if running manually

Linux / macOS

Windows

Back up a volume by running a temporary Alpine container that mounts the volume and creates a tar archive in the current directory:

docker run --rm \
  -v koios_data_postgres:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/koios_data_postgres.tar.gz -C /data .

Run the same command for each volume you want to back up, swapping the volume name and archive filename. At minimum, back up the three Critical volumes (koios_data_postgres, koios_data_influxdb, koios_secrets). Add koios_media and koios_license if you have uploaded models or an activated license.

Restore

Stop Koios Before Restoring

Restoring into a running container will corrupt the databases.

Stop Koios, then restore each archive back into its volume. This command deletes the volume's contents before extracting, so the restore is a clean replacement:

docker run --rm \
  -v koios_data_postgres:/data \
  -v $(pwd):/backup \
  alpine sh -c "rm -rf /data/* && tar xzf /backup/koios_data_postgres.tar.gz -C /data"

Repeat for every volume you need to restore, then start Koios again.

Licensing Koios Updating Koios