78 lines
2.3 KiB
Markdown
78 lines
2.3 KiB
Markdown
# Satoru Agent Notes
|
|
|
|
## Project Intent
|
|
Satoru is a restic-based backup control plane for Linux hosts over SSH.
|
|
|
|
Core model:
|
|
1. Satoru pulls from edge hosts (no direct edge->B2 writes).
|
|
2. Stages data locally.
|
|
3. Runs restic locally for deduplicated snapshots.
|
|
4. Syncs restic data to B2 (scheduled).
|
|
|
|
## Current Direction
|
|
1. Background job execution for site operations.
|
|
2. Preflight-first workflow before full backup runs.
|
|
3. Strong operational visibility through structured logs and job events.
|
|
|
|
## Run The Server
|
|
```bash
|
|
cd /Users/peterli/git/satoru
|
|
go run ./cmd/satoru
|
|
```
|
|
|
|
Default URL:
|
|
- `http://localhost:8080`
|
|
|
|
## Logging
|
|
Satoru uses structured logging and supports:
|
|
|
|
1. `LOG_FORMAT=console|json` (default `json`)
|
|
2. `LOG_LEVEL=debug|info|warn|error` (default `info`)
|
|
3. `LOG_FILE=/path/to/file.log` (optional; logs still go to stdout)
|
|
|
|
Examples:
|
|
```bash
|
|
LOG_FORMAT=console LOG_LEVEL=debug go run ./cmd/satoru
|
|
```
|
|
|
|
```bash
|
|
LOG_FORMAT=json LOG_LEVEL=debug LOG_FILE=./logs/satoru.log go run ./cmd/satoru
|
|
tail -f ./logs/satoru.log | jq
|
|
```
|
|
|
|
## Config File (Optional)
|
|
You can configure runtime variables in a key-value file:
|
|
- default path: `/Users/peterli/git/satoru/data/satoru.conf`
|
|
- override path: `SATORU_CONFIG_FILE=/absolute/path/to/file`
|
|
- on first run, Satoru creates an example config automatically if missing
|
|
- if no explicit restic password is configured, Satoru auto-generates `RESTIC_PASSWORD` and appends it on first boot
|
|
|
|
Format:
|
|
```bash
|
|
# comments allowed
|
|
RESTIC_PASSWORD=example-local-password
|
|
RESTIC_PASSWORD2=example-b2-password
|
|
B2_APPLICATION_ID=xxxx
|
|
B2_APPLICATION_KEY=yyyy
|
|
B2_EXECUTABLE_PATH=/opt/homebrew/bin/b2
|
|
SATORU_RESTIC_B2_REPOSITORY=b2:bucket-name:repo-prefix
|
|
```
|
|
|
|
Precedence:
|
|
- environment variable overrides config file value.
|
|
|
|
## Debug Logging Expectation
|
|
Be proactive with debug-level logging for:
|
|
1. DB state changes (job/site/session mutations).
|
|
2. Job lifecycle transitions and step boundaries.
|
|
3. Scan and backup target-level decisions/results.
|
|
4. External command start/finish, duration, and failures.
|
|
|
|
Logs should include useful identifiers where possible:
|
|
- `job_id`, `site_id`, `job_type`, `target_path`, `target_mode`, `status`, `error`.
|
|
|
|
## Data Safety
|
|
Do not delete `data/satoru.db` during normal development, smoke checks, or troubleshooting.
|
|
|
|
Use forward migrations to evolve schema/data for soft-launched deployments.
|