AI AdminPanel Documentation

Upgrade & Uninstall

Before changing the installation

Record the running version and keep a restorable backup of the panel and Keycloak databases, application data, installation configuration, and secrets. A panel database dump alone does not cover service volumes, OpenBao, or its unseal material. See Backup and Restore and the repository runbook docs/runbooks/openbao.md. Review the target release notes and plan an interruption for all tenants using this panel.

In-product updates

Open Settings → Updates to compare the running version with the available release and read its notes. You can check now, select Stable or Beta, and pin the current version. Stable is the default. Viewing and configuring the channel or pin requires system.update; applying an update requires system.update.apply, which is Admin-only by default.

Update now

Confirm Update now to request an update. The installed host updater:

  1. Validates the target and takes a panel PostgreSQL pg_dump backup. A failed backup aborts the update. It retains the three most recent pre-update dumps under /opt/aiadminpanel/backups/.
  2. Checks the target image's signature against the official release pipeline. Verification failure aborts the update.
  3. Fetches the selected release's versioned Compose configuration when available, preserving the previous Compose file. Missing required host files must be supplied successfully or the update stops. Existing host files are preserved.
  4. Changes PANEL_VERSION in .env, pulls the image, and applies the Compose stack when configuration changed (otherwise recreating only the panel). It checks panel health through /healthz. Other box-specific .env settings are preserved.
  5. Attempts an image/configuration rollback if the health check fails. The pre-update database backup remains available for operator recovery.

A release without versioned Compose assets receives an image-only update. Check the result before assuming a host configuration change has been applied. The corrected versioned-asset lookup shipped in 2.12.3; an old /opt/aiadminpanel/aap-update.sh needs an operator-managed refresh. Updating the panel image does not replace that host script.

The panel writes an update request; aap-updater.path and aap-updater.service run the privileged work on the host. The UI result and updater log explain whether an update succeeded, failed, or rolled back. After success, sign in, check the reported version, and open a deployed application. A health response alone does not verify those journeys.

Automatic updates

Automatic updates are off by default. An administrator with system.update.apply can enable them and select a daily time and timezone. They use the same host updater and backup/signature/health-check path. Pinning prevents automatic updates; a release that rolled back is not retried automatically each night. Check the last run result and notifications after a scheduled update.

Manual image changes (advanced)

The installed Compose file selects ghcr.io/aiadminpanel/ai-admin-panel:${PANEL_VERSION:-latest}. latest follows released versions. An explicit version pins the image; an unreleased main image is a separate channel.

After recording the current tag, making backups, and selecting a compatible released target in /opt/aiadminpanel/.env, run from the installation directory:

cd /opt/aiadminpanel
docker compose pull panel
docker compose up -d --no-deps --force-recreate panel

These commands only change the panel container. They do not perform the host updater's backup, signature verification, Compose reconciliation, or automatic rollback. Database migrations run when the new panel starts. Preserve any installer-generated Compose overrides and verify login and application access.

After upgrading: check for image-supplied routing labels

Newer releases refuse to deploy an image that ships traefik.* or aiadminpanel.* labels, because Docker copies image labels onto containers and the proxy routes from them. The upgrade does not touch containers that are already running. A service created earlier from such an image keeps its labels, and any route they define, until you remove or rebuild it. The panel does not yet detect this for you.

To list affected services, run this on the host. It only reads; it prints one line per container and label, and nothing when the host is clean:

for c in $(docker ps -aq --filter label=aiadminpanel.managed=true); do
  name=$(docker inspect -f '{{.Name}}' "$c")
  docker image inspect -f '{{range $k, $v := .Config.Labels}}{{println $k}}{{end}}' \
    "$(docker inspect -f '{{.Image}}' "$c")" 2>/dev/null \
    | grep -iE '^(traefik|aiadminpanel)\.' | sed "s|^|${name#/}: |"
done

For every service it lists: rebuild or re-tag the image without those labels and redeploy, or remove the service. Redeploying, moving, rotating a secret on, or changing the subdomain of such a service is refused until the image is fixed; there is no override. The service keeps running in the meantime.

Recovery and rollback limits

An older image does not undo database migrations. Automatic rollback restores the previous image/configuration, not the database. If schema compatibility is uncertain, stop and plan a coordinated restore of the matching version, database, configuration, and secret material. Restoring an older database can lose writes made after the backup. Do not import a dump into a running database and assume it reverses a migration.

For an image-only rollback confirmed compatible with the current database, restore the recorded previous PANEL_VERSION, then recreate the panel with the manual commands above. Inspect the result and application behavior before reopening access.

Supporting services such as PostgreSQL, Keycloak, and OpenBao have their own upgrade and backup requirements. Do not change a database major version by simply replacing its image tag. Review the component's migration procedure and test recovery separately. OpenBao backup, restore, and unseal procedures are maintained in docs/runbooks/openbao.md in the repository.

Stop while preserving data

To stop the installation for later recovery, first disable automatic updates in Settings and wait for any running update to finish. Then stop its host updater units and Compose stack:

sudo systemctl disable --now aap-updater.path
sudo systemctl stop aap-updater.service
cd /opt/aiadminpanel
docker compose down

down without -v preserves named volumes. Keep /opt/aiadminpanel, its .env, Compose files, secrets/, certificates, and backups, plus any configuration under /etc/aiadminpanel. Removing those files can make retained volumes unusable. Independently deployed application containers and volumes need separate handling.

Permanent removal

Inventory all panel and application containers, volumes, host files, and backups before deleting anything. Confirm a tested off-server backup and explicit approval to destroy the intended installation. Stop it as above first.

docker compose down -v deletes the installed stack's declared named volumes and attached anonymous volumes. It does not mean every deployed application's container or data volume has been removed. Review those resources separately. Remove installation files and the aap-updater systemd units only after deciding which configuration, secrets, certificates, and backups must be retained; reload systemd after removing unit files.

Do not remove shared Docker storage to uninstall one panel: other applications may use the same Docker host.