Updates

Update LearnHouse regularly to get the latest features, bug fixes, and security patches.

Updating LearnHouse

Use the built-in update command. It backs up your database, pulls the new image, migrates uploaded content to a persistent volume, restarts the stack, and applies database migrations.

# Update to the latest version
npx learnhouse update
 
# Update to a specific version
npx learnhouse update --to 1.4.2
# or using the short form:
npx learnhouse update -v 1.4.2

What update Does

The command runs these steps in order:

1. Database backup: pg_dump to ./backups/ (skipped with --no-backup)
2. Alembic baseline: stamps the current schema for installs that pre-date Alembic tracking (one-time, idempotent)
3. Image tag update: rewrites the tag in docker-compose.yml
4. Content volume migration: moves uploaded media into a named Docker volume so it survives future container recreations (one-time, idempotent)
5. Image pull: docker compose pull fetches the new image
6. Stack restart: docker compose down && docker compose up -d --pull always
7. Health wait: polls /api/v1/health until the app responds
8. Database migrations: alembic upgrade head (prompted unless --migrate/--no-migrate passed)

Recommended Update Procedure

# 1. Review the release notes
# https://github.com/learnhouse/learnhouse/releases
 
# 2. Run the update (backup is created automatically)
npx learnhouse update
 
# 3. Verify all services are healthy
npx learnhouse doctor
 
# 4. Check logs for any errors
npx learnhouse logs

Database Migrations

LearnHouse uses Alembic  to evolve the database schema between versions. After the new container starts, the CLI prompts:

? Run database migrations now? › Yes / No

• Yes: runs alembic upgrade head in the app container. Recommended.
• No: skips migrations. You can run them later manually.

To skip the prompt, pass --migrate (always run) or --no-migrate (always skip).

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

Installs Created Before v1.3

Early LearnHouse 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
npx 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: ghcr.io/learnhouse/app:<new> back to <old>)
 
# Restart on the old image
npx 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 npx learnhouse backup manually before updating.

Checking for Updates

The CLI automatically checks for a new version each time you run a command and prints a notice if one is available.

Review the LearnHouse release notes  before updating to understand what has changed. Some updates may include:

• New features or UI changes
• Database migrations (applied automatically when you accept the prompt or pass --migrate)
• Configuration changes that may require updating your .env file
• Breaking changes (rare, documented in release notes with a migration guide)