Upgrading

What the Conzent OCI updater preserves and what it resets, how to customise a self-hosted install so your changes survive, and how to roll back.

Upgrading

cd /path/to/conzent
bash scripts/backup.sh && bash scripts/install.sh --update

Or, from anywhere:

curl -sSL https://getconzent.com/install | sh -s -- --update

Take the backup first. Migrations run automatically and are not reversible.

What the update does

Step Effect
git fetch + git reset --hard Tracked files are reset to the release. Local edits to them are discarded
docker compose down Containers stop. Volumes are kept — your database survives
Removes the app-public volume Stale CSS/JS/media is cleared so the new build's assets are served
docker compose build --no-cache --pull Full rebuild, ignoring layer cache
docker compose up -d Everything starts again
migrations:migrate Applies pending schema migrations only
scanner:register Re-registers the bundled scanner (idempotent)
Redis flush + template cache clear Drops stale sessions and compiled templates
Admin creation Skipped — your users are untouched

Expect a few minutes for the no-cache rebuild.

What survives: the database, generated consent scripts, and every untracked file — .env, .conzent-credentials, docker-compose.override.yml, backups/.

What does not: edits to tracked files such as docker-compose.yml, the nginx config, templates, and source files; the app-public volume; and Redis contents, so everyone is signed out.

Customising without losing it

The rule: never edit a tracked file. There are two supported places for your changes.

.env holds all configuration — APP_URL, APP_PORT, SMTP, scanner tuning, third-party keys.

docker-compose.override.yml holds anything about the stack itself. Compose merges it automatically and it is gitignored:

services:
  # Publish the scanner so remote installs can reach it
  scanner:
    ports:
      - "8300:8300"

  # Give MariaDB more memory
  mariadb:
    command: --innodb-buffer-pool-size=1G

  # Mount custom nginx config
  nginx:
    volumes:
      - ./docker/nginx/custom.conf:/etc/nginx/conf.d/default.conf:ro

Files you add — a Caddyfile, a custom nginx conf — are untracked and survive updates. Files you modify do not.

Verifying an upgrade

docker compose ps
docker compose exec app php bin/oci health
docker compose exec app php bin/oci scanner:health

Then load the dashboard and confirm your customisations are intact. If a banner on a live site looks wrong afterwards, run docker compose exec app php bin/oci scripts:regenerate.

If an upgrade goes wrong

# 1. What broke
docker compose logs --tail=100 app

# 2. Roll back code and data together
git checkout <previous-tag>
docker compose build --no-cache && docker compose up -d
bash scripts/restore.sh backups/<archive-taken-before-the-upgrade>.tar.gz --yes

Restoring the pre-upgrade backup is what undoes a migration — rolling back code alone leaves the new schema in place. That is the reason for the backup-first rule.

Uninstalling

bash scripts/install.sh --uninstall

This runs docker compose down -v, deleting every volume including the database, then removes the install directory. It asks for confirmation first. Take a backup if there is any chance you will want the data back.

The full reference lives with the code: docs/upgrading.md on GitHub.

Back to Documentation