Skip to main content

Upgrading OpenCLM

Follow this procedure to upgrade your self-hosted OpenCLM instance safely.

Before You Upgrade​

  1. Read the release notes — check GitHub Releases for breaking changes, migration notes, and new environment variables required.
  2. Back up your database — always back up before upgrading. 
    docker compose exec -T db pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB} | gzip > openclm_backup_$(date +%Y%m%d).sql.gz
  3. Test in staging — if you have a staging environment, upgrade it first.

Upgrade Steps​

Docker Compose Deployment​

# 1. Pull the latest images
docker compose pull

# 2. Restart containers with new images
docker compose up -d

# 3. Apply database migrations
docker compose exec api npx prisma migrate deploy

# 4. Verify the upgrade
docker compose ps
docker compose logs api --tail=50

That's it for most upgrades.

Manual / Source Deployment​

# 1. Pull the latest code
git fetch origin
git checkout main
git pull

# 2. Install / update backend dependencies
cd server
npm install

# 3. Build the frontend
cd ..
npm install
npm run build

# 4. Apply migrations
cd server
npx prisma migrate deploy

# 5. Restart the API
pm2 restart openclm-api  # or systemctl restart openclm-api

Major Version Upgrades​

When upgrading across major versions (e.g. v1.x → v2.x):

  • Read the Migration Guide in the release notes.
  • Some major upgrades require manual data migration steps.
  • Allow for a maintenance window.

Rollback​

If an upgrade causes issues:

# 1. Restore the database backup
gunzip < openclm_backup_YYYYMMDD.sql.gz | docker compose exec -T db psql -U ${POSTGRES_USER} ${POSTGRES_DB}

# 2. Roll back to the previous Docker image tag
docker compose down
# Edit docker-compose.yml to pin the previous image version tag
docker compose up -d

Database migrations are not automatically reversible. The backup restore is the safest rollback path.

Checking Your Current Version​

In the OpenCLM UI, go to Settings → About. The current version number is shown there.

Via API:

curl https://openclm.yourdomain.com/api/version

Response:

{"version": "1.4.2", "buildDate": "2025-09-15"}