Updates

Keeping ZəkaHouse up to date ensures you have the latest features, bug fixes, and security patches.

Updating ZəkaHouse

ZəkaHouse app images aren’t published to a container registry, so an update is two steps: build (or tag) the new app image on the host, then point the deployment at it with zeka-learnhouse update.

# 1. From an up-to-date clone of the repository, build the new app image
docker build -t zeka-learnhouse:1.4.2 .
 
# 2. Move the deployment to it
zeka-learnhouse update --to 1.4.2

update backs up your database, runs database migrations against the new image before it boots, and restarts the stack. It stops before changing anything if the target image doesn’t exist locally. See Commands → update for its flags and the exact sequence of steps.

The update command creates a database backup automatically before making any changes. The backup is saved to {installDir}/backups/db-pre-upgrade-{timestamp}.sql.gz.

Recommended Update Procedure

# 1. Check with your ZekaLab contact for what changed in this release
 
# 2. Build the new app image (see above), then run the update
zeka-learnhouse update --to <version>
 
# 3. Verify all services are healthy
zeka-learnhouse doctor
 
# 4. Check logs for any errors
zeka-learnhouse logs

Database Migrations

ZəkaHouse uses Alembic to evolve the database schema between versions. update applies migrations automatically: it stops the app, migrates the database with the new image, and only then starts it. If that fails, it switches back to the previous image and restarts it.

To skip migrations, pass --no-migrate.

If you skip migrations, the new version of the app may error until they are applied. Run them manually when ready:

docker compose exec learnhouse-app sh -c "cd /app/api && uv run alembic upgrade head"

Installs Created Before v1.3

Early ZəkaHouse installs created their schema via SQLAlchemy’s create_all without Alembic tracking. The update command detects this automatically and stamps the current schema as the baseline before running any delta migrations — so upgrade head applies only new changes instead of replaying everything.

Rolling Back

If an update causes issues, restore from the pre-upgrade backup:

# List available backups
ls {installDir}/backups/
 
# Restore the database
zeka-learnhouse restore backups/db-pre-upgrade-<timestamp>.sql.gz
 
# Revert the image tag in docker-compose.yml to the previous version
# (edit the file: change image: zeka-learnhouse:<new> back to zeka-learnhouse:<old>)
 
# Restart on the old image
zeka-learnhouse start

Backups are named db-pre-upgrade-{timestamp}.sql.gz when created by update, and learnhouse-backup-{timestamp}.tar.gz when created by the backup command. The pre-upgrade backup created by update includes only the database dump; to also preserve your .env, run zeka-learnhouse backup manually before updating.

Uploaded files stored on the filesystem (in the learnhouse_content_* Docker volume) are not included in the database backup. To back up uploaded files, use docker volume export or a volume-level snapshot provided by your hosting platform.

Finding Out About New Releases

The CLI doesn’t check for new versions on its own. Check with your ZekaLab contact for release notes before updating to understand what has changed. Some updates may include:

New features or UI changes
Database migrations (applied automatically by update)
Configuration changes that may require updating your .env file
Breaking changes (rare, documented in release notes with a migration guide)

PreviousTroubleshooting