2.3 KiB

Raw Blame History

Satoru Agent Notes

Project Intent

Satoru is a restic-based backup control plane for Linux hosts over SSH.

Core model:

Satoru pulls from edge hosts (no direct edge->B2 writes).
Stages data locally.
Runs restic locally for deduplicated snapshots.
Syncs restic data to B2 (scheduled).

Current Direction

Background job execution for site operations.
Preflight-first workflow before full backup runs.
Strong operational visibility through structured logs and job events.

Run The Server

cd /Users/peterli/git/satoru
go run ./cmd/satoru

Default URL:

http://localhost:8080

Logging

Satoru uses structured logging and supports:

LOG_FORMAT=console|json (default json)
LOG_LEVEL=debug|info|warn|error (default info)
LOG_FILE=/path/to/file.log (optional; logs still go to stdout)

Examples:

LOG_FORMAT=console LOG_LEVEL=debug go run ./cmd/satoru

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:

# comments allowed
RESTIC_PASSWORD=example-local-password
RESTIC_PASSWORD2=example-b2-password
B2_APPLICATION_ID=xxxx
B2_APPLICATION_KEY=yyyy
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:

DB state changes (job/site/session mutations).
Job lifecycle transitions and step boundaries.
Scan and backup target-level decisions/results.
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.

2.3 KiB Raw Blame History