169 lines
7.3 KiB
Markdown
169 lines
7.3 KiB
Markdown
# Varaverk — Claude Code Context
|
|
|
|
## Working Rules (read first)
|
|
|
|
- **Workspace is always** `/boot/config/plugins/varaverk` — every edit goes here.
|
|
- **No Co-Authored-By** in commit messages unless explicitly asked.
|
|
- **No comments** unless the WHY is genuinely non-obvious.
|
|
- The `.plg` symlinks the installed plugin location directly to this workspace — one copy, no drift.
|
|
|
|
### Current workflow: edit here, push to Gitea
|
|
|
|
Pre-release — too many moving parts for a dev/prod split right now. Edits are made directly in `/boot/config/plugins/varaverk/` and pushed. This is intentional, not a gap.
|
|
|
|
### Future: dev/prod split (post-release)
|
|
|
|
When the codebase stabilises, the plan:
|
|
- **Dev** — a separate git clone somewhere on the array (`/mnt/user/Development/Varaverk/` or similar). All editing happens there.
|
|
- **Prod** — `/boot/config/plugins/varaverk/` remains as-is. Only updated via `git pull` (already handled by `git_pull_execute.sh` in the daily orchestrator, or triggered manually from the UI).
|
|
- **`plugin_setup.sh`** stays pointing at the prod path. Dev never touches `/boot/` directly.
|
|
- **Push is the only bridge** — no deploy hooks, no rsync-on-save, no direct path references between dev and prod. The old dev folder was deleted precisely because it violated this.
|
|
|
|
### Hard limits — do not cross these
|
|
|
|
- **Never create or modify `.claude/settings.json`** in this repo. No workspace hooks, ever. The stale hook that existed here previously fired `Deployment/deploy.sh` (now deleted) on every file edit and caused unintended deploys. If you think a hook would help, ask first.
|
|
- **Never change `HOST1_STORAGE_MODE_INTERNAL`** in `host1.conf`. Claude data belongs in `/mnt/user/appdata/claude-code/` — not inside this repo.
|
|
- **There is no dev folder.** The old `/mnt/user/Important Shit/Git/Development/Varaverk` copy was deleted. Do not recreate it.
|
|
- **Never move files between `Configurations/` and `Deployment/`** without explicit instruction. `Configurations/` = live runtime confs (gitignored). `Deployment/` = templates and setup tooling (tracked).
|
|
|
|
---
|
|
|
|
## Project: What Varaverk Is
|
|
|
|
Self-healing, self-maintaining, mutually-redundant two-server Unraid home media ecosystem.
|
|
One codebase runs on both servers. No primary/standby — both run independently and cover each other.
|
|
|
|
**HOST1 — unRAID-Gmer4Lfe** (`gmer4lfe@gmail.com`)
|
|
- Hardware: Threadripper 1950X, 128 GB RAM, ZFS cache pools
|
|
- Domain: Gmer4Lfe.com
|
|
- Runs: full arr stack (Sonarr/Radarr/Lidarr), auth stack (source of truth), Emby primary
|
|
|
|
**HOST2 — unRAID-Jayred365**
|
|
- Hardware: Intel i5 10th gen, 64 GB RAM
|
|
- Domain: Gmer4Lfe.us
|
|
- Status: being rebuilt — most host2.conf sections scaffolded, not yet fully online
|
|
|
|
Networking between hosts: Tailscale mesh. No hardcoded IPs — hostnames resolve via Tailscale.
|
|
|
|
---
|
|
|
|
## Configuration System (three-file model)
|
|
|
|
Every script sources all three at startup:
|
|
|
|
```
|
|
master.conf ← shared: thresholds, toggles, profiles, orchestrator job lists
|
|
host1.conf ← HOST1 credentials, shares, container names, keys
|
|
host2.conf ← HOST2 credentials, shares, container names, keys
|
|
```
|
|
|
|
Sparse checkout (git) means each server only pulls its own `host*.conf`.
|
|
HOST1 never sees HOST2 credentials and vice versa.
|
|
|
|
**Rule:** thresholds/toggles → `master.conf`; credentials/paths/container names → `host*.conf`.
|
|
|
|
`detect_hosts()` in `common.sh` matches `$(hostname)` against `HOST1`/`HOST2` in `master.conf`
|
|
and sets `MY_ID` / `REMOTE_ID` for the rest of the script.
|
|
|
|
---
|
|
|
|
## Platform Adapter Layer
|
|
|
|
`Plugin/unraid/adapter.sh` isolates all OS-specific calls.
|
|
Scripts never branch on OS directly — always call adapter functions.
|
|
This is intentional architecture — don't bypass it.
|
|
|
|
---
|
|
|
|
## Key Paths
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `master.conf` | Shared config — all thresholds, toggles, profiles |
|
|
| `host1.conf` / `host2.conf` | Per-host credentials, shares, container lists |
|
|
| `common.sh` | Shared functions — `detect_hosts()`, `log()`, `notify()`, etc. |
|
|
| `load_config.sh` | Sources all three conf files + common.sh |
|
|
| `State_Files/` | Runtime state (watchdogs, fallback, transcode) — survives reboots |
|
|
| `data/` | Historical logs and stats |
|
|
| `Plugin/unraid/` | Unraid WebGUI plugin (PHP pages, API endpoints, adapter) |
|
|
| `Orchestrators/` | Top-level schedulers (array_started, daily, weekly, watchdog) |
|
|
| `Watchdogs/` | docker_watchdog, system_watchdog, resource_watchdog, stability |
|
|
| `Fallback/` | Mutual container failover logic |
|
|
| `Rsync/` | rsync.sh + profile system |
|
|
| `Media/` | Arr cleanup, discovery, permissions, play state sync |
|
|
| `Tools/` | Manual one-off tools including `claude_startup.sh` |
|
|
|
|
---
|
|
|
|
## Orchestrator Schedule
|
|
|
|
| When | What |
|
|
|------|------|
|
|
| Array start | `Orchestrators/array_started.sh` → runs `ARRAY_START_SCRIPTS` |
|
|
| Every minute | `watchdog_orchestrator.sh` → resource → docker → system → stability watchdogs |
|
|
| Every 30 min | `critical_sync_maintenance.sh` → downloaders_reset, play_state_sync, critical rsync |
|
|
| Every 4 hours | `intermediate_sync_maintenance.sh` → arr_sync, arrs_failed_stalled_recovery |
|
|
| Daily 1am | `daily_sync_maintenance.sh` → git pull, permissions, cleaners, arr cleanup, docker updates |
|
|
| Sunday 2:30am | `weekly_sync_maintenance.sh` → full Emby + Critical-Data sync, weekly restarts |
|
|
| Sunday 3am+ | `monthly_maintenance.sh` (self-gated on 30-day uptime) → ZFS scrub, SMART tests |
|
|
| Sunday 7am | `sunday_morning_coffee_report.sh` → ZFS, SMART, certs, backup verify, bandwidth, Emby report |
|
|
|
|
---
|
|
|
|
## Rsync Toggle State (current)
|
|
|
|
```bash
|
|
RSYNC_ENABLED=true
|
|
CRITICAL_RSYNC_ENABLED=true
|
|
INTERMEDIATE_RSYNC_ENABLED=true
|
|
DAILY_RSYNC_ENABLED=true
|
|
WEEKLY_RSYNC_ENABLED=true
|
|
FALLBACK_RSYNC_ENABLED=true
|
|
```
|
|
|
|
---
|
|
|
|
## Fallback System
|
|
|
|
`fallback.sh` runs continuously from array start.
|
|
States: `NORMAL | FALLBACK | NO_INTERNET | DARK`
|
|
|
|
DDNS rules are absolute:
|
|
- Internet loss → stop own DDNS immediately
|
|
- Failover → start remote's DDNS as Tier 1 first
|
|
- Handback → stop remote DDNS → rsync → start containers → start local DDNS last
|
|
|
|
Tier delays before activating higher tiers are in `host*.conf` (`HOST1_TIER*_DELAY`, `HOST2_TIER*_DELAY`).
|
|
|
|
---
|
|
|
|
## Port Notes
|
|
|
|
- **NPM admin API (`HOST1_NPM_URL`)** — port **7818**. Port 81 is the partnership WebUI port (`HOST1_PARTNERSHIP_AUTH_WEBUIS`), not the API. Easy to confuse.
|
|
- **HOST1_NETWORK_WATCHDOG_NPM_URL** — external HTTPS domain, completely separate from the admin API.
|
|
|
|
## Known Gaps / Active Work
|
|
|
|
- HOST2 NPM/lldap credentials (`HOST2_NPM_USER`, `HOST2_NPM_PASS`, `HOST2_LLDAP_PASS`) are empty in `host2.conf` — fill in when HOST2 is back online.
|
|
- `PARTNERSHIP_ENABLED=false` — not yet active.
|
|
- `FALLBACK_ENABLED=true` — fallback is running.
|
|
|
|
---
|
|
|
|
## Claude Code Persistence on Unraid
|
|
|
|
`/root` is a RAM filesystem — wiped on every reboot.
|
|
`Tools/claude_startup.sh` runs at array start (via `ARRAY_START_SCRIPTS`) and:
|
|
- Symlinks `/root/.claude` → `/mnt/user/appdata/claude-code/.claude`
|
|
- Symlinks `/root/.local/share/claude` → `/mnt/user/appdata/claude-code/local/share/claude`
|
|
- Symlinks `/root/CLAUDE.md` → `/boot/config/plugins/varaverk/CLAUDE.md` (this file)
|
|
|
|
This file lives on `/boot` (USB flash) and is always available regardless of array state.
|
|
|
|
---
|
|
|
|
## Commit Style
|
|
|
|
Plain, concise messages. No Co-Authored-By trailers. No bullet-point summaries in the body.
|
|
One sentence on the why, not the what.
|