Skip to main content

​
Docker Images and Releases

SafariDesk publishes two application Docker images for self-hosting:
The deployment also uses three upstream infrastructure images:
Related pages:

​
Image Count

SafariDesk has two custom application images. SafariDesk does not need separate images for channels, worker, or beat. Those services reuse the backend image.

​
Compose Image References

The root docker-compose.yml reads these variables:
Rendered image names:
Example production values:

​
Local Build vs Published Images

Use published images for normal self-hosting:
Build from local source when developing or testing unreleased changes:
Both modes use the same Compose file.

​
GitHub Actions Publishing

Docker Hub publishing is defined in:
The workflow builds:
  • safaridesk-frontend
  • safaridesk-backend
Required GitHub repository settings: Placeholder links:

​
Tagging Rules

The Docker workflow currently generates tags from:
  • Branch name
  • Git tag
  • Commit SHA with sha- prefix
  • latest on the default branch
Examples:
Production deployments should use version tags such as:
Avoid latest for production because it can change between deployments.

​
Release Workflow

GitHub releases are created by:
The workflow runs when a Git tag matching v* is pushed. Example:
The release should include:
  • Frontend changes
  • Backend changes
  • Database migration notes
  • Environment variable changes
  • Docker image tags
  • Upgrade steps
  • Rollback notes

​
Versioning Model

Use one SafariDesk version for the whole monorepo. Good:
Avoid separate frontend and backend versions for self-hosted releases. One version is easier to support because it keeps these aligned:
  • Frontend API expectations
  • Backend API behavior
  • WebSocket routes
  • Database migrations
  • Environment variable requirements
  • Documentation
  • Docker Compose examples

​
Build Locally Before Publishing

Validate the Compose file:
Build the images:
Start the stack:
Run migrations and static collection:
Run health checks:

​
Manual Docker Hub Publishing

Use the GitHub workflow for normal publishing. If manual publishing is needed:
Also publish latest only when the version should become the default:

​
Upgrade Image Tags

Update .env:
Pull and restart:
See Update Guide for the full process.

​
Rollback Image Tags

If a release must be rolled back:
  1. Stop traffic or put the site into maintenance mode if your infrastructure supports it.
  2. Restore the database if the failed release ran non-reversible migrations.
  3. Set SAFARIDESK_IMAGE_TAG back to the previous version.
  4. Pull and restart.
Example:
See Backup and Restore before attempting rollback across database migrations.

​
Release Checklist

  • Frontend build passes.
  • Backend checks pass.
  • Compose validation passes.
  • Docker images build.
  • Docker images push to Docker Hub.
  • Release tag exists.
  • Release notes include migrations.
  • Release notes include env var changes.
  • Installation docs still match Compose.
  • Update docs are tested from the previous release.
  • Rollback notes are included.