Backing Up Docker Volumes

Use the In-App Backup First

For nearly all cases, use the in-app backup at System > Backup & Restore. 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, the application secret key, time-series database token)	Critical
`koios_media`	Uploaded files (ML models, component packages, stack wheels) and the built stacks	Critical
`koios_license`	License activation file	High
`koios_certs`	Certificates, including any web-interface certificate you installed and its private key	Medium
`koios_logs`	Application log files	Low

The four Critical volumes are enough to rebuild a working install. The other three carry uploads and configuration that are convenient to keep but recoverable from elsewhere — though losing koios_certs drops the web interface back to its built-in self-signed certificate, so you would need to install your certificate again.

Stacks live on koios_media

The wheels uploaded into a stack are stored only on koios_media, and they are the only source a stack can be rebuilt from. Restore without it and every component environment attached to a stack is left with nothing to run.

That volume also holds the built stacks, which the in-app backup deliberately leaves out — they are large and specific to the machine and CPU architecture that built them, and the in-app restore rebuilds them from the archived wheels. A raw archive of the volume captures them, so expect a much bigger archive, and expect to rebuild the stacks by hand if you restore onto a different machine. Exclude the stacks/ directory when archiving this volume by hand, or use the in-app backup instead.

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 four Critical volumes (koios_data_postgres, koios_data_influxdb, koios_secrets, koios_media). Add koios_license to keep an activated license, and koios_certs to keep an installed web-interface certificate.

To leave the built stacks out of the koios_media archive, exclude the stacks/ directory:

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

The uploaded wheels are still archived, so you can rebuild each stack from Components > Stacks after restoring.

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.

What's Next

Backup & Restore: the in-app backup that runs without stopping Koios and supports scheduled retention.

Running Multiple Instances Protocols