Upgrade & Uninstall

In-Product Updates (Settings → Updates)

The panel checks for new releases on its own and surfaces them in Settings → Updates — no terminal needed to know an update exists. This page shows:

• Your current version vs. the latest available, with an "Update available" badge when you're behind.
• What's new — the release notes / changelog for the latest version.
• Release channel — choose Stable (released versions) or Beta (release candidates, so you can preview the next release before it ships). Stable is the default.
• Pin current version — freeze updates at the version you're on until you unpin. Useful when you want to hold a known-good version through a busy period.
• Check now — force an immediate check instead of waiting for the daily automatic check.

You don't have to open this page to find out an update exists: when a newer version is available, a dismissible "Panel update available" banner appears at the top of every admin page, with a one-click View update link straight to this tab. The banner stays hidden while you have a version pinned, and dismissing it for one release won't hide the banner when the next release lands.

Viewing the Updates page and changing the channel/pin requires the system.update permission (granted to Admin and Reseller by default).

Update now (one-click)

When an update is available, an Update now button appears on the Updates page (and you can reach it from the global banner's View update link). One click — no terminal — and the panel updates itself safely:

1. Confirm. A dialog explains the panel will back up the database and briefly restart.
2. Database backup first. The panel takes a pg_dump backup before anything changes. If the backup fails, the update is aborted — your data is never at risk. The three most recent pre-update backups are kept (older ones are pruned) under /opt/aiadminpanel/backups/.
3. Signature verification (verify-or-refuse). The target image must carry a valid signature from the official AI Admin Panel release pipeline. An unsigned or tampered image is refused and nothing is swapped — this is fail-closed, with no bypass.
4. Swap + health check. The panel pulls the verified image, restarts, and watches its own health.
5. Automatic rollback. If the new version doesn't come up healthy in time, the panel automatically rolls back to the version you were on. The pre-update backup remains available if a migration changed data and you want to restore it.

While an update runs you'll see "Updating to 2.7.0…", then "Updated to 2.7.0" on success, or "Update rolled back: health check failed" if it had to revert.

Because applying a panel-wide update restarts the panel and affects every tenant, the Update now action requires the Admin-only system.update.apply permission — a tier above the shared system.update (view/check/pin). Resellers can see that an update is available but cannot trigger it.

Automatic updates (opt-in)

If you'd rather not click Update now yourself, turn on Automatic updates in the same Settings → Updates page. It's off by default — you opt in.

When on, you pick:

• A daily time (e.g. 02:00) — the time of day an available update may apply.
• A timezone — so 02:00 means 2 AM where you are, not on the server's clock.

At that window each day, if an on-channel update is available and the version isn't pinned, the panel applies it using the exact same safe path as Update now — pg_dump backup, signature verification, swap, health check, and automatic rollback if the new version isn't healthy. A scheduled update is exactly as safe as a manual one; it does not add any new privileged access.

What to expect:

• You're always told the outcome. Every automatic update sends a notification — "Panel automatically updated to 2.8.0", or "Automatic update to 2.8.0 rolled back: …". The Last run line on the card shows the most recent result too.
• A pinned version is never auto-updated. Pinning always wins.
• A bad release isn't retried in a loop. If an automatic update rolls back, the panel won't keep trying that same version every night — it waits for a newer release or for you to act.
• Missed the window? It still runs. If the box was off at 02:00, the update applies on the next check that day; if the whole day is missed, it runs the next day. At most one automatic update happens per day.

Turning Automatic updates on or off requires the Admin-only system.update.apply permission (the same one Update now needs) — viewing the page only needs system.update.

How it works under the hood (no docker.sock in any container). The panel itself is unprivileged for updates — it only writes a small request file. A host systemd service (aap-updater.path / aap-updater.service, installed by the installer) is the only privileged actor: it runs the backup, signature check, swap, and rollback as root. No container is given write access to the Docker socket for updating, keeping with the secure-and-sovereign design.

Prefer the command line, or running an unattended/air-gapped box? The Standard Upgrade steps below remain fully supported as the manual path.

Upgrading

Standard Upgrade

AI Admin Panel uses Docker images for upgrades. To update to the latest version:

cd /opt/aiadminpanel

# Pull the latest images
docker compose pull panel

# Restart with the new version
docker compose up -d panel

The panel runs database migrations automatically on startup. No manual migration steps are needed.

Upgrade to a Specific Version

# Edit .env to pin the version
sed -i 's/PANEL_VERSION=.*/PANEL_VERSION=1.8.0/' /opt/aiadminpanel/.env

# Pull and restart
docker compose pull panel
docker compose up -d panel

Pre-Upgrade Checklist

Before upgrading, especially for major versions:

1. Back up the database:

docker exec aiadminpanel_postgresql pg_dump -U aiadminpanel -d aiadminpanel > /opt/aiadminpanel/backup-pre-upgrade-$(date +%Y%m%d).sql
docker exec aiadminpanel_postgresql pg_dump -U aiadminpanel -d keycloak > /opt/aiadminpanel/backup-keycloak-pre-upgrade-$(date +%Y%m%d).sql

2. Save the current binary (for rollback):

docker tag ghcr.io/aiadminpanel/ai-admin-panel:latest ghcr.io/aiadminpanel/ai-admin-panel:pre-upgrade-backup

3. Check the changelog for breaking changes at https://docs.aiadminpanel.com/docs/getting-started/changelog.

Verify After Upgrade

# Check health
curl -s https://panel.example.com/healthz | jq .

# Check version
curl -s https://panel.example.com/api/v1/setup/status | jq .version

# Check all containers
docker compose ps

# Check migration ran
docker logs --tail 20 aiadminpanel_panel | grep -i migration

Rolling Back

If an upgrade causes issues, roll back to the previous version:

Quick Rollback

cd /opt/aiadminpanel

# Stop the panel
docker compose stop panel

# Use the backup image
docker tag ghcr.io/aiadminpanel/ai-admin-panel:pre-upgrade-backup ghcr.io/aiadminpanel/ai-admin-panel:latest

# Restart
docker compose up -d panel

Database Rollback

If the new version ran a migration that broke something:

# Stop the panel
docker compose stop panel

# Restore from backup
docker exec -i aiadminpanel_postgresql psql -U aiadminpanel -d aiadminpanel < /opt/aiadminpanel/backup-pre-upgrade-YYYYMMDD.sql

# Start with the old version
docker compose up -d panel

Warning: Database rollbacks can cause data loss if new records were created after the upgrade. Only restore from backup as a last resort.

Upgrading Infrastructure

To upgrade the supporting services (PostgreSQL, Keycloak, Traefik):

PostgreSQL

# Back up first!
docker exec aiadminpanel_postgresql pg_dump -U aiadminpanel -d aiadminpanel > /opt/aiadminpanel/backup-pg.sql

# Update the image tag in docker-compose.yml, then:
docker compose pull postgresql
docker compose up -d postgresql

Keycloak

# Back up the Keycloak database
docker exec aiadminpanel_postgresql pg_dump -U aiadminpanel -d keycloak > /opt/aiadminpanel/backup-keycloak.sql

# Update the image tag in docker-compose.yml, then:
docker compose pull keycloak
docker compose up -d keycloak

Traefik

docker compose pull traefik
docker compose up -d traefik

Traefik upgrades are usually seamless — certificates and routes are preserved.

OpenBao (secrets manager)

OpenBao only patches its latest minor release line, so bump OPENBAO_VERSION promptly when a new minor ships. Always bump the panel's ExpectedOpenBaoMinor constant in the same change — that's what drives the version-mismatch warning on the Settings → Security → Secrets card, and an unbumped constant defeats the warning entirely. Take a volume backup first (rare storage-format changes are called out in OpenBao's release notes):

# Back up first — see docs/runbooks/openbao.md §2 in the repository for the full procedure
cd /opt/aiadminpanel
docker compose stop openbao
docker run --rm -v aiadminpanel_openbao_data:/data:ro -v aiadminpanel_openbao_logs:/logs:ro \
  -v /opt/aiadminpanel/backups:/backup alpine \
  tar czf /backup/openbao-data-$(date +%Y%m%d-%H%M).tar.gz -C / data logs
docker compose start openbao

# Update OPENBAO_VERSION in .env, then:
docker compose pull openbao
docker compose up -d --no-deps --force-recreate openbao

Confirm it came back healthy and unsealed before moving on:

docker exec aiadminpanel_openbao wget -q -O- http://127.0.0.1:8200/v1/sys/health | grep -q '"sealed":false'

Full backup/restore, unseal-key rotation, and bootstrap-recovery procedures live in docs/runbooks/openbao.md in the repository.

Uninstalling

Remove AI Admin Panel

To completely remove the panel and all data:

cd /opt/aiadminpanel

# Stop all containers
docker compose down

# Remove Docker volumes (THIS DELETES ALL DATA)
docker compose down -v

# Remove installation files (secrets live under /opt/aiadminpanel/secrets, so
# this already removes them)
rm -rf /opt/aiadminpanel
rm -rf /etc/aiadminpanel
rm -rf /var/log/aiadminpanel
# Legacy cleanup: pre-AI-397 installs kept secrets in the tmpfs /run/secrets
rm -f /run/secrets/master_key /run/secrets/db_password /run/secrets/keycloak_admin_password

Keep Data, Remove Panel

To stop the panel but preserve the database for later:

cd /opt/aiadminpanel

# Export data first
docker exec aiadminpanel_postgresql pg_dump -U aiadminpanel -d aiadminpanel > ~/aiadminpanel-backup.sql
docker exec aiadminpanel_postgresql pg_dump -U aiadminpanel -d keycloak > ~/keycloak-backup.sql

# Stop containers but keep volumes
docker compose down

# Remove application files (keeps Docker volumes)
rm -rf /opt/aiadminpanel /etc/aiadminpanel

The PostgreSQL data volume persists until you explicitly remove it with docker volume rm aiadminpanel_postgres_data.

Remove Docker (Optional)

If Docker was installed solely for AI Admin Panel:

systemctl stop docker
apt-get purge -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
rm -rf /var/lib/docker