Migrate Docker Compose stack

Use this guide when upgrading an existing Annolive on-prem Docker Compose installation from version 08.06.26 or earlier to the latest deployment package.

This covers configuration and stack changes. For routine image updates on an already migrated stack, see Upgrade in the installation guide.

Before you begin

Back up your installation. Follow Backup and Restore and archive /opt/annolive/ before changing compose or nginx files.
Plan a short maintenance window. The stack will restart; backend and worker wait for the one-shot init service on every up.
Do not re-run setup.py. It is for fresh installs only. Upgrades use the automatic init service (init.py: collectstatic + migrate).

Your current stack (≤ 08.06.26)

Typical client installations on version 08.06.26 or earlier look like this:

Characteristic	Current (≤ 08.06.26)	Latest stack
Frontend host port	`8558:3000` published on `frontend`	No frontend host port — UI via nginx on 8558
Nginx host ports	`8559:8559` only (API)	`8558:8558` (UI) and `8559:8559` (API)
`nginx.conf`	API on port 8559 only	UI on 8558 + API on 8559
`.env` URLs	May be missing	`FRONTEND_URL` and `BACKEND_URL` required

User-facing URLs stay the same after migration: UI at http://<host>:8558, API at http://<host>:8559.

What changed in the latest stack

Frontend via nginx — the UI is no longer published directly on 8558:3000; nginx proxies port 8558 to the frontend container.
FRONTEND_URL and BACKEND_URL — required in .env so the UI can resolve the API URL at login.
Domain template — if you later move to hostname access, use nginx-domains.example.conf (see Custom domain access in the installation guide).

The init service, annoliveai/annolive:latest images, and PostgreSQL health checks are unchanged from the 08.06.26 stack.

Migration steps

1. Pull latest images

docker login -u annoliveai
docker pull annoliveai/annolive:latest
docker pull annoliveai/model-server:latest

2. Back up and copy new package files

cd /opt/annolive
sudo cp docker-compose.yml docker-compose.yml.bak
sudo cp nginx.conf nginx.conf.bak
sudo cp .env .env.bak

# Copy the new deployment package files:
sudo cp -a /home/ubuntu/annolive-docker-compose-package/. /opt/annolive/

3. Replace `.env` with the new template

Instead of updating your old .env, copy the latest .env.example from the deployment package and use it as your new .env:

sudo cp .env.example .env

Important:

Open your old .env.bak and copy your admin/organization details (such as DOMAIN_NAME, ADMIN_EMAIL, LICENSE_KEY, COMPOSE_PROJECT_NAME, and any other custom or sensitive settings) into the new .env.
Do not change your existing admin, license, or organization information—only update or fill out new required variables, such as FRONTEND_URL and BACKEND_URL, to match what users open in the browser:
```
FRONTEND_URL="http://<host-ip-or-dns>:8558"
BACKEND_URL="http://<host-ip-or-dns>:8559"
```
You can also remove DJANGO_SETTINGS_MODULE from your .env, as it is no longer required in the new stack.
Ensure all other required variables in .env.example are set appropriately for your deployment.

This approach ensures you have all new required variables, while retaining your original organization and admin settings.

4. Apply the new stack

cd /opt/annolive
docker compose -f docker-compose.yml up -d

Wait for init to complete:

docker compose -f docker-compose.yml logs init
docker compose -f docker-compose.yml ps

5. Verify

Confirm the migration before removing any backup files created in step 2.

Service health

docker compose -f /opt/annolive/docker-compose.yml ps
docker compose -f /opt/annolive/docker-compose.yml logs init --tail 20

All services should be Up (or Exited for init after success).

Application checks

Open http://<host-ip>:8558 in a browser and log in with your existing admin credentials.
Confirm existing organisations, projects, and data are present.
Run a quick smoke test (create or open a task, upload or view media if you use those features).

Do not proceed to cleanup until all checks pass. If anything fails, use Rollback below.

6. Clean up old files (after verification only)

Once you have strictly verified the migration, remove the local .bak files created in step 2:

sudo rm -f /opt/annolive/docker-compose.yml.bak \
           /opt/annolive/nginx.conf.bak \
           /opt/annolive/.env.bak \
           /opt/annolive/nginx.podman.conf

If you extracted the deployment package on the host, you can also remove it:

rm -rf ~/annolive-docker-compose-package
rm -f ~/annolive-docker-compose-package.tar.gz

caution

Keep your full archive from Backup and Restore (for example ~/annolive_backup_data.tgz) until you are satisfied the migration is stable in production. Do not delete that tarball as part of this cleanup.

Custom domain access (optional next step)

After a successful migration, you can expose Annolive by hostname (for example app.example.com and api.example.com) instead of <host-ip>:8558 / :8559. Use the bundled nginx reverse proxy — do not run a separate nginx on the host.

Copy nginx-domains.example.conf from the deployment package to /opt/annolive/nginx.conf.
Follow Custom domain access in the installation guide:
- HTTP setup — serve UI and API on port 80
- HTTPS setup — TLS on port 443 with HTTP redirected to HTTPS

Update FRONTEND_URL and BACKEND_URL in .env to match the hostnames and scheme users open in the browser.

FRONTEND_URL or BACKEND_URL is missing or does not match the browser URL. Update .env and restart:

docker compose -f /opt/annolive/docker-compose.yml up -d frontend backend nginx

`init` service fails

Check logs:

docker compose -f /opt/annolive/docker-compose.yml logs init

Common causes: database not ready, disk full, or migration conflict. Resolve the error and run docker compose up -d again.

Port 8558 connection refused after migration

The UI is now served by nginx on port 8558, not the frontend container directly. Confirm nginx publishes 8558:8558 and that the new nginx.conf includes the UI server block.

nginx crash loop (`host not found in upstream "frontend"`)

Start or recreate nginx after frontend is running:

docker compose -f /opt/annolive/docker-compose.yml up -d frontend backend
docker compose -f /opt/annolive/docker-compose.yml up -d nginx

Rollback

If migration fails, restore from backup:

docker compose -f /opt/annolive/docker-compose.yml down
sudo rm -rf /opt/annolive/
sudo mkdir -p /opt/annolive/
sudo tar -xzf ~/annolive_backup_data.tgz -C /opt/annolive
sudo chown -R 1000:1000 /opt/annolive
docker compose -f /opt/annolive/docker-compose.yml up -d

Or restore only the backed-up compose and nginx files:

sudo cp /opt/annolive/docker-compose.yml.bak /opt/annolive/docker-compose.yml
sudo cp /opt/annolive/nginx.conf.bak /opt/annolive/nginx.conf
sudo cp /opt/annolive/.env.bak /opt/annolive/.env
docker compose -f /opt/annolive/docker-compose.yml up -d

Ongoing upgrades after migration

Once on the latest stack, routine upgrades are:

docker compose -f /opt/annolive/docker-compose.yml pull
docker compose -f /opt/annolive/docker-compose.yml up -d

Each up re-runs init. Do not re-run setup.py.

Before you begin​

Your current stack (≤ 08.06.26)​

What changed in the latest stack​

Migration steps​

1. Pull latest images​

2. Back up and copy new package files​

3. Replace .env with the new template​

4. Apply the new stack​

5. Verify​

6. Clean up old files (after verification only)​

Custom domain access (optional next step)​

Unable to resolve API URL on login​

init service fails​

Port 8558 connection refused after migration​

nginx crash loop (host not found in upstream "frontend")​

Rollback​

Ongoing upgrades after migration​