Consent Docs
Open console

Upgrade and roll back

Move a self-hosted deployment to a newer build, check it, and return to the earlier build if something goes wrong.

How-to3 min readFor project administrators and deployment operators

Do this to move your deployment to a newer commit. The repository publishes no images, so you build your own and tag each build with its commit.

Before you start#

  • Run the commands in your clone, next to docker-compose.yml.
  • Choose a name for your image tags. The examples use registry.example.in.

Upgrade#

  1. Tag the images you run now with their commit, so you can return to them.

    Shell
    old=$(git rev-parse --short HEAD)
docker tag piedap-consent-consent-api \
  registry.example.in/piedap-consent-api:$old
docker tag piedap-consent-consent-web \
  registry.example.in/piedap-consent-web:$old

  2. Fetch the new commit and list the migrations it adds.

    Shell
    git fetch
git diff --stat HEAD <new commit> -- server/src/migrations
git checkout <new commit>

  3. Back up the database. Some migrations cannot be undone.

  4. Build and start the new version. The API applies the migrations, then starts to serve.

    Shell
    docker compose up -d --build
docker compose logs -f consent-api

  5. Check that the API is up.

    Shell
    curl -s http://127.0.0.1:8080/health

  6. Sign in to the console, then load a page that shows the banner.

  7. Open Audit, then choose Verify on the latest evidence anchor.

The upgrade worked when /health answers 200, the banner loads and the anchor verifies.

What a restart loses is in Scheduled jobs.

Keep older runtime versions in the image

Some sites pin a runtime version and load /sdk/v1/runtime/<version>/…. Do not delete older folders from server/src/sdk/assets/runtime, or those sites lose their banner.

If you changed an SDK

The built SDK files for version 1.0.7 are in the repository, so a plain build serves them. After a change to an SDK, build them again before the image. The script needs Node.js, npm ci run in packages/consent-js, and Python 3 with the build module.

Shell
./scripts/sync-sdk-assets.sh
docker compose build consent-api
With several API replicas

Start one replica of the new version first. Let it finish the migrations before you start the rest. Until the last one is replaced, old replicas run against the new schema. That is safe only when the migrations add things and change nothing the old code uses. If you have not checked, plan a short maintenance window.

Large record tables#

The release of 3 October 2026 adds indexes to consent_record and audit_log. Its migrations block writes to those tables while they build. On a large database, build these three beforehand without blocking, and the migrations skip them.

SQL
CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_2ba869dc17db2d4894721e529e"
  ON consent_record ("projectId", "collectedOn");
CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_165715fcb46d581a1395237f19"
  ON consent_record ("projectId", "expiresOn");
CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_0c52b62c8ebaf3c3d4ff9561d4"
  ON audit_log ("projectId", "createdOn", "id");

Two more indexes, on the new basis and importId columns, cannot be built beforehand. They cover no existing row, but each still reads the whole table once while writes to it wait.

A concurrent build that fails leaves an invalid index, which the migration also skips. Before you upgrade, check that indisvalid is t for each. Drop an invalid one and build it again.

SQL
SELECT indexrelid::regclass AS index, indisvalid
  FROM pg_index
 WHERE indexrelid::regclass::text LIKE '"IDX_%';

Its ten migrations add tables, columns and an append-only trigger on audit_log. In production the API does not start while ALLOW_PRIVATE_WEBHOOK_URLS is true: set PRIVATE_NETWORK_ALLOWLIST instead. See Configuration.

Roll back#

What you can do depends on whether the upgrade changed the schema.

Situation Roll back by
No new migrations Starting the earlier images again
New migrations, and you can lose what was recorded since Stopping the API, restoring the backup from before the upgrade, then starting the earlier images
New migrations, and you must keep what was recorded since Fixing forward with a new build. The earlier image may not run against the newer schema

To start the earlier images:

  1. Give the names the compose file uses back to the earlier build.

    Shell
    docker tag registry.example.in/piedap-consent-api:<old commit> \
  piedap-consent-consent-api
docker tag registry.example.in/piedap-consent-web:<old commit> \
  piedap-consent-consent-web

  2. Start the stack without building.

    Shell
    docker compose up -d --no-build

  3. Check /health and sign in, as after an upgrade.

Do not plan on npm run migration:revert. It undoes one migration at a time from a source checkout. Some migrations refuse to revert once evidence depends on them. Once a record carries a basis, a notice or a capture context, an earlier release reports its events as tampered, so fix forward.

↑↓ to move, Enter to open