Upgrade & Uninstall

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:

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

Save the current binary (for rollback):

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

Check the changelog for breaking changes at https://docs.aiadminpanel.net.

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/panel:pre-upgrade-backup ghcr.io/aiadminpanel/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.

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
rm -rf /opt/aiadminpanel
rm -rf /etc/aiadminpanel
rm -rf /var/log/aiadminpanel
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