Skip to main content

Upgrading

Regular upgrade​

By default all components use the latest tag, so an upgrade is just two commands:

docker compose pull
docker compose up -d

To pin a specific version, set it in .env — one variable for every component:

# .env
XLADA_VERSION=1.1.7

Database migrations are applied automatically when the panel container starts.

Before upgrading​

Dump the database — this is the only reliable way to roll back:

docker exec xpanel-db pg_dump -U xpanel xpanel > backup-$(date +%F).sql

Also keep .env safe: the APP_SECRET, POSTGRES_PASSWORD, and domain values must survive the upgrade unchanged.

What not to do​

  • docker compose down -v — the -v flag deletes the volumes along with the database.
  • Changing APP_SECRET after the first start — this breaks login and TOTP.
  • Renaming volumes and services — on upgrade compose creates new empty volumes, and the data stays in the old ones.

Rollback​

docker compose down
# restore the previous XLADA_VERSION value in .env
docker compose up -d
docker exec -i xpanel-db psql -U xpanel -d xpanel < backup-2026-01-01.sql
warning

Migrations are not rolled back automatically. If the new version has already applied the migrations, restoring the dump is the only way to return the schema to its previous state.

Check the current version​

The version is visible in the panel footer and in the API response:

curl -s https://panel.example.com/api/system/health | head