Upgrade and Rollback

Upgrade the backend and frontend together. Database migrations run at startup and are not reversible, so a pre-upgrade snapshot is your rollback boundary.

Before Upgrading

1. Read every release note between the current and target versions.
2. Confirm the target image tag exists for both rust-srec and rust-srec-frontend.
3. Download a configuration export and take a consistent backup of the database, configuration, output, .env, and Compose file.
4. Record the current image tags or digests and the result of health checks.
5. Schedule around active recordings and pipeline jobs. An interrupted media write may need manual inspection.

Docker Upgrade

Edit .env so VERSION is the reviewed target, for example:

VERSION=v0.5.1

Then run:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200 rust-srec
curl http://localhost:12555/api/health/live

After signing in, verify authenticated readiness, the System Health page, streamer count, recent sessions, one platform check, and a noncritical recording/pipeline. Keep the pre-upgrade backup until the observation period ends.

systemd Upgrade

Swap the binary in place and restart the unit. install replaces the file rather than writing into it, so the running process is unaffected until the restart:

install -D -m 0755 rust-srec /opt/rust-srec/rust-srec
systemctl restart rust-srec
systemctl status rust-srec
journalctl -u rust-srec --since "5 min ago"
curl http://localhost:12555/api/health/live

Reinstall rust-srec.service to /etc/systemd/system/ and run systemctl daemon-reload only when the release changes the unit itself; a release note says so when it does. Then repeat the same post-upgrade checks as the Docker path.

Automatic Updates (Watchtower)

Watchtower is part of the Docker deployment and does not apply to the systemd service, which is upgraded by hand as above.

The Compose file ships an optional watchtower service that pulls new images and recreates the containers automatically. It is off by default; enable it with:

docker compose --profile autoupdate up -d

Updates only happen while the system is idle. Before stopping a container, Watchtower runs its pre-update hook, which calls the unauthenticated GET /api/health/idle endpoint:

• 200 — nothing is recording or queued to record, and no pipeline job (upload, remux, danmaku conversion, ...) is processing. The update proceeds.
• 503 or no response — the hook exits with code 75 and Watchtower skips this cycle, retrying on the next poll (WATCHTOWER_POLL_INTERVAL, default 3600 seconds).

Pending pipeline jobs do not block an update; they are persisted and re-run after the restart. The frontend container carries the same gate, so both images move to the new version in the same cycle.

Caveats:

• Automatic updates require a mutable image tag: keep VERSION=latest (or dev). Pinned vX.Y.Z tags never receive updates.
• Database migrations still run at startup and are not reversible. Automatic updates skip the manual pre-upgrade snapshot, so keep scheduled backups (see Backup and Restore) and read release notes regularly. If an upgrade must be reviewed before rollout, stay on manual upgrades with a pinned tag.
• The idle check runs immediately before the container stops; a recording that starts in the few seconds in between is still interrupted.

Preset and Template Timestamps

Migration 20260907120000 normalizes created_at and updated_at in job_presets, pipeline_presets, and template_config to integer Unix milliseconds. Existing integers are preserved. Historical date strings are converted with their timezone, truncating submillisecond precision. API dates remain strings.

If startup reports Cannot normalize preset/template timestamps, one of these columns contains an invalid or unsupported historical value, such as an expanded-year date produced by an older timestamp decoding error. The migration rolls back and preserves the original values. Stop the backend, retain a database backup, inspect those six columns, and repair only values whose intended time can be established from the backup or other records. Restart to retry the migration. Do not replace unknown dates with the current time or edit a shipped migration.

Filter Timezone Compatibility

Migration 20260909120000 preserves existing TimeBased schedules by materializing "timezone":"local" where an object configuration omitted timezone or used null. Explicit zones, Cron rules, row identities and unrelated configuration members are preserved. Malformed/non-object JSON is left unchanged; the migration does not repair historical invalid configurations.

New omitted/null timezones mean UTC. Existing TimeBased editor updates that omit the member retain the stored zone; explicit null requests UTC. Backup exports now use schema 0.1.8 and explicit zones, while older TimeBased backup omissions import as local. See filter timezones.

Proxy settings

The first start of a version with saved proxies converts the proxy configured on global, platform, template and streamer settings into saved proxies under Settings → Proxies, and points each setting at its proxy. Take the pre-upgrade backup first: the conversion clears the old settings, and an earlier version cannot read the new ones. Check that the proxy environment variables the backend should see are set before that start. If HTTP_PROXY, HTTPS_PROXY or ALL_PROXY is set and the global proxy was turned off or empty, the global default becomes System proxy; otherwise it becomes Direct. A setting that could not be kept, such as a socks4 address, becomes Direct and is logged as a warning.

After starting, review Settings → Proxies and the Default proxy under Settings → Global → Network & System. Direct now also keeps FFmpeg and Streamlink off the environment's proxy. See upgrading from proxy settings for every rule.

Rollback

Do not start an older binary against a database already migrated by a newer release unless the release notes explicitly say it is compatible.

1. Stop both services.
2. Restore the pre-upgrade database and configuration snapshot.
3. Reset VERSION to the previous tag or image digest, or reinstall the previous binary over /opt/rust-srec/rust-srec.
4. Start both services and repeat the health and recording checks.

Any sessions or configuration created after the snapshot will be lost. If those changes matter, preserve the failed-upgrade data separately for forensic recovery rather than merging it directly into the restored database.

Source or Binary Installations

Keep the exact binary, frontend build, environment file, and database snapshot as one release unit. Build with --locked; do not combine an arbitrary frontend commit with a different backend release.