Updates and migrations

Before updating

Read the chosen release notes, record the current image tag/source SHA and take a coordinated backup. Include image storage because migrations can change file layout as well as database schema.

The supplied production Compose file uses ${ZUKAN_TAG:-latest} for both API and worker and postgres:17 for the database. latest moves; the PostgreSQL major tag can also receive minor updates. Pin actual published tags/digests when repeatability is required.

Prebuilt application images

Set the desired published ZUKAN_TAG in .env, then:

docker compose pull
docker compose up -d
docker compose logs --tail=100 api
docker compose logs --tail=100 worker

Keep API and worker on the same version. The API command applies alembic upgrade head before serving requests. If migration fails, diagnose it before starting ad-hoc older/newer containers against that database.

docker compose pull includes the database service. Plan PostgreSQL image changes separately if minor-version behavior matters to your operations.

Source builds

Update to the chosen source revision after preserving local deployment edits, then:

docker compose -f docker-compose-dev.yml up -d --build

That stack uses project zukan-dev and data-dev, not production's data. It can still conflict on the same published port unless changed.

Catalog upgrades

A provider's catalog-version bump can make a full catalog sync due immediately. Expect temporary load and possible load-triggered maintenance after an upgrade even when your ordinary catalog interval has not elapsed.

Verification

Check /api/health, web login, a representative card page, personal quantities, custom images and worker jobs. Test Android connectivity when authentication or API behavior changed. Application and Android release numbering are independent.

Rollback

An older container tag does not automatically reverse schema changes or file moves. The safest general rollback is the prior application version with its coordinated pre-upgrade database/image/configuration backup restored into a compatible deployment. Preserve the failed upgraded state before replacing it if diagnosis matters.

PostgreSQL major upgrades are separate database migrations. Do not point a new major-version image at an old data directory and assume it will upgrade it. Follow the selected PostgreSQL upgrade method and validate it on a copy first.

Implementation references

• Dockerfile
• docker-compose.yml
• backend/alembic
• backend/app/services/schedule.py