Upgrade Guide

This guide covers upgrading the AtlasAI Tenant Plane (TP) for self-hosted deployments (on-prem, BYOC, and Kubernetes). SaaS and Dedicated TP customers receive upgrades automatically — no action needed.

Before you upgrade

Every upgrade follows the same principles:

1. Check the release notes for the version you are upgrading to. Breaking changes, new required environment variables, and deprecated features are listed there.
2. Back up your database. AtlasAI runs database migrations on startup. These are one-way: once applied, they cannot be automatically reversed. A backup lets you restore if something goes wrong.
3. Plan a maintenance window if you cannot afford even the brief service interruption during container restart. Rolling updates in Kubernetes avoid downtime entirely.

Upgrade paths

Option 1: Online upgrade (Docker Compose)

Use this when your server has internet access and can pull images from the Docker registry.

Step 1: Check current version

cd /opt/atlasai
docker compose exec tenant-plane cat /app/.atlas-version
# Output: 1.2.2

Step 2: Run the upgrade script

AtlasAI provides an upgrade script that handles the full process automatically:

ATLAS_VERSION=1.3.0 bash scripts/upgrade-tp.sh

What the script does:

1. Verifies prerequisites (Docker, disk space)
2. Creates a database backup using pg_dump (if DB_URL is set)
3. Pulls the new image from the Docker registry
4. Updates the image tag in your docker-compose.yml
5. Restarts the service with the new image
6. Runs database migrations automatically
7. Polls the health endpoint for up to 90 seconds
8. If the health check fails, automatically rolls back to the previous version
9. Records the upgrade in .atlas-upgrade-history

Step 3: Verify

# Check health
curl -s http://localhost:3000/api/health | python3 -m json.tool
 
# Check version
docker compose exec tenant-plane cat /app/.atlas-version

Environment variables for the upgrade script

Option 2: Air-gapped upgrade (no internet)

Use this when your server cannot reach the internet. You transfer the Docker image as a file.

Step 1: Export the image on a connected machine

Run this on a machine that has internet access and Docker installed:

# Pull the new version
docker pull atlasai/tenant-plane:1.3.0
 
# Export to a compressed tar file
docker save atlasai/tenant-plane:1.3.0 | gzip > tenant-plane-1.3.0.tar.gz
 
# Verify the file
ls -lh tenant-plane-1.3.0.tar.gz
# Output: -rw-r--r-- 1 user user 1.2G Mar 26 10:00 tenant-plane-1.3.0.tar.gz

Step 2: Transfer the file to your server

# Using scp
scp tenant-plane-1.3.0.tar.gz admin@your-server:/opt/atlasai/
 
# Using rsync
rsync -avz --progress tenant-plane-1.3.0.tar.gz admin@your-server:/opt/atlasai/
 
# Using a USB drive or internal file server (air-gapped environments)
cp tenant-plane-1.3.0.tar.gz /media/usb/
# ... transfer to target machine ...

Step 3: Run the upgrade with the offline bundle

On the target server:

ATLAS_VERSION=1.3.0 \
OFFLINE_BUNDLE=/opt/atlasai/tenant-plane-1.3.0.tar.gz \
bash scripts/upgrade-tp.sh

The script detects the OFFLINE_BUNDLE variable and loads the image from file instead of pulling from the registry. All other steps (backup, migration, health check, auto-rollback) work exactly the same.

Step 4: Verify

# Check the image is loaded
docker images | grep tenant-plane
# Output: atlasai/tenant-plane   1.3.0   abc123def456   5 minutes ago   850MB
 
# Check health
curl -s http://localhost:3000/api/health

Option 3: Kubernetes / Helm rolling upgrade

For Kubernetes deployments, Helm handles the upgrade as a rolling update — old pods are terminated one at a time as new ones become healthy, resulting in zero downtime.

Step 1: Update the image tag

helm upgrade atlasai-tp deploy/helm/atlasai-tp \
  --set image.tag=1.3.0 \
  --namespace atlasai \
  --wait \
  --timeout 10m

Helm automatically:

• Updates the Deployment with the new image tag
• Performs a rolling update (keeps old pods running until new ones pass health checks)
• Applies any new ConfigMap or Secret values if you changed them
• Runs database migrations on the first new pod to start

Step 2: Monitor the rollout

# Watch pods being replaced
kubectl rollout status deployment/atlasai-tp -n atlasai
 
# See events
kubectl describe deployment/atlasai-tp -n atlasai

Step 3: Verify

# Check all pods are running the new version
kubectl get pods -n atlasai -l app=atlasai-tp -o jsonpath='{.items[*].spec.containers[0].image}'
# Output: atlasai/tenant-plane:1.3.0 atlasai/tenant-plane:1.3.0 atlasai/tenant-plane:1.3.0
 
# Check health through the service
kubectl exec -it -n atlasai deploy/atlasai-tp -- \
  wget -qO- http://localhost:3000/api/health

Upgrading with a values file change

If the new version requires new configuration:

# Edit your values file first
vim values-production.yaml
 
# Apply both the new image and new values
helm upgrade atlasai-tp deploy/helm/atlasai-tp \
  -f values-production.yaml \
  --namespace atlasai \
  --wait

What happens during upgrade: database migrations

When the upgraded Tenant Plane starts for the first time, it automatically runs any database migrations required by the new version. Migrations are:

• Idempotent — they can run multiple times safely. Running them again on an already-migrated database skips them without error.
• Additive — migrations only add tables, columns, or indexes. They never drop data. (Dropping deprecated columns happens separately and only after a major version transition.)
• Tracked — a schema_migrations table records which migrations have been applied. The upgrade knows exactly where to start.

You can also run migrations manually before or after the service restarts:

# Via the API (triggers migration on the running TP)
curl -X POST https://your-tenant-plane/api/db/migrate \
  -H "x-service-secret: $INTERNAL_SERVICE_SECRET"
 
# Via the versioned migration script (from the repo)
TENANT_PLANE_DATABASE_URL=postgresql://... npm run migrate:versioned:tenant

Upgrade schedule and release cadence

We recommend staying within 2 minor versions of the latest release for security and support reasons.

Post-upgrade checklist

After every upgrade, verify:

• Health endpoint returns "status": "ok"
• You can log in and access the Command Center
• The version shown in Settings → License matches the expected version
• Edge agents are still connected (check Settings → Edge Agents for last-seen timestamps)
• No error banners in the UI
• Existing incidents, runbooks, and dashboards are accessible

If any step fails, follow the Rollback Guide.