Switch from docker-compose.yml to docker-compose.ghcr.yml
This guide moves an installation that has so far run with docker-compose.yml
(aion/* images built from the repository clone) to docker-compose.ghcr.yml
(prebuilt ghcr.io/aion-by-asa-computer/aion-* images from GitHub Container
Registry, GHCR), in the same folder and without losing data. It is meant
for the administrator or operator who manages the server. Once on GHCR, you can
install new releases with one command or with the "Update now" button in the
admin UI.
Summary of the steps: pick the image version (0), run pre-flight checks (1),
back up (2), take a "before" snapshot of the data (3), update .env (4), start
the new stack (5), verify (6), then make GHCR the default (7). Rollback is in
step 8.
Why no data is lost
- Both files declare
name: aion-agent, so the volumes always have the same names:aion-agent_aion_data,aion-agent_redis_data,aion-agent_caddy_data,aion-agent_caddy_config. The new stack attaches to the existing volumes. - The database (
/app/data/aion.db: chats, users, settings, encrypted credentials) lives in theaion_datavolume, with the sameAION_DB_URLin both files. - The bind mounts
./.env,./config,./mcp_servers,./data/sessions,./data/db_testare identical.
Only the images (the code) change. The differences you need to handle are covered in the steps below: MCP overlay, Alembic version/migrations, override file.
- Never run
docker compose down -von the real stack:-vdeletes the volumes. - Do not touch
AION_CREDENTIAL_ENCRYPTION_KEY,REDIS_PASSWORDorAION_CHAT_AUTH_SECRETin.env. - Run all commands in the same terminal (
exported variables only exist there) and from the root of the clone.
0. Working variables
cd /percorso/del/clone/AION_Agent
Choose the image version
Option A: latest published release (no local build). Images are pulled from
GHCR. This is the choice for production, and the only one that works with
automatic updates (install.sh upgrade, the "Update now" button).
With the gh CLI:
export AION_TARGET=$(gh release view --repo AION-by-ASA-Computer/AION_Agent --json tagName -q .tagName | sed 's/^v//') && echo "Release: $AION_TARGET"
Without gh (same call install.sh uses):
export AION_TARGET=$(curl -fsSL https://api.github.com/repos/AION-by-ASA-Computer/AION_Agent/releases/latest | python3 -c "import sys, json; print(json.load(sys.stdin)['tag_name'].lstrip('v'))") && echo "Release: $AION_TARGET"
For a specific release: export AION_TARGET=1.6.2 (without the v).
Option B: images built locally with the GHCR names
(bash ./scripts/install.sh --local or build_local_images), tag local.
Use it when the code in your clone is newer than the latest release.
export AION_TARGET=local
If the DB has already been migrated by code newer than the latest release (for
example by a start with local images, or with the default compose on an
unreleased branch), option A cannot be used until a release containing those
migrations is published. The check in step 1c detects this. In that case
use option B now and move to the release later (step 9).
Backup folder (outside the clone, with a timestamp):
export BK=~/aion-backups/pre-ghcr-$(date +%Y%m%d_%H%M%S) && mkdir -p "$BK" && echo "$BK"
Helper function for the new stack: it includes docker-compose.override.yml if
present (with -f, the override is no longer loaded automatically).
dcg() { if [ -f docker-compose.override.yml ]; then docker compose -f docker-compose.ghcr.yml -f docker-compose.override.yml "$@"; else docker compose -f docker-compose.ghcr.yml "$@"; fi; }
1. Pre-flight checks (old stack still running)
1a. Local code changes. With GHCR, src/, config_std/ and
mcp_servers_std/ are no longer mounted: the versions inside the image are
used. Uncommitted or unreleased changes stop having any effect.
git status --short src config_std mcp_servers_std
1b. Images available. For a release, pull first (the old stack keeps
running, so downtime is shorter); for local, the images must already exist.
[ "$AION_TARGET" != "local" ] && AION_VERSION=$AION_TARGET docker compose -f docker-compose.ghcr.yml pull
If the pull answers denied or unauthorized, the images require a GHCR login
(GitHub token with the read:packages scope):
docker login ghcr.io
for s in backend chat-ui admin-ui website; do docker image inspect ghcr.io/aion-by-asa-computer/aion-$s:$AION_TARGET >/dev/null 2>&1 && echo "ok aion-$s:$AION_TARGET" || echo "MANCA aion-$s:$AION_TARGET"; done
If any line says MANCA (missing), stop.
1c. Database compatibility (Alembic). The DB's current revision must be
known to the new image, otherwise the backend does not start. The revision is
read straight from the alembic_version table, because alembic current would
fail if the DB were already ahead of the old code.
REV=$(docker compose exec -T backend python -c "import sqlite3; print(sqlite3.connect('file:data/aion.db?mode=ro', uri=True).execute('select version_num from alembic_version').fetchone()[0])" 2>/dev/null); echo "Revision DB: $REV"
if [ -n "$REV" ] && docker run --rm --entrypoint alembic ghcr.io/aion-by-asa-computer/aion-backend:$AION_TARGET history 2>/dev/null | grep -q "$REV"; then echo "OK: la nuova immagine conosce $REV"; else echo "STOP: la nuova immagine NON conosce '$REV' (troppo vecchia o errore)"; fi
The command prints OK if the new image knows the revision, STOP otherwise.
On STOP do not continue: you need a newer version (if you chose option A,
switch to option B and see step 9). Do not rely on the healthcheck alone: if
migrations fail, the backend logs
ERROR … Errore durante le migrazioni Alembic but still becomes healthy,
running code that does not know the DB schema.
If the old stack's logs show
Can't locate revision identified by '<rev>', the DB has already been migrated
by a newer image (for example a previous start of the GHCR compose) and the old
code is running on a schema it does not know. This is not data loss: switching
to an image that knows that revision (the OK check above) brings code and DB
back in line.
docker compose logs backend | grep -iE "alembic|migrat" | tail -5
2. Backup
2a. Logical backup (stack running), then copied into the backup folder:
docker compose exec backend python scripts/aion_backup.py --output /app/data/_backups
mkdir -p "$BK/backup-logico" && docker compose cp backend:/app/data/_backups/. "$BK/backup-logico/"
2b. Stop the old stack. Without -v.
docker compose down
2c. Volume backup (with the stack stopped, so the SQLite copy is consistent):
for v in aion_data redis_data caddy_data caddy_config; do docker run --rm -v aion-agent_$v:/v:ro -v "$BK:/b" alpine tar -czpf /b/$v.tar.gz -C /v . && echo "ok $v"; done
2d. Backup of host files (.env included; it contains secrets, so keep the
folder safe):
tar -czpf "$BK/host-files.tar.gz" .env config mcp_servers data/sessions data/db_test $( [ -f docker-compose.override.yml ] && echo docker-compose.override.yml ) && echo ok
git rev-parse HEAD > "$BK/git-commit.txt" && docker images --format '{{.Repository}}:{{.Tag}} {{.ID}}' | grep '^aion/' > "$BK/old-images.txt"
2e. Check the backup.
ls -lh "$BK" && tar -tzf "$BK/aion_data.tar.gz" | grep -E '^\./aion\.db$' && echo "DB presente nel backup"
3. "Before" snapshot of the data
A script that counts the rows of every table in the DB (the SQLite URI is passed as an argument):
cat > "$BK/count.py" <<'EOF'
# Counts the rows of every table in the AION DB: used to compare before/after the switch.
import sqlite3, sys
c = sqlite3.connect(sys.argv[1], uri=True)
for (t,) in c.execute("select name from sqlite_master where type='table' and name not like 'sqlite_%' order by 1"):
try:
print(t, c.execute(f'select count(*) from "{t}"').fetchone()[0])
except Exception as e:
print(t, "ERR", e)
EOF
Count on the volume (stack stopped), using the old image:
docker run --rm -i --entrypoint python -v aion-agent_aion_data:/d:ro aion/backend:latest - "file:/d/aion.db?immutable=1" < "$BK/count.py" > "$BK/before.txt" && wc -l "$BK/before.txt"
4. Update .env
Set the keys without opening the file: existing lines with the same key are removed and rewritten at the end; commented lines are kept.
AION_VERSION: tag of the GHCR images (must be explicit, notlatest).AION_MCP_REGISTRY_LOCAL_PATH: keeps the MCP overlay where it was (./config/mcp_registry.local.yaml). The GHCR compose default would point to/app/data/…, and the MCP servers added by the admin would seem to have disappeared.
[ -n "$(tail -c1 .env)" ] && echo >> .env; for kv in "AION_VERSION=$AION_TARGET" "AION_MCP_REGISTRY_LOCAL_PATH=/app/config/mcp_registry.local.yaml"; do k=${kv%%=*}; sed -i '' "/^${k}=/d" .env; echo "$kv" >> .env; done
grep -E '^(AION_VERSION|AION_MCP_REGISTRY_LOCAL_PATH)=' .env
sed -i '' is the macOS syntax; on Linux use sed -i.
Sandbox image (optional, recommended with option A). The sandbox stays on
aion/sandbox:latest, built from the clone, until you point it to the GHCR
image. It does not touch data, so you can also do it later. The image must be
available in Podman, not in Docker.
Option A (release):
podman pull ghcr.io/aion-by-asa-computer/aion-sandbox:$AION_TARGET
Option B (local, copied from Docker to Podman):
docker save ghcr.io/aion-by-asa-computer/aion-sandbox:local | podman load
Then in .env:
k=AION_SANDBOX_CONTAINER_IMAGE; sed -i '' "/^${k}=/d" .env; echo "$k=ghcr.io/aion-by-asa-computer/aion-sandbox:$AION_TARGET" >> .env
5. Start with docker-compose.ghcr.yml
dcg up -d
Wait until backend is healthy (up to about 2 minutes on the first start,
because migrations run at boot):
dcg ps
dcg logs backend | grep -iE 'alembic|migrat|aion-entrypoint|error|traceback'
6. Verify
6a. DB revision matches the new image:
dcg exec backend alembic current
6b. Compare the data (read-only access to the live DB):
dcg exec -T backend python - "file:/app/data/aion.db?mode=ro" < "$BK/count.py" > "$BK/after.txt" && diff "$BK/before.txt" "$BK/after.txt" && echo "Nessuna differenza"
Expected result: no existing table has fewer rows. New tables (from
migrations) and changes in the internal FTS tables (*_data, *_idx,
*_docsize, *_config) are normal.
6c. Checks in the UI (http://localhost or https://<DOMAIN>):
- log in with an existing user
- chat history in the sidebar; open an old conversation
- profiles and projects
- admin-ui → custom MCP servers are present
- admin-ui → LLM providers: sending a message works (confirms the encryption key is correct)
- channels (Telegram/WhatsApp), if configured
7. After the switch
Always use the GHCR compose. A docker compose up -d --build with the
default file would bring the stack back to the aion/* images. To make GHCR the
default for this folder, add COMPOSE_FILE to .env (including the override
only if the file exists):
echo "COMPOSE_FILE=docker-compose.ghcr.yml$( [ -f docker-compose.override.yml ] && echo :docker-compose.override.yml )" >> .env
From then on, docker compose ps/logs/exec/up use GHCR. Note:
scripts/install.sh always uses only -f docker-compose.ghcr.yml, so the
override is not applied during automatic upgrades.
Later updates (option A only). With AION_VERSION=X.Y.Z, new releases are
installed with the script, which takes a backup, pulls the images and runs
migrations one hop at a time:
bash scripts/install.sh upgrade
With AION_VERSION=local, upgrades are not supported, except in hybrid mode:
see Update from the admin UI and step 9.
"Update now" button in the admin UI (optional, option A only). It needs the
updater sidecar, enabled by COMPOSE_PROFILES=updater and the AION_HOST_*
keys. install.sh upgrade writes them on its own, but only when there really is
an update: if you are already on the latest release it exits early. In that case
add them like this (only the missing ones; AION_HOST_DOCKER_GID=0 is right for
Docker Desktop on macOS, on Linux use stat -L -c %g /var/run/docker.sock):
add() { grep -q "^$1=" .env || echo "$1=$2" >> .env; }; add AION_HOST_INSTALL_DIR "$PWD"; add AION_HOST_HOME "$HOME"; add AION_HOST_UID "$(id -u)"; add AION_HOST_GID "$(id -g)"; add AION_HOST_DOCKER_GID 0; add AION_UPDATER_TOKEN "$(openssl rand -hex 32)"; add COMPOSE_PROFILES updater
dcg up -d updater && dcg ps updater
Cleanup (only after a few weeks without problems):
docker volume rm aion-agent_uv_cache
docker image rm aion/backend:latest aion/chat-ui:latest aion/admin-ui:latest aion/website:latest
8. Rollback
Migrations applied by the new image can make the DB incompatible with the old code, so a rollback always restores the volumes from the backup.
Chats created after the switch are lost on rollback.
In the same terminal (you need $BK and dcg; in a new terminal, set BK
again to the backup folder path and redefine dcg):
dcg down
for v in aion_data redis_data caddy_data caddy_config; do docker run --rm -v aion-agent_$v:/v -v "$BK:/b:ro" alpine sh -c "find /v -mindepth 1 -delete && tar -xzpf /b/$v.tar.gz -C /v" && echo "ripristinato $v"; done
tar -xzpf "$BK/host-files.tar.gz" && echo "file host ripristinati"
docker compose -f docker-compose.yml up -d
Restoring host-files.tar.gz also brings back the original .env (without
AION_VERSION, COMPOSE_FILE, etc.). The aion/* images are still available
locally (listed in $BK/old-images.txt), so there is no need to rebuild.
9. From local to the latest release (later on)
If you switched with option B because the DB was ahead of the latest release, move to a release as soon as one ships with the same migrations. The data stays in the volumes; only the tag changes.
Define the step 0 variables again (option A for AION_TARGET) and dcg, then:
docker pull ghcr.io/aion-by-asa-computer/aion-backend:$AION_TARGET
REV=$(dcg exec -T backend python -c "import sqlite3; print(sqlite3.connect('file:data/aion.db?mode=ro', uri=True).execute('select version_num from alembic_version').fetchone()[0])" 2>/dev/null); if [ -n "$REV" ] && docker run --rm --entrypoint alembic ghcr.io/aion-by-asa-computer/aion-backend:$AION_TARGET history 2>/dev/null | grep -q "$REV"; then echo "OK: la release $AION_TARGET conosce $REV"; else echo "STOP: la release $AION_TARGET non conosce '$REV', aspetta la prossima"; fi
OK means the release knows the DB revision; STOP means it does not yet, so
wait for the next release.
Only on OK: back up as in step 2 (with dcg down instead of
docker compose down), then:
k=AION_VERSION; sed -i '' "/^${k}=/d" .env; echo "$k=$AION_TARGET" >> .env
dcg pull && dcg up -d && dcg logs backend | grep -iE 'alembic|migrat|error'
If you had set up the GHCR sandbox, also update AION_SANDBOX_CONTAINER_IMAGE
and run podman pull as in step 4. From here on, updates go through
install.sh upgrade or the admin UI button (step 7).