Skip to content

Migration Guide

Jump to bottom
Adrian Edwards edited this page May 6, 2026 · 7 revisions

This guide covers the basics of migrating to CollectOSS 1.0.0 (release notes · discussion) from Augur.

If you would like assistance or believe your situation is different from these use cases, please join us in the #wg-collectoss-8knot channel of the CHAOSS Slack and a maintainer can help you with the transition.

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. Make any changes needed, such as rebasing your branch or updating the project name
  4. File a new pull request from your modified branch
  5. Work with the maintainers 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, we would love to help you continue working on your contributions

For Deployed Instances

v1.0.0 is meant to be a soft-landing in the CollectOSS project with low-risk, drop-in containers. API's, environment variables, and most of your configuration can remain unchanged.

In the next minor release will provide a further migration guide for things like AUGUR_* env vars and other more impactful changes, with a separate guide to follow.

Docker deployments

If docker is how your existing instance is running, you can swap in the following images into your compose file:

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

  • backend becomes ghcr.io/chaoss/collectoss:v1.0.0
  • augur-database becomes ghcr.io/chaoss/collectoss-database:v1.0.0 (existing instances can also use the regular postgres:16 container if you choose)
  • keyman becomes ghcr.io/chaoss/collectoss-keyman:v1.0.0
  • rabbitmq should remain unchanged.
  • redis can use the :alpine version, we do not make any customizations to upstream redis.

We recommend pinning the versions of the collectoss containers to :v1.0.0, rather than :latest so that you can update when it makes sense for you. We encourage instance admins to look at the release notes before updating to understand what changes to expect.

Your existing environment variables should continue to work as-is in v1.0.0.

If you have trouble with your migration, please reach out on slack and the maintainers can help you get back up and running.

Manual (non-Docker) deployments

Bare-metal installs aren't supported by CollectOSS. Ask in #wg-collectoss-8knot and we'll help you migrate to Docker.

Clone this wiki locally