Self-Update

Cleanmails can update itself from the admin dashboard or via the included update script. Updates download the latest release from S3, rebuild Docker images, and restart all services.

Update via Dashboard

From the admin panel: Admin → System → Check for Updates

The API endpoints for system updates (super_admin only):

# Check for updates
curl https://YOUR_SERVER/api/v1/admin/system/check-update \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

# Trigger update
curl -X POST https://YOUR_SERVER/api/v1/admin/system/update \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

# Get current version
curl https://YOUR_SERVER/api/v1/admin/system/version \
  -H "Cookie: auth_token=YOUR_JWT_TOKEN"

Update via Script

SSH into your server and run:

cd /opt/cleanmails
bash scripts/update.sh

The update script performs these steps:

1. Downloads the latest release tarball from S3
2. Backs up current binaries to /opt/cleanmails/backup/
3. Extracts new files over the existing installation
4. Rebuilds all Docker images (API, Worker, Frontend) with --no-cache
5. Restarts all services with --force-recreate --remove-orphans
6. Waits for the API health check to confirm successful startup
7. Cleans up the backup directory on success

Rollback

If an update fails, the previous binaries are preserved in /opt/cleanmails/backup/. To roll back:

cd /opt/cleanmails

# Restore previous binaries
cp backup/cleanmails-api bin/
cp backup/cleanmails-worker bin/

# Rebuild images with previous code
docker build -t cleanmails-api:latest -f Dockerfile.api .
docker build -t cleanmails-worker:latest -f Dockerfile.worker .

# Restart
docker compose -f docker-compose.prod.yml up -d --force-recreate

Update Frequency

Updates are released as new tarballs to the S3 bucket. There is no auto-update — you always initiate updates manually either from the dashboard or via the script.