Instance Upgrade

1. Upgrade Overview

Due to its simple architecture and streamlined deployment, upgrading a Docker Compose installation is significantly easier compared to other methods. Upgrades typically involve updating the container images and making minor configuration adjustments.

⚠️ Pre-upgrade Notice: Breaking Changes

Before each upgrade, please review the csghub-omnibus Release Notes to check whether the target version introduces any breaking changes.

Known breaking changes:

Version Range	Breaking Change	Action Required
v2.3.0 and later	Built-in PostgreSQL upgraded from 15.x to 16.x	Must export data via pg_dumpall before upgrade and import after; otherwise the container will fail to start due to incompatible data directory
v2.0.0-ce/ee	Dataflow log storage switched from MongoDB to PostgreSQL	Must manually run Dataflow database migration after upgrade

2. Prerequisites

v2.3.0

PostgreSQL Database Upgrade (15.x → 16.x)

v2.3.0 upgrades the built-in PostgreSQL from 15.17 to 16.14. PostgreSQL major versions are not compatible at the data directory level, requiring a logical backup and restore (pg_dumpall / psql) to complete the upgrade.

1. Pre-upgrade Preparation (Backup v2.2.0 Data)

Before pulling the new image, stop all application services inside the container, keep only PostgreSQL running, and export all data. Key principle: all external write access to PostgreSQL must be stopped before and after the backup/restore.

1. Stop all services except PostgreSQL:

   # Stop all services
   docker exec -it csghub-omnibus csghub-ctl stop
   # Start only PostgreSQL
   docker exec -it csghub-omnibus csghub-ctl start postgresql

2. Dump all databases:

   docker exec -it csghub-omnibus su - postgres -c "pg_dumpall --clean --if-exists -U csghub -f /tmp/all_dbs.sql"

3. Copy the backup file to the host:

   docker cp csghub-omnibus:/tmp/all_dbs.sql ./all_dbs.sql

4. Stop and remove the old container:

   docker compose down

5. Back up the old PostgreSQL data directory (needed for rollback):

   The default data directory path is ./csghub/data/postgresql/data. Adjust according to the volume mapping in your docker-compose.yaml.

   mv ./csghub/data ./csghub/data.backup

2. Start the New Container

Pull the new image and start the container. PostgreSQL 16.14 will automatically initialize a fresh empty data directory:

docker compose pull && docker compose up -d

3. Restore the Database

After the container is ready, restore the backup to the new database:

1. Copy the backup file into the new container:

   docker cp ./all_dbs.sql csghub-omnibus:/tmp/all_dbs.sql

2. Stop all services except PostgreSQL again to ensure no other connections are reading or writing the database:

   docker exec -it csghub-omnibus csghub-ctl stop
   docker exec -it csghub-omnibus csghub-ctl start postgresql

3. Terminate non-template connections and restore data:

   docker exec -it csghub-omnibus su - postgres -c "psql -U csghub -c \"SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname NOT IN ('template0', 'template1') AND pid <> pg_backend_pid();\""
   docker exec -it csghub-omnibus su - postgres -c "psql -U csghub -f /tmp/all_dbs.sql"

   Note: The --clean --if-exists flags in pg_dumpall automatically drop existing roles and databases before recreation, preventing conflicts with default resources created during initialization.

4. Reconfigure and start all services:

   docker exec -it csghub-omnibus csghub-ctl reconfigure
   docker exec -it csghub-omnibus csghub-ctl start

5. Verify service status:

   docker exec -it csghub-omnibus csghub-ctl status

If there is no existing data to migrate (e.g., a fresh installation or test environment), skip the steps above and proceed directly to docker compose pull && docker compose up -d.

3. Upgrade Procedure

1. Pull images and recreate containers (skip database backup for versions other than v2.3.0):

   docker compose pull && docker compose up -d

2. Verify service status

   docker exec -it csghub-omnibus csghub-ctl status

4. Post-Upgrade Troubleshooting

If the services are abnormal after an upgrade, follow these steps to diagnose the issue:

Check Docker Compose Logs

View the container's standard output to identify initialization or environment errors:

docker compose logs -f

• Initialization Errors: Usually indicate a syntax error or a breaking change in the docker-compose.yaml configuration format.
• Runtime Errors: May indicate issues with internal service dependencies.

Check Specific Service Logs

If the main Docker logs show no obvious errors, enter the container to inspect logs for the specific failing component:

# View logs for all or a specific service (e.g., csghub-ctl tail server)
docker exec -it csghub-omnibus csghub-ctl tail <service_name>

5. Support

If you are unable to determine the cause of the failure, please collect the relevant logs and submit a support request via the official issue tracker.