Updates and Recovery

简体中文 | English

Update the Center

Upgrade from v0.1.1 to v0.1.2

Update the Center first, then the Agents. Before upgrading, stop the Center and back up ./data/config and ./data/history as one consistent set. Preserve /var/lib/ipchronicle-agent on each node. The Center applies new migrations while preserving the account, node identities, proxies, schedules, and history. The Agent-local state schema remains at version 9.

The new Compose files add ./data/logs:/var/lib/ipchronicle/logs. Add this mount to custom Compose files too, so logs survive container recreation. Cloudflare Tunnel deployments keep their matching Compose file and existing .env token.

After the configuration database migrates, switching directly to an older Center image is unsupported. To downgrade, stop the Center and restore the matching pre-upgrade backups before running the old version. Those backups do not contain data created after the upgrade.

Update Commands

Read the target version's release notes before updating. A standard deployment downloads a fresh compose.yaml:

curl --proto '=https' --tlsv1.2 -fL \
  "https://github.com/ipchronicle/ipchronicle/releases/latest/download/compose.yaml" \
  -o compose.yaml
docker compose pull
docker compose up -d

A Cloudflare Tunnel deployment uses its matching file:

curl --proto '=https' --tlsv1.2 -fL \
  "https://github.com/ipchronicle/ipchronicle/releases/latest/download/compose.cloudflare-tunnel.yaml" \
  -o compose.yaml
docker compose pull
docker compose up -d

Also review the latest default.env.example and add any newly required variables to the existing .env.

Current Data Boundary

v0.1.1 entered production use on 2026-09-04 and is the initial persisted-data compatibility baseline. Supported upgrades within the same major version must preserve an existing v0.1.1 deployment's ./data/config, ./data/history, and /var/lib/ipchronicle-agent on each node.

v0.1.1 does not migrate configuration, history, or Agent-local state from development builds, release candidates, or v0.1.0. When moving from one of those versions, deploy v0.1.1 with empty Center data directories and run the installer with --uninstall --purge before enrolling each old Agent again.

The Center applies migrations included in the target version before it starts serving. A Release that changes a persisted format documents its upgrade and rollback requirements. A rollback uses a data backup compatible with its target version.

Update Agents

Select the stable or RC release-discovery channel under Settings > System. This setting controls release discovery and does not automatically update the Center.

Under Nodes, select online nodes with an available version to request a batch update. Results are shown per node. Before atomic replacement, the Agent validates the platform, version, capabilities, manifest, size, and checksum. If the new Agent cannot start or report healthy, the root supervisor restores the previous binary and state checkpoint. Updates and complete probes share the node's one immediate-task slot.

Restore a Node after Reinstallation

Before reinstalling the host, copy its dedicated recovery installation command from the node's Settings. Run it as root after reinstallation to retain the same node and its Center configuration and history. Recovery immediately revokes the old Agent credentials. The recovery key remains valid until rotated in node settings; anyone holding the command can take over the node, so protect it as a credential.

Data not yet uploaded from the old disk requires a separate backup of Agent state. The Center cannot recover that data.

Backup Boundary

IPChronicle currently has no built-in backup or restore command. Stop the Center before copying SQLite databases, or use a snapshot mechanism that understands SQLite WAL state.

When Center data must be preserved, back up these directories as one consistent set:

• ./data/config: account, node identities, proxy and notification secrets, schedules, history generation, and master.key;
• ./data/history: address events, probe runs, snapshots, and history gaps.

Also preserve /var/lib/ipchronicle-agent on each node when host recovery must retain Agent identity and offline queues.

Clear History

Settings > History and storage > Clear observed history removes address events, probe runs, executions, snapshots, and history gaps. It preserves the account, nodes, public-IP settings, hidden paths, proxies, schedules, notification configuration, and pending task state. The operation advances the history generation so Agents discard data queued for the previous generation. It does not automatically start a complete probe.