This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Migrate using Docker Compose

Migrate a v5.x Docker Compose deployment to v6.1 or later by standing up a new deployment from the v6.1 reference compose file and moving your data into it.

This runbook migrates a running Anchore Enterprise v5.x Docker Compose deployment to v6.1 or later. It assumes the commands are run on the host where the deployment lives. Before you begin, read the migration overview to understand what the migration does and what you need in place.

Rather than editing your existing v5.x docker-compose.yaml file in place, this guide has you start from a clean copy of the v6.1 reference compose file and move your data into it.

The migration has two parts: we safely migrate the underlying PostgreSQL database from PostgreSQL 13 to PostgreSQL 17, and we then move the actual Anchore Enterprise application images from v5.x to v6.1. Starting from the v6.1 template takes care of both at once — the template already runs PostgreSQL 17, and once your data is restored into it, Anchore Enterprise upgrades its own database schema automatically on first boot.

Something you may already noticed by taking a look at the new v6.1 docker-compose file, is that v6.x adds two new services (component-catalog and db-preflight) along with several new required settings.

Upgrades are only supported from v5.x to v6.1 or later. A v5.x deployment cannot upgrade directly to v6.0.

Migrating a host with no outbound internet access? See Air-Gapped Migration before you begin — you’ll need to mirror the v6.x compose file, database Dockerfile, and application images to the high side before Step 4 below.

Prerequisites

Before you begin, make sure you have:

Confirm the deployment is currently running a supported Anchore Enterprise v5.x release. Check the Recommended Component Versions table in the Release Notes for the version you’re moving from.
Docker and Docker Compose installed and up to date.
A valid license.yaml.
Ensure sufficient disk space exists for database backups, temporary migration files, and the additional PostgreSQL volume — a full second copy of your database’s data directory, plus the export file, at minimum.
A maintenance window — you will need to stop the deployment and writes to the database before the final export in Step 5 so no data is missed.

Test this procedure in a staging or QA environment before running it against production. The steps below include a downtime window while the database is exported and restored.

Migration Procedure

Step 1: Stop All Services

docker compose down --remove-orphans

This begins the downtime window.

Step 2: Back Up Your Existing Configuration

Before making any changes, back up the existing docker-compose.yaml and, optionally, the Docker volumes. Please file away the backup of the file somewhere safe so that you do not accidentally use/delete it.

cp docker-compose.yaml docker-compose-v5.yaml.bak

Step 3: Set Up a New Deployment Directory

Create a separate directory for the v6.1 deployment. Do not reuse your v5.x deployment directory. This method keeps the two deployments, and their compose projects, independent until you’re ready to retire v5.x.

mkdir anchore-enterprise-v6 && cd anchore-enterprise-v6

Step 4: Download the v6.x Deployment Files

Your new v6.x directory will need a new v6.1 formatted docker-compose.yaml file, your license file which we can copy from the old v5.x directory, and a Dockerfile that we also provide for download from our official documentation site for building the new Postgres 17 Database:

curl -sSfL https://docs.anchore.com/current/docs/deployment/docker_compose/docker-compose.yaml > docker-compose.yaml
curl -sSfL https://docs.anchore.com/current/docs/deployment/docker_compose/Dockerfile.anchore-db > Dockerfile.anchore-db
cp /path/to/your/v5-license.yaml ./license.yaml

The Dockerfile needs to be named ‘Dockerfile.anchore-db’ as it is targeted by name directly from the docker-compose file on build. If you name it something different then it will not get picked up by the build.

Step 5: Configure Secrets

Follow Step 4: Configure Secrets in the standard deployment guide to set POSTGRES_PASSWORD, ANCHORE_ADMIN_PASSWORD, ANCHORE_AUTH_SECRET, and ANCHORE_DB_PASSWORD. These are fresh secrets for the new deployment — they do not need to match the values your v5.x deployment used.

You do not need to reconcile the database password with your v5.x deployment after restoring your data. pg_dumpall carries PostgreSQL role passwords over in a format PostgreSQL 17 rejects, but the export/restore in this guide uses pg_dump against a single database (not roles), so the fresh POSTGRES_PASSWORD you set here is never touched by the restore.

At-rest encryption of sensitive database columns (ANCHORE_DB_ENCRYPTION_KEY_CURRENT) is optional and off by default — leave it commented out and the service starts normally, with those columns stored as plaintext exactly as in v5.x. See Encrypting Database Secrets at Rest if you want to enable it now or later.

Step 6: Start Only the New Database

docker compose up -d anchore-db

Wait for it to report healthy before continuing:

docker compose ps anchore-db

Step 7: Export the v5.x Database

From your v5.x deployment directory, stop writes and export the database - we are going to export it to our new v6 deployment directory and then from there you can decide where you want to move it to after the migration is complete:

docker compose exec -T anchore-db pg_dump -U postgres -Fc -d postgres -f /tmp/anchore-v5-export.dump
docker compose cp anchore-db:/tmp/anchore-v5-export.dump path/to/v6-deployment/anchore-v5-export.dump

