# Operations Guide

## Install

```bash
./install.sh
```

The installer is idempotent:

- existing `.env` is kept;
- existing Docker/Compose installation is reused;
- repeated loading of packaged ours RP, Prometheus and Grafana ARM64 images is safe;
- existing data directory is reused.

## Start

```bash
./start.sh
```

Start without waiting for the first snapshot:

```bash
./start.sh --no-wait-first-run
```

## Stop and Restart

```bash
./stop.sh
./restart.sh
```

## Status Checks

```bash
./status.sh
./self-check.sh
```

Important checks:

- Docker/Compose availability;
- runtime, Prometheus and Grafana images exist;
- `HOST_DATA_DIR` is writable;
- Compose config is valid;
- latest run status;
- metrics, Prometheus and Grafana endpoints.

`status.sh` also prints:

- `periodic_snapshot_reset`
- `periodic_snapshot_max_deltas`

## Upgrade

Extract the new package into a new directory and explicitly reuse the existing `.env` through the upgrade script:

```bash
./upgrade.sh --reuse-env-from /path/to/old-installer/.env
```

If the new package directory already has a `.env`, the upgrade script keeps it.

Upgrade does not delete:

- `runs/`
- `logs/`
- `state/rsync-mirror`
- runtime configuration referenced by `.env`
- Prometheus / Grafana data

To validate periodic forced snapshot behavior, temporarily set:

```bash
PERIODIC_SNAPSHOT_RESET=1
PERIODIC_SNAPSHOT_MAX_DELTAS=2
```

Then confirm the latest `run-meta.json` contains:

```bash
snapshot_reason=periodic_snapshot_delta_limit
```

And inspect the independent lifecycle state:

```bash
jq '{last_run,last_success_snapshot,successful_deltas_since_snapshot,state_health}' \
  "${HOST_DATA_DIR}/state/run-lifecycle-state.json"
```

After validation, restore:

```bash
PERIODIC_SNAPSHOT_MAX_DELTAS=100
```

## Cleanup

```bash
./cleanup.sh --keep-runs 100
./cleanup.sh --keep-runs 100 --execute
```

Cleanup is dry-run by default. Add `--execute` after reviewing the output.