Skip to content

Documentation

Upgrading a self-hosted install

Back up, upgrade, check and roll back EvenTier on Docker Compose, Kubernetes or a Linux server.

Where
Account console (Deploy) · docker compose · helm upgrade · install.sh
Permission
Admin of the host, cluster or server · access to the database backups
Updated
October 2026

Before you start

Each release comes as a container image, a Helm chart and a server tarball. The Deploy page in your account console names the current release, and the changelog lists what changed.

You can skip releases. The new release applies every database change in between, in order.

Database changes only go forward, so back up the database before every upgrade. Keep SECRET_ENCRYPTION_KEY with the backup.

An upgrade swaps the image, chart version or tarball and nothing else. Never replace your settings file with one from a new bundle download: it carries new secrets.

Step by step

  1. 01

    Check your current version

    Note the version you run now, so you know what you are upgrading from.

    Current versionbash
    # Docker Compose
    docker compose exec app node -p 'require("./package.json").version'
    
    # Kubernetes
    helm list
    
    # Server
    /opt/eventier/current/bin/eventier version
  2. 02

    Back up the database

    Dump or snapshot the database before you start. The examples below show the command for each path.

    • Keep the backup until the new release has run cleanly for a day
  3. 03

    Upgrade on Docker Compose

    Point EVENTIER_IMAGE in .env at the new release, then pull it, update the database and restart.

    • Expect a few seconds of 502 errors while the app restarts
    In the bundle folderbash
    # First set EVENTIER_IMAGE in .env to the image reference from Deploy
    docker compose pull app
    docker compose run --rm migrate
    docker compose up -d
  4. 04

    Upgrade on Kubernetes

    Check the new image's signature, then run helm upgrade with the new chart version and your values file.

    • Don't pass --reuse-values: it keeps the old chart's image digest
    • Keep the eventier-secrets Secret as it is: never apply the secrets.yaml from a newer bundle download
    Upgradebash
    helm upgrade eventier oci://ghcr.io/eventierio/charts/eventier --version <new x.y.z> -f my-values.yaml --wait --timeout 15m
  5. 05

    Upgrade on a server

    Run install.sh with the new tarball.

    • It updates the database, switches /opt/eventier/current to the new release and restarts the service
    • eventier.env, uploads and the previous release are kept
    With the new tarball from Deploy next to install.shbash
    sudo ./install.sh eventier-server-<new x.y.z>-linux-x64.tar.gz
  6. 06

    Check the new release

    Check that it is healthy and licensed.

    • /api/health/ready returns 200 once the database is reachable and up to date
    • Sign in and confirm Admin > Billing shows a valid license
    Health checkbash
    curl -fsS https://<your domain>/api/health/ready
  7. 07

    Roll back if needed

    Stop the app, restore the backup if the new release changed the database, then go back to the previous image, Helm revision or release directory.

    • The examples below have the full commands for each path

Examples

Docker Compose: upgradebash
# In the bundle folder: back up the database and the settings first
docker compose exec -T postgres pg_dump -U eventier -d eventier -Fc > eventier-$(date +%Y%m%d%H%M).dump
cp -p .env .env.before-upgrade

# Set EVENTIER_IMAGE in .env to the image reference from Deploy, then
docker compose pull app
docker compose run --rm migrate
docker compose up -d
curl -fsS https://eventier.internal.example.com/api/health/ready
Docker Compose: roll backbash
docker compose stop app

# Only if the new release applied migrations: restore the pre-upgrade dump
docker compose exec -T postgres dropdb -U eventier eventier
docker compose exec -T postgres createdb -U eventier eventier
docker compose exec -T postgres pg_restore -U eventier -d eventier --no-owner < eventier-<stamp>.dump

# Put the previous EVENTIER_IMAGE back (it is in .env.before-upgrade), then
docker compose up -d
Kubernetes: upgrade and roll backbash
# Back up: your managed database's snapshot, or a dump of the bundled PostgreSQL
kubectl exec statefulset/eventier-postgresql -- pg_dump -U eventier -d eventier -Fc > eventier-$(date +%Y%m%d%H%M).dump

cosign verify ghcr.io/eventierio/eventier@sha256:<new digest> \
  --certificate-identity-regexp '^https://github.com/eventierio/eventier/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
helm upgrade eventier oci://ghcr.io/eventierio/charts/eventier --version <new x.y.z> -f my-values.yaml --wait --timeout 15m

# Roll back: stop writes, restore the backup if migrations ran, return to the previous revision
helm history eventier
kubectl scale deployment/eventier deployment/eventier-worker --replicas=0
kubectl exec statefulset/eventier-postgresql -- dropdb -U eventier eventier
kubectl exec statefulset/eventier-postgresql -- createdb -U eventier eventier
kubectl exec -i statefulset/eventier-postgresql -- pg_restore -U eventier -d eventier --no-owner < eventier-<stamp>.dump
helm rollback eventier <previous revision> --wait
# With autoscaling on, the chart sets no replica count: scale back up and the HPA takes over
kubectl scale deployment/eventier deployment/eventier-worker --replicas=2
Server: upgrade and roll backbash
# Back up first (a PostgreSQL on the same server is shown; use your own tooling otherwise)
sudo -u postgres pg_dump -Fc eventier > eventier-$(date +%Y%m%d%H%M).dump
sudo cp -p /etc/eventier/eventier.env /etc/eventier/eventier.env.before-upgrade

# With the new tarball from Deploy next to install.sh
sudo ./install.sh eventier-server-<new x.y.z>-linux-x64.tar.gz
/opt/eventier/current/bin/eventier version
curl -fsS http://127.0.0.1:3000/api/health/ready

# Roll back: stop, restore the dump if migrations ran, point current at the previous release
sudo systemctl stop eventier
sudo -u postgres dropdb eventier
sudo -u postgres createdb -O eventier eventier
sudo -u postgres pg_restore -d eventier --no-owner --role=eventier < eventier-<stamp>.dump
ls /opt/eventier/releases
sudo ln -sfn /opt/eventier/releases/eventier-server-<previous x.y.z>-linux-x64 /opt/eventier/current
sudo systemctl start eventier

What an upgrade replaces and keeps

What's kept survives an upgrade, and is what a rollback returns to.

PathReplacedKept
Docker ComposeThe app image named by EVENTIER_IMAGE in .env.env and its secrets; the postgres-data, eventier-uploads, clamav-db and caddy-data volumes; the previous image until you prune it
KubernetesThe chart version and the image digest it pinsYour values file, Secrets, persistent volumes and external database; every earlier Helm revision
Linux server/opt/eventier/current, which points at a new directory under /opt/eventier/releases/etc/eventier/eventier.env, /opt/eventier/uploads, the previous release directory, your PostgreSQL and clamd

Good to know

  • Upgrade a staging install first.
  • Air-gapped: copy the image into your registry, or carry the tarball across, and follow the same steps.
  • Once the new release runs cleanly, remove old images, old directories under /opt/eventier/releases and the pre-upgrade dump.