Migrating to v1.0.0

This guide covers the breaking changes and required steps when upgrading from any v0.10.x release to v1.0.0.

Back Up First

Always create a backup before a major version upgrade. Use System > Backup in the web interface or see Backing Up Docker Volumes.

Breaking Changes

New `koios_secrets` Volume

Koios v1.0.0 moves runtime credentials out of the Docker image and onto a dedicated volume. This affects how the container is started.

Change	Details
New volume	`koios_secrets` stores database passwords, the application secret key, and the time-series database token
Automatic migration	On first boot with an existing database, Koios writes the legacy credential values to the new volume automatically — no manual credential changes needed
Service file update required	Your systemd service file or `docker run` command must include the new volume mount

Update the Service File

Open your service file:

sudo nano /etc/systemd/system/docker.koios.service

Add the koios_secrets volume mount to the ExecStart line, after the koios_license mount:

--mount source=koios_secrets,target=/var/www/koios/secrets \

Your ExecStart should now include seven --mount lines. See Running Koios as a Service for the complete service file.

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart docker.koios.service

Update a Manual Docker Run Command

If you use docker run directly, add the same mount flag. See Manually Starting Koios for the complete command.

What happens without the volume?

Koios will still start without the secrets volume — it generates new credentials on each boot. However, credentials won't persist across container restarts, which means services may fail to authenticate after a restart. Always include the secrets volume.

Database Migrations

v1.0.0 includes database migrations that run automatically on first startup. These migrations:

Add tables for components, scan groups, expression tags, dashboards, roles, and API clients
Add new fields to existing device, tag, and model tables
Create the koios_schema_meta table for version compatibility tracking

All migrations are forward-compatible — your existing devices, tags, models, and configuration are preserved without modification.

Pre-Migration Backup

The v1.0.0 entrypoint automatically takes a database backup before running migrations, saved to the media volume at /var/www/koios/media/backups/pre-migrate-backup.sql. This is a safety net — you should still create your own backup before upgrading.

New Features

For a complete list of what's new in v1.0.0, see the v1.0.0 Release Notes.

Verification

After upgrading, confirm the new version is running:

Open the Koios web interface
Navigate to System > Overview
Verify the version shows 1.0.0

If the container fails to start, check the logs:

# Systemd service
journalctl -u docker.koios.service -f

# Manual run
docker logs koios

Common issues:

"Schema version incompatible" — you're running a version older than what the database expects. Restore from backup and try again with the correct image.
Services failing to authenticate — the koios_secrets volume mount is missing. Add it and restart.

Updating Koios Dashboard