Skip to main content

​
SafariDesk Update Guide

Use this page to update a self-hosted SafariDesk deployment. The safest update flow is:
  1. Read release notes.
  2. Back up the database and uploads.
  3. Pull the new code or images.
  4. Restart services.
  5. Run migrations.
  6. Collect static files.
  7. Run post-update commands.
  8. Verify the deployment.
Related pages:

​
Before Updating

Check the current image tag:
Check running containers:
Create a backup:
Confirm backup files exist:
Read the release notes for:
  • Database migrations
  • New environment variables
  • Removed environment variables
  • Frontend build changes
  • License changes
  • Manual post-update commands
  • Rollback warnings
Placeholder release notes link:

​
Update Using Published Images

Edit .env and set the target image tag:
Pull images:
Start the new containers:
Run migrations:
Collect static files:
Sync email templates:
Run health checks:
For production:

​
Update From Source

Use this flow when building local images from the monorepo source. Pull code:
Review changes to .env.example:
Build and restart:
Run migrations:
Collect static files:
Sync email templates:

​
Updating With the Production Override

If production uses docker-compose.prod.yml, include it consistently:
The helper scripts currently call plain docker compose. If your operational standard always uses extra Compose files, either run the direct commands manually or export COMPOSE_FILE before using scripts. Example:

​
Environment Variable Changes

When a release changes .env.example, update .env manually. Compare:
If diff is not available, inspect both files directly. Do not overwrite .env with .env.example; that can erase production secrets. Changes to backend variables usually require a restart:
Changes to VITE_* variables require a rebuilt frontend image because Vite bakes them into the frontend bundle. Local rebuild:
Published-image deployments need a newly published frontend image with the updated build args.

​
Database Migrations

Run migrations after the new backend image is running:
The helper script runs both:
If migrations fail:
  1. Stop and inspect the error.
  2. Do not repeatedly rerun destructive commands.
  3. Check database connectivity.
  4. Check the release notes for manual migration steps.
  5. Restore from backup if the database is left in a bad state.

​
Static Files

After an update, collect static files:
Or:
Nginx serves collected files from the staticfiles volume at:
If admin or API documentation assets 404 after update, run collectstatic again and restart Nginx:

​
Post-Update Verification

Check containers:
Check health:
Check logs:
Verify in the browser:
  • Login works.
  • Frontend loads without asset errors.
  • API calls succeed.
  • WebSockets connect.
  • Uploads display.
  • Email sending still works if configured.
  • Background jobs are processed.

​
Rollback

Rollback depends on whether the failed update ran database migrations. If migrations did not run:
  1. Set SAFARIDESK_IMAGE_TAG back to the previous tag.
  2. Pull images.
  3. Restart services.
If migrations did run:
  1. Review whether the migrations are backward-compatible.
  2. If they are not backward-compatible, restore the database backup from before the update.
  3. Restore uploads if the update changed uploaded file layout.
  4. Set SAFARIDESK_IMAGE_TAG to the previous version.
  5. Pull and restart.
Restore example:
See Backup and Restore.

​
Update Checklist

  • Release notes reviewed.
  • .env.example compared with .env.
  • Database and uploads backed up.
  • Target image tag selected.
  • Images pulled or rebuilt.
  • Services restarted.
  • pgvector install command run.
  • Migrations run.
  • Static files collected.
  • Email templates synced.
  • Health checks pass.
  • Frontend reaches API.
  • WebSockets work.
  • Uploads work.
  • Worker and beat are running.
  • Rollback path is known.