Self-hosting

Upgrading

Back up, upgrade release images, and restore a backup if you need to roll back.

Back up first

Pause sending and other application writes. Export data and file storage before upgrading, and save .env securely with the release's Compose files and image versions. Encryption keys in .env are needed to recover encrypted settings.

Run these commands in the installation directory. Keep the export container until its file has been copied to the host:

bash

docker compose run --name opensend-backup migrate export --include-file-storage --path /tmp/backup.zip
docker cp opensend-backup:/tmp/backup.zip ./backup.zip
docker rm opensend-backup

Do not add --rm to that export: /tmp/backup.zip is inside the container. Rehearse the restore against a separate installation before trusting the backup. A consistent whole-volume backup requires stopping writes and Convex before copying the volume.

Upgrade with the installer

From the parent of the installation directory:

bash

curl -fsSL https://opensend.cc/install.sh | sh -s -- upgrade --dir ./opensend

Use upgrade v0.1.0 or --version TAG to choose a release. The installer backs up .env and replaced Compose files, pulls images, recreates the one-shot migrate service, and waits for startup. migrate sets the backend environment and redeploys functions automatically. Secrets are preserved.

Upgrade a manual installation

Download the new release's compose.yaml, compose.caddy.yaml, and Caddyfile as in manual setup. Update OPENSEND_VERSION in .env to that release's image tag, and update any image overrides too. Then run:

bash

docker compose pull
docker compose up -d --wait

Use the backend digest in the release Compose file with the CLI in the matching migrate image. They are selected together per release; do not mix backend and migrate versions. The changed migrate image redeploys functions before the app starts. If reapplying the same image, run docker compose rm -f migrate before up to recreate the completed job.

For source installations, check out the intended release and run pnpm install --frozen-lockfile and pnpm setup; use .env.docker for Compose commands.

Validate and roll back

Check sign-in, teams, sending, webhooks, and file downloads before resuming traffic. Keep the backup until validation finishes. An older binary may not read an upgraded database. Rollback requires restoring the pre-upgrade backup into a separate volume with its saved secrets and compatible release images; changing an image tag alone is not a rollback. See restore a snapshot.