You are going to need enough storage space for this process as mentioned in the Prerequisites earlier. You are probably going to need enough free disk space to store the file at least twice. Once you have completed this guide and the migration has been verified as successful, you can move the old dump file wherever you wish.

Step 8: Restore the Data into the New Database

From your new v6.x deployment directory run the below command to restore data from the export that you previously took from the old database into the new database:

docker compose exec -T anchore-db pg_restore -U postgres -d postgres --clean --if-exists --no-owner < ./anchore-v5-export.dump

–clean –if-exists lets you re-run this command safely if you need to redo the restore — it drops matching objects before recreating them instead of erroring on a non-empty database.

Step 9: Start the Full v6.x Deployment

Again, from inside the new v6.x deployment directory run the below to bring up the full v6 deployment:

docker compose up -d

Anchore Enterprise performs its own database schema migration in-process on first boot, upgrading your restored v5.x data to the v6.1 schema automatically — no separate migration command is needed.

Step 10: Validate the Upgrade

Check	Command
All services are healthy	`docker compose ps`
API reports the new version	`curl <api-url>/v2/status` — confirm `"version":"6.1.0"`
Users can log in	`anchorectl account list`
Historical data is present	`anchorectl image list`
Scans and policy evaluations still function	`anchorectl image vulnerabilities <existing-tag>` and `anchorectl image check <existing-tag>`

Retire the Old v5.x Deployment (Optional)

Once the upgrade is validated and you feel comfortable and confident you won’t need to roll back, you can take the real final (but completely optional!) step of removing the v5.x deployment’s volume backup. Our recommendation is to retain the database dump file, the original compose file, and the volume backup until the upgraded deployment has been fully validated in production.

docker volume rm <your-old-db-volume-name>

Please make sure you are using the correct volume name in the command - it is the old v5 volume name and NOT *the new v6 volume name. If you use the wrong name you may completely wipe all of your data.

Also do not remove the v5.x deployment’s volumes until you’ve confirmed that the migration succeeded and your existing data, images etc. because this and the original v5 docker-compose.yaml file are your only rollback path.

Downtime Expectations

This migration requires application downtime during the database export and restore.Downtime duration depends on database size, disk performance, and system resources.

1 - Migrate Air-Gapped using Docker Compose

If the deployment host has no outbound internet access, complete this guide before Step 4: Download the v6.x Deployment Files in the main migration runbook. It mirrors the low-side/high-side process in Air-Gapped Docker Compose deployment — the v6.x reference compose file, database Dockerfile, and application images all need to reach the high side before you can start the new deployment, in addition to the database dump you already have to move as part of the migration itself.

Throughout this guide, the low side is the internet-facing system and the high side is the air-gapped system.

Prepare the Files and Images (low side)

Download the v6.x compose file and database Dockerfile:

curl -sSfL https://docs.anchore.com/current/docs/deployment/docker_compose/docker-compose.yaml > docker-compose.yaml
curl -sSfL https://docs.anchore.com/current/docs/deployment/docker_compose/Dockerfile.anchore-db > Dockerfile.anchore-db

Pull the v6.x application images:

docker pull docker.io/anchore/enterprise:v6.1.0
docker pull docker.io/anchore/enterprise-ui:v6.1.0
docker pull docker.io/redis:7.4.6

Build the database image from Dockerfile.anchore-db:

docker build -f Dockerfile.anchore-db -t anchore:db .

Move the Files and Images to the High Side

Choose one of the following, matching the equivalent step in the Air-Gapped Docker Compose deployment guide:

Private container registry (recommended) — re-tag, then push directly, or save/transfer/load/push, exactly as described in Option 1, for all four images pulled/built above.
Local image tarball — for hosts with no registry available, as described in Option 2.

Also transfer docker-compose.yaml, Dockerfile.anchore-db, and your license.yaml to the high side along with the images — you’ll need docker-compose.yaml in Step 4 of the main runbook, and the Dockerfile is kept for reference even though anchore:db is already built.

Point Your Compose File at the Registry (or Local Images)

Update the image: lines in your new docker-compose.yaml exactly as described in Deploy on the High Side on the deployment air-gapped page — point every service referencing docker.io/anchore/enterprise and docker.io/anchore/enterprise-ui at your registry tag or locally loaded image name, replace anchore-db’s build: section with a direct image: <registry>/anchore:db (or image: anchore:db for a local tarball) reference, and update the redis image line the same way.

Run the Migration from the Local Files

Continue with the main migration runbook starting at Step 4, substituting the compose file you just edited for the one Step 4 would otherwise download, and skipping the curl commands there — you already have both files from the low side.

Every other step needs no changes for an air-gapped host:

Step 5: Configure Secrets through Step 10: Validate the Upgrade run exactly as written.
Step 7: Export the v5.x Database and Step 8: Restore the Data into the New Database are a direct pg_dump/pg_restore against your own database containers and require no internet access either way.

Because the deployment cannot reach the Anchore Data Service, complete Air-Gapped Feed Configuration on the new v6.x deployment — disable the Data Syncer’s automatic feed sync and import feed bundles manually with AnchoreCTL — or the migrated deployment will have no vulnerability data.