Updating

Copula supports UI-triggered self-update, plus a manual update path on the host. Database migrations run automatically on every update via the copula-migrate init job.

Self-update from the UI

The backend exposes a self-update API that the UI drives:

• GET /api/system/update/status — check whether an update is available and follow the run state.
• POST /api/system/update with body {"force": false} — start the update.

Availability check is digest-based: the backend compares the digest of the running container image against the registry's latest tag through the mounted /var/run/docker.sock. The SELF_UPDATE_IMAGE environment variable overrides the image reference used for this check.

Run states:

idle → pulling → migrating → recreating → restarting → completed / failed

Guard rails when force is false:

• 400 no_update_available — the running image already matches the registry digest.
• 409 active_jobs_running — pipeline jobs are in progress; the response payload lists the blocking jobs. Wait for them to finish or retry with force: true.

No automatic rollback

If the container swap fails, the previous container is left stopped under a renamed predecessor name. Recover it manually — see Troubleshooting.

Manual update

On the server, pull the new images and recreate the stack:

# Provisioned installation (wizard)
cd /root/copula
docker compose pull
docker compose up -d

# Manual installation (from the published image)
cd <directory with your docker-compose.yml>  # created during manual installation
docker compose pull
docker compose up -d

docker compose pull fetches the current njoy14/copula-api:latest image along with the rest of the stack images.

Database migrations apply automatically on every up through the copula-migrate init job, which runs before the backend starts.

INFO

The /var/run/docker.sock mount in the backend container is mandatory — self-update (and the cocoindex integration) do not work without it.