Skip to main content

Legacy Migration

When is this needed?

Only for a deployment whose directory has .env and .secrets/ at its top level and no .deployment_states/: one set up by hand, or by a deploy tool older than 2.7.0. Such deployments also predate Authentik and keep their users in the Avatar database.

Every other deployment follows Upgrade & Rollback.

The migration runs once. It moves the configuration into the layout managed by octopize-deploy-tool, then imports the existing users, organizations and licenses into Authentik. Afterwards, the deployment upgrades like any other.

1. Back up the legacy deployment​

Back up the database and copy the whole legacy directory. The backup commands apply, with the paths of the legacy directory.

2. Migrate the configuration​

Install the latest deploy tool, then point it at the legacy directory and at a new, empty deployment directory:

octopize-deploy-tool migrate \
  --app-root ./app/avatar-new \
  --from-legacy ./app/avatar-old

migrate reads the values from the legacy .env and .secrets/ and asks for the missing ones. It then shows the diff, starting with the service versions that change. Expect a large diff: the layout changes and every service jumps to the current release.

Non-interactive runs

Before running with --non-interactive, check that the legacy .env sets NGINX_SSL_CERTIFICATE_PATH and NGINX_SSL_CERTIFICATE_KEY_PATH to paths that exist.

3. Start and import the users​

octopize-deploy-tool start --app-root ./app/avatar-new

The first start after a migrate offers to import the users into Authentik. It previews every operation and asks for confirmation. Accept it.

If you declined, or the import failed partway, run it later. It is safe to re-run, since users already imported are skipped:

# Preview without changing anything
octopize-deploy-tool tasks authentik-migrate --from-docker --app-root ./app/avatar-new --dry-run

# Import
octopize-deploy-tool tasks authentik-migrate --from-docker --app-root ./app/avatar-new

# Retry only the operations that failed
octopize-deploy-tool tasks authentik-migrate --from-docker --app-root ./app/avatar-new \
  --from-log migration_log.jsonl --failed-only

4. Verify​

Follow Verification & Troubleshooting. Existing users log in through Authentik from now on. To add new ones, see User management.

If the migration fails, stop the new deployment, restore the database backup, and bring the legacy deployment back up from its directory.