# deploy/systemd

Systemd **user** units for clawstor.

## Units

| Unit | Purpose |
|---|---|
| `clawstor-cluster.service` | daemon (gossip + RPC + Prometheus + build cache). Not shipped here — deployed per-node from the fleet playbook. |
| `clawstor-fuse.service` | Phase 6 read-only FUSE mount at `~/clawstor-mount/`. Depends on `clawstor-cluster.service`. |
| `clawstor-dashboard.service` | HTTP dashboard on `:7700`. Serves the v2 SPA at `/v2/*` + `/api/v2/*`. See `docs/dashboard-v2.md`. |
| `clawstor-scrub.service` + `clawstor-scrub.timer` | Weekly (Sun 04:00) BLAKE3 verify every chunk against its manifest. Non-zero exit = integrity failure — surfaced by systemd status. |
| `clawstor-gc.service` + `clawstor-gc.timer` | Nightly (03:30) orphan-chunk sweep. Override ExecStart via drop-in to add `--evict-to-gb N` for size-cap fleets. Sequenced before the Sunday scrub so scrub reads a fresh layout. |
| `clawstor-ref-sweep.service` + `clawstor-ref-sweep.timer` | Nightly (03:15) Gitea live-refs poll + stale-fingerprint report. Set `GITEA_TOKEN` via a drop-in for private repos. Report-only (dry-run) — deletion is a follow-on. |
| `clawstor-snapshot-rotate.service` + `clawstor-snapshot-rotate.timer` | Daily (02:00) create `daily-YYYY-MM-DD` snapshot + prune snapshots older than `RETAIN_DAYS` (default 30). Only touches snapshots whose name matches `daily-*` — hand-created ones survive. |

## Install `clawstor-fuse.service` (Linux)

Prereqs: `libfuse3-dev` + `pkg-config` installed, `claw-fuse` binary built with
`cargo build --release --features fuse --bin claw-fuse`. Create the
mount directory once before enabling the unit — the unit no longer
does that itself (some Ubuntu builds refuse subsequent FUSE mounts
after an ExecStartPre chain touches the mount point):

```bash
mkdir -p ~/clawstor-mount
```

```bash
# 1. Copy the binary
cp target/release/claw-fuse ~/clawstor-deploy/claw-fuse

# 2. Install the unit
mkdir -p ~/.config/systemd/user
cp deploy/systemd/clawstor-fuse.service ~/.config/systemd/user/

# 3. Reload + enable
systemctl --user daemon-reload
systemctl --user enable --now clawstor-fuse.service

# 4. Verify
systemctl --user status clawstor-fuse.service
ls ~/clawstor-mount/     # blobs  snapshots  tags
```

Override the default paths with a drop-in:

```bash
systemctl --user edit clawstor-fuse.service
```

```ini
[Service]
Environment=CLAWSTOR_MOUNT=/mnt/clawstor
```

## Install `clawstor-scrub.timer`

```bash
cp deploy/systemd/clawstor-scrub.service ~/.config/systemd/user/
cp deploy/systemd/clawstor-scrub.timer  ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now clawstor-scrub.timer

# Verify:
systemctl --user list-timers clawstor-scrub.timer
# Run once manually to confirm the service works:
systemctl --user start clawstor-scrub.service
journalctl --user -u clawstor-scrub.service --since -5min
```