Migration Guide

For Contributors

To mitigate any potential hiccups when moving to the new repo, all contributors should clone the new project fresh, as if it was a brand new project.

Any pull requests open prior to March 29, 2025 have had their underlying code migrated to a branch with the naming convention of [Author username]/[original branch name]. To continue working on your pull request:

1. Create a fork of the new repository
2. Find your original branch based on your username
3. File a new pull request from this branch
4. Continue iterating on your pull request until it is ready to merge

If for some reason this process is not working for you, please reach out to a maintainer on the #wg-collectoss-8knot slack channel. We would love to help you continue working on your contributions

For Deployed Instances

Scope: CollectOSS v1.0.0 (the Initial Release). v1.0.0 is intentionally a low-risk drop-in — no API changes, no env-var renames, and only minor schema migrations that don't touch data. The second CollectOSS release will require more involved migration (renaming AUGUR_* env vars, renaming PostgreSQL schemas, etc.); a separate guide will accompany that release.

Docker deployments

Existing Augur deployments running under docker compose can drop the v1.0.0 CollectOSS images straight into the existing docker-compose.yml. Published on GHCR:

• ghcr.io/chaoss/collectoss:v1.0.0 — main backend (Celery workers, Flask API, scheduler)
• ghcr.io/chaoss/collectoss-database:v1.0.0 — PostgreSQL with schema
• ghcr.io/chaoss/collectoss-keyman:v1.0.0 — API-key orchestrator
• ghcr.io/chaoss/collectoss-rabbitmq:v1.0.0 — RabbitMQ (see caveat below)

A :latest tag exists and points at the same images, but pin to :v1.0.0 in production — auto-updating to whatever :latest happens to point at is not recommended.

Bring your data with you

1. Reuse your existing .env, or copy values into the new one. Variable names are unchanged in v1.0.0 — still AUGUR_DB, AUGUR_DB_USER, AUGUR_DB_PASSWORD, AUGUR_RABBITMQ_USERNAME, AUGUR_RABBITMQ_PASSWORD, AUGUR_RABBITMQ_VHOST, AUGUR_GITHUB_API_KEY, etc.
2. Use the same passwords for the Postgres and RabbitMQ users so existing volumes and queues continue to work without re-initialization.
3. PostgreSQL schema names are unchanged (augur_data, augur_operations, spdx). Your existing data is picked up as-is.

Schema migrations on first boot

v1.0.0 contains a small number of database migrations that alembic will run automatically on first startup. None of them touch row data:

• A migration to rename Augur → CollectOSS in various schema comments (#2)
• The uniqueness constraint on contributor alias emails was loosened to allow multiple contributors with the same email (#288)
• An unused test database table in the public schema was dropped (#281)

You don't need to run these by hand — they apply automatically because AUGUR_DB_SCHEMA_BUILD=1 is set in the default docker-compose.yml.

RabbitMQ — important caveat

The new collectoss-rabbitmq image expects username collectoss and vhost collectoss_vhost. If your existing stack uses the Augur defaults (username augur, vhost augur_vhost), keep using the Augur v0.92.0 rabbitmq image for now — v1.0.0 is explicitly compatible with it. Swapping the image without also reconfiguring AUGUR_RABBITMQ_USERNAME, AUGUR_RABBITMQ_VHOST, and the RABBITMQ_CONN_STRING on core and keyman will break message routing.

When you're ready to cut over to the CollectOSS rabbit image, the actual change is just renaming the username and vhost in the places they're configured. The collectoss-rabbitmq image already has these as its baked-in defaults, so you don't need to override anything on the rabbit container itself — only on the things that connect to it.

Locations to update from augur / augur_vhost to collectoss / collectoss_vhost:

1. .env — AUGUR_RABBITMQ_USERNAME=collectoss and AUGUR_RABBITMQ_VHOST=collectoss_vhost.
2. The core service env vars in docker-compose.yml, where RABBITMQ_CONN_STRING is interpolated — confirm the defaults inside the ${AUGUR_RABBITMQ_USERNAME:-...} and ${AUGUR_RABBITMQ_VHOST:-...} fallbacks also point at the new values, so the connection string resolves correctly even without .env.
3. The flower service env vars, if you've enabled flower — same defaults need updating there.

Then stop services, swap the rabbit image to ghcr.io/chaoss/collectoss-rabbitmq:v1.0.0, and bring everything back up.

Redis

No migration. CollectOSS uses an unmodified upstream redis:alpine, identical to Augur. Leave the service as-is.

Keyman

Keyman only talks to Redis, so swapping to ghcr.io/chaoss/collectoss-keyman:v1.0.0 is independent of every other change. Either image works.

Suggested swap order

1. Backend / core — most visible change, but contained.
2. Database — existing volumes continue to work; swap whenever convenient. Alembic migrations run on first startup of the new backend.
3. Keyman — stateless w.r.t. the swap; do it any time.
4. RabbitMQ — leave on the Augur v0.92.0 image until you're ready to reconfigure user/vhost.
5. Redis — leave alone.

Rollback

Migrations in v1.0.0 only touch schema comments, one unique constraint, and an unused table — they don't modify row data, so the database is operationally fine for the old Augur image either way. The catch is alembic itself: if Augur boots and sees a stamped revision it doesn't know about, it may refuse to start until the version is reconciled.

If you hit a rollback that doesn't come back cleanly, ask for help in the #wg-collectoss-8knot Slack channel rather than improvising — the right move depends on how far the v1.0.0 boot got before things broke.

Manual (non-Docker) deployments

Manual installs need to migrate to Docker first, then follow the steps above. There is no manual-Augur → manual-CollectOSS path supported in v1.0.0.

Typical sequence:

1. Back up the database (pg_dump) and your .env / config files.
2. Stand up a Docker-based Augur deployment using the backed-up data, and confirm it runs cleanly.
3. Drop in the v1.0.0 CollectOSS images per the Docker section above.