deployment

Updating

Pull the latest images and apply migrations.

Updating Glyph in production with docker-compose.prod.yml is two commands. Migrations run automatically on backend startup.

Standard update

cd /opt/glyph
 
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

pull fetches the latest :latest images from Docker Hub. up -d recreates only the containers whose images changed and starts them.

The backend runs alembic upgrade head on startup, applying any new migrations to the database.

Pinning a version

Using :latest is convenient but risky if a release is bad. To pin a version, edit docker-compose.prod.yml:

backend:
  image: rseize/glyph-backend:1.4.2  # was :latest
 
frontend:
  image: rseize/glyph-frontend:1.4.2  # was :latest

Then docker compose pull && up -d as usual.

Pinned versions are recommended for production. Watch the project's release notes for breaking changes before bumping.

Watching the update

docker compose -f docker-compose.prod.yml logs -f

Look for:

INFO: Application startup complete. (backend ready)
Migration output: Running upgrade <revision>
ready - started server on 0.0.0.0:3000 (frontend ready)

Browser sessions stay valid as long as SECRET_KEY hasn't changed - users won't be signed out.

Rolling back

If an update broke something:

# Edit docker-compose.prod.yml back to the previous version (e.g. :1.4.1)
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Database migrations are not auto-reverted. If the new version applied a migration that's incompatible with the old code, rolling back the image won't fix it. Restore the database from a backup taken before the update.

For this reason, always take a fresh backup before a major version bump.

Major version upgrades

Read the release notes for any version that crosses a major boundary (e.g. 1.x → 2.x). Look for:

Database migration warnings
.env variable changes
API breaking changes
Required manual steps

If unsure, take a backup, test in a staging environment, and only then update production.

Health check after update

docker compose -f docker-compose.prod.yml ps

All containers should be healthy. If backend shows unhealthy, check logs immediately:

docker compose -f docker-compose.prod.yml logs backend

Common post-update issues:

Missing new required .env variable → backend exits with a clear message
Migration failure → backend keeps restarting, the migration error is logged
Image pull failure → check internet access and Docker Hub availability

Update notifications

Glyph doesn't currently notify you of new releases. Watch the GitHub repository (Releases → Watch → Releases only) to get an email on each new version.

Future versions may include an in-app "update available" banner.

Backups

Troubleshooting