nodemaster/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

NodeMaster is a beego v2 REST API (Go module `nodemaster`) for managing a single Docker/Podman host ("the node"), a registry of remote NodeMaster nodes, and the compose-based services running on the local node — including a scheduled/on-demand backup system for both the node and individual services.

## Commands

```bash
go build ./...              # build
go vet ./...                # vet
gofmt -l .                  # list files needing formatting (gofmt -w to fix)
go test ./...                # run all tests
go test ./tests/ -run TestGetNode   # run a single test
go run . scan [folder] [--json]     # CLI: scan compose folders, don't start the HTTP server
go run . info                       # CLI: print node summary, don't start the HTTP server
go run .                            # start the HTTP API (beego.Run(), port from conf/app.conf)
bee run -gendoc=true -downdoc=true  # dev server: rebuild-on-change + regenerate swagger/swagger.json on every save
bee generate routers                # regenerate routers/commentsRouter.go from @router annotations (run after adding/changing any controller method)
```

Swagger UI is served at `/swagger` when `runmode = dev` (see `conf/app.conf`). The spec files `swagger/swagger.json` / `swagger/swagger.yml` and `routers/commentsRouter.go` are all **generated** — never hand-edit them. Run `bee run -gendoc=true -downdoc=true` for day-to-day dev (it rebuilds and regenerates the swagger spec on every file change, and downloads the swagger UI static assets via `-downdoc` if `swagger/index.html` is missing); after adding, removing, or changing any controller method's `@router` annotation, also run `bee generate routers` to regenerate `routers/commentsRouter.go` (see routing note below). Two pre-existing `@Success`/`@Param` annotations reference types `bee generate docs` can't resolve (a package-local unexported struct `nodeServices` in `controllers/nodes.go`, and the pseudo-type `object` in `controllers/node.go`'s scan endpoint) — this prints a harmless `Cannot find the object: ...` warning and generates a placeholder empty-object schema for those two entries; it does not affect generation success or the routes themselves.

There is no README and no lint config beyond `go vet`/`gofmt`.

## Architecture

**Config persistence (`models/store.go`):** the entire application state — local node info, remote node registry, and services — is one `AppConfig` struct, serialized as JSON to `/etc/nodemaster/nodemaster.conf` (falls back to `~/.nodemaster.conf` if that path isn't writable). A single package-level `sync.RWMutex` (`mu`) guards the in-memory `cfg *AppConfig`. Every mutating function calls `persist()` to write the JSON back out. Because the config can hold a restic repository password (see below), `persist()` writes/chmods the file `0600`.

**API namespaces (all under `/v1`, wired in `routers/router.go`):**
- `/node` — the local host: info, update history, backup config/targets/run, compose scan
- `/nodes` — remote node registry, plus `GET /nodes/aggregated` which calls each registered node's own `/v1/services` over HTTP and merges the results
- `/services` — compose-based services on the local node: CRUD, start/stop, backup config/targets/run

**Critical routing gotcha:** beego's `NSInclude` resolves controller routes from `beego.GlobalControllerRouter`, which is populated by `routers/commentsRouter.go` — a **generated** file, rebuilt by `bee generate routers` (with no flags: this project's `ctrlDir`/`routersFile` match bee v2's defaults, `controllers` and `routers/commentsRouter.go`). If you add, remove, or change a controller method's `@router` annotation, you must run `bee generate routers` afterwards, or the route will silently 404 (it won't error at startup — it just won't be registered). Never hand-edit `commentsRouter.go`; a plain rerun of `bee generate routers` overwrites it in place from the current `@router` comments. (Historically this file was hand-maintained under the name `commentsRouter_controllers.go` after `bee generate routers` seemed unreliable — the actual issue was just that the default bee output path is `routers/commentsRouter.go`, not `commentsRouter_controllers.go`; running the generator with that stale filename created a second, duplicate router file instead of updating the existing one. Regenerating at the correct default path resolved it.)

**Backup execution (`models/backup.go`):** three methods — `MethodRsync`, `MethodRestic`, `MethodExternal` (no `rclone`; it was removed in favor of restic). `BackupTarget.Remote` is overloaded by method: an rsync destination (`user@host:/path`) or a restic repository string (`/mnt/backup/repo`, `s3:...`, `sftp:...`, etc.); `BackupTarget.Params` becomes extra `--key=value` CLI flags for whichever tool runs. `MethodExternal` is a no-op (the operator manages that backup outside the API). Restic's repository password is **node-global, not per-target**: `NodeInfo.ResticPassword`, read via `models.GetResticPassword()`, set through `PUT /v1/node`'s `restic_password` field (never echoed back — `GET /v1/node` only exposes `restic_password_set: bool`). It's passed to the `restic` binary via `RESTIC_PASSWORD`/`RESTIC_REPOSITORY` env vars, never argv. `runTarget` calls `ensureResticRepo()` (runs `restic init`, tolerates "already initialized") before every restic backup rather than tracking init state separately.

**Backup targets are individually CRUD-able**, not just a whole-`BackupConfig` replace: `/v1/node/backup/targets[...]` and `/v1/services/:id/backup/targets[...]`, each with `:tid` sub-routes for get/put/delete/run/progress, plus a `.../backup/progress` aggregate view. `BackupTarget.Schedule` is a 5-field standard cron expression (empty = manual-only). Validated centrally in `validateBackupTarget` (`models/backup.go`) — this is the single place that knows the set of valid `BackupMethod` values and schedule syntax.

**Scheduling (`models/scheduler.go`):** an in-process `robfig/cron/v3` scheduler. `StartScheduler()` is called once from `main.go`, only on the normal HTTP-server path (not on the `scan`/`info` CLI paths). `SyncSchedule()` fully tears down and rebuilds every cron entry from the current target definitions in `cfg`, and must be called after *any* mutation that can change `Targets` — not just the per-target CRUD endpoints, but also whole-object replace paths (`UpdateNodeBackupConfig`, `AddService`, `UpdateService`, `DeleteService`), since those can silently add/remove/alter schedules too. Any new way of mutating backup targets needs a `SyncSchedule()` call after `persist()`.

**Progress tracking (`models/progress.go`):** an in-memory-only `RunState` map (its own mutex, deliberately kept out of `cfg`/`persist()` — a crash/restart must never leave a stale "running" flag on disk). Populated by `models/backup.go`'s `progressWriter`, wired as both `cmd.Stdout` and `cmd.Stderr`: rsync via `--info=progress2` (regex on the `NN%` token), restic via `backup --json` (parses `message_type` lines: `status` for percent/ETA, `summary` for the final snapshot id, `error` for failures). Parsing is best-effort — an unparsed line just leaves the last known percent/message in place rather than failing the backup.

**Shared run helpers:** `models.RunNodeBackup(targetIDs []string)` and `models.RunServiceBackup(id string, targetIDs []string)` are the single code path used by manual-trigger controllers, the scheduler, and the "run all targets" endpoints. Don't duplicate stop/start/backup/persist logic in a controller — route new triggers through these.

**Compose support:** `docker compose` (default), `docker-compose`, `podman-compose`, selected per-service via `Service.ComposeType` (`models/backup.go`'s `composeCmd`). Services can be configured to stop before backup (`StopOnBackup=true`) and restart after; all backup runs are asynchronous (goroutine) and append a `BackupExecution` record to history.

**Compose scan (`models/scan.go`, `POST /v1/node/scan` or `nodemaster scan [folder] [--json]`):**
- Scans `/opt/compose`, `/root/compose`, `/home/*/compose` by default, plus an optional extra folder
- Parses compose YAML to deduce a backup folder (prefers `/opt/data/containers/<name>`, falls back to the common path prefix across volume mounts)
- Probes live status via `docker ps --filter label=com.docker.compose.project=<name>`
- Falls back to a text-based parser for compose files with duplicate YAML keys (which `gopkg.in/yaml.v3` rejects)

## Key files

- `models/types.go` — every persisted struct (`AppConfig`, `NodeInfo`, `RemoteNode`, `Service`, `BackupConfig`, `BackupTarget`, `BackupExecution`, `ScanResult`, etc.)
- `models/store.go` — the persistence layer (`cfg`, `mu`, `persist()`, config path resolution)
- `models/backup.go` — `RunBackup`/`runTarget`, `progressWriter`, `validateBackupTarget`, `StartService`/`StopService`/`composeCmd`
- `models/progress.go` — in-memory `RunState` tracking (not persisted)
- `models/scheduler.go` — cron wiring: `StartScheduler`/`SyncSchedule`
- `models/scan.go` — `ScanAll`, compose YAML parsing, backup-folder deduction
- `models/node.go` / `models/nodes.go` / `models/services.go` — CRUD for the local node, remote node registry, and services respectively
- `controllers/*.go` — beego controllers with `@router` annotations (source of truth for API surface)
- `routers/commentsRouter.go` — generated beego route registration, rebuilt via `bee generate routers` (see routing gotcha above) — never hand-edit
- `routers/router.go` — namespace wiring + dev-mode CORS filter
- `main.go` — entrypoint; also implements the `scan`/`info` CLI subcommands ahead of the normal `beego.Run()` path