---
title: "Migrating to v1.0.0"
description: "Breaking changes and migration steps for upgrading from v0.10.x to v1.0.0"
source_url: https://ai-ops.com/docs/updates/v1-0-0
---

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

> [!TIP] 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](https://ai-ops.com/docs/installation/backup-restore.md).

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

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

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

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

Your `ExecStart` should now include **seven** `--mount` lines. See [Running Koios as a Service](https://ai-ops.com/docs/installation/running-as-a-service.md) for the complete service file.

Then reload and restart:

```bash
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](https://ai-ops.com/docs/installation/manually-starting-koios.md) for the complete command.

> [!NOTE] 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.

> [!WARNING] 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](https://ai-ops.com/docs/release-notes/v1-0-0.md).

## Verification

After upgrading, confirm the new version is running:

1. Open the Koios web interface
2. Navigate to **System > Overview**
3. Verify the version shows **1.0.0**

If the container fails to start, check the logs:

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