Upgrades and maintenance

Keeping the installation current and healthy.

Upgrading

  1. Take a database backup.
  2. Pull the new version: set ALBA_IMAGE in .env to the new release tag (for example ghcr.io/garth/alba:0.7.8, this release), or leave it unset to follow latest, and run docker compose pull.
  3. docker compose up -d. The migrate service runs the migrations once and exits, and the application container starts only after it has succeeded; migrations are additive and safe to run on a live database. If it fails, docker compose logs migrate shows why and the application container is not started on the new version.
  4. Check /health and the application log for errors.

On Kubernetes the same steps are a new migration Job with the new tag, then the Deployment set to it, as Installation describes.

People with Alba Ticket open do not need to be told to refresh. Their pages reconnect to the new version within a second or so and reload themselves to pick up its scripts and styles. A page where someone has typed something that is not saved yet, or has a dialog open, does not reload: it shows a bar at the top saying that Alba Ticket has been updated, with a Reload button for when they are ready.

Downgrading is not supported once a version's migrations have run; restore the backup instead. With several nodes, see the rolling upgrade notes in Clustering.

Notes for specific upgrades

  • Default workflow transitions. The Default workflow is now seeded with one transition into each status, each runnable from any status, so boards let a card move to any column. On start-up the seed replaces the old fixed path (Start progress, Send to review, Back to progress, Resolve, Reopen, Close) with the new set when the workflow still has exactly those transitions and nothing else; a Default workflow an administrator has changed is left as it is. Ticket history keeps its status changes; the link from those events to the deleted transitions is cleared, so they read as "changed the status".

Routine tasks

  • Storage sweep. Every hour the application removes upload slots that were never completed. Nothing to do.
  • Job history. Finished background jobs are pruned after a week.
  • Disk. Watch the database volume and the bucket. Attachments dominate.
  • Log. The container logs to standard output. Errors from background jobs, webhook processing and import runs appear there; import review items are also listed in Administration.

Command-line tasks

Inside the container, bin/alba gives access to the release:

docker compose exec app /app/bin/alba eval 'Alba.Release.grant_admin("you@example.com")'
docker compose exec app /app/bin/alba eval 'Alba.Release.seed()'
docker compose exec app /app/bin/alba remote     # an interactive shell on the running node

grant_admin makes an existing user an installation administrator, for example after the only administrator left. seed reinstalls the default vocabulary (statuses, workflow, ticket types, priorities, resolutions, link types and roles), which is idempotent.

Password resets and locked-out administrators

Administrators cannot see or set passwords. A person who cannot log in should use a login link, or an administrator can grant administrator rights to another account with grant_admin above.