Skip to content

Migration Guide

Jump to bottom
Shlok Gilda edited this page May 5, 2026 · 5 revisions

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 (release notes · discussion). Low-risk drop-in: no API changes, no env-var renames, only minor migrations that don't touch data. The next release will rename AUGUR_* env vars and PostgreSQL schemas — separate guide will follow.

Docker deployments

Drop the v1.0.0 images into your existing docker-compose.yml:

  • ghcr.io/chaoss/collectoss:v1.0.0 — backend
  • ghcr.io/chaoss/collectoss-database:v1.0.0 — PostgreSQL
  • ghcr.io/chaoss/collectoss-keyman:v1.0.0 — key orchestrator
  • ghcr.io/chaoss/collectoss-rabbitmq:v1.0.0 — RabbitMQ (see caveat)

Pin to :v1.0.0. :latest exists but auto-updates aren't recommended.

Bringing data with you

Reuse your existing .env — variable names (AUGUR_DB, AUGUR_RABBITMQ_*, AUGUR_GITHUB_API_KEY, etc.) and schema names (augur_data, augur_operations, spdx) are unchanged. Keep your existing Postgres and RabbitMQ passwords so existing volumes and queues keep working.

Schema migrations

Alembic auto-applies three migrations on first boot (none touch row data):

  • Augur → CollectOSS rename in schema comments (#2)
  • Loosened uniqueness on contributor alias emails (#288)
  • Dropped an unused test table in public (#281)

RabbitMQ

The collectoss-rabbitmq image defaults to user collectoss / vhost collectoss_vhost. If your stack still uses the Augur defaults (augur / augur_vhost), stay on the Augur v0.92.0 rabbit image — v1.0.0 is compatible with it.

To cut over later, update user/vhost from augur → collectoss and augur_vhost → collectoss_vhost in:

  1. .env
  2. The core service env-var defaults in docker-compose.yml (the ${AUGUR_RABBITMQ_USERNAME:-...} / ${...VHOST:-...} fallbacks)
  3. The flower service env vars, if flower is enabled

Then swap the image to ghcr.io/chaoss/collectoss-rabbitmq:v1.0.0 and restart.

Redis & Keyman

Redis is unmodified upstream: leave it alone. Keyman only talks to Redis, so ghcr.io/chaoss/collectoss-keyman:v1.0.0 swaps in cleanly any time.

Suggested swap order

core → database → keyman → rabbitmq (when ready to reconfigure). Leave Redis alone.

Rollback

The migrations don't modify row data, so the DB stays operationally fine for the old Augur image. But alembic on Augur may refuse to start if it sees a newer stamped revision. If rollback doesn't come back cleanly, ask in #wg-collectoss-8knot rather than improvising — the fix depends on how far v1.0.0 got before breaking.

Manual (non-Docker) deployments

Bare-metal installs are no longer supported. Migrate to Docker first, then follow the steps above.

  1. Back up the database (pg_dump) and .env / config.
  2. Stand up Augur on Docker against the backed-up data, confirm it runs.
  3. Drop in the v1.0.0 images per above.

Clone this wiki locally