Upgrades & backups

HeliosLogs is a single binary with no external database, so upgrades are simple: replace the binary (or image) and restart. This page covers the upgrade flow, the automatic on-disk migrations, and what to back up.

Upgrading

1. Build or pull the new version.
2. Replace the binary / bump the image tag.
3. Restart serve.

No separate migration command is required — any on-disk format upgrades run automatically at startup (see below). For a cluster, upgrade nodes one at a time (rolling). Because cross-node visibility is eventual and the control plane is shared, a mixed-version window during a rolling upgrade is fine for routine releases; check release notes for any exceptions.

Automatic migrations

On startup HeliosLogs performs one-shot, idempotent storage migrations before opening the catalog:

• Env-aware layout — older partitions stored without an environment level are promoted into the data/<env>/<index>/<day>/ layout: ordinary user data moves under default, and reserved self-log indexes (_*) move under _system.
• Legacy index — an old top-level ./index/ directory (from very early demo builds) is moved into the new partition layout.

These are safe to re-run and log what they moved. If a migration can't complete (for example a permissions or destination-collision issue), HeliosLogs logs the error and continues rather than aborting — fix the issue and restart to retry.

What to back up

What	Where	Why
Secret files	secret-control.json, secret-jwt.json (or your HELIOS_*_PATH locations)	Losing the control key makes the control plane unrecoverable.
Control plane	<data-dir>/_control (single node) or the _control prefix in the shared store	Users, settings, dashboards, monitors, alerts, conversations.
Log data	<data-dir> partitions, or the shared store/bucket	Your actual events.

With a shared store, backing up is "replicate the bucket" (plus the secret files, which live outside it). With S3, enable bucket versioning and/or cross-region replication. See Multi-node & shared store.

Restore / disaster recovery

1. Restore (or fail over to) the replicated shared store / data directory.
2. Restore the secret files to their configured paths.
3. Start a node pointed at both. With a shared store, the local cache rebuilds from the shared manifests on first read.

Rollback

Rolling back the binary is generally safe for routine releases. The risk is a release that introduced a forward-only on-disk migration; in that case a backup of the pre-upgrade data/control plane is your safety net. Always read the release notes before downgrading, and keep a backup taken immediately before the upgrade.