docs: add architecture reference, update CLAUDE.md with current CI/sidebar state

2026-07-09 23:37:13 +08:00
parent e66dc9a38a
commit f7b8301824
2 changed files with 143 additions and 27 deletions
@@ -0,0 +1,100 @@
+# NAS Tools — Architecture & Operations
+
+## Overview
+
+NAS Dashboard is a web UI for managing a Synology DS224+ NAS and its ecosystem of services. It runs as a Docker container on the NAS with a FastAPI backend + Svelte 5 frontend.
+
+## Architecture
+
+```
+Browser → VPS Caddy (161.33.182.109, port 443)
+         → Tailscale → NAS Caddy (port 8443, fallback only)
+         → NAS Dashboard (port 4000)
+```
+
+DNS: `*.jimmygan.com` → VPS Caddy → Tailscale → NAS services.
+
+## Services
+
+### Media
+| Service | URL | Port | Description |
+|---------|-----|------|-------------|
+| Navidrome | music.jimmygan.com | 4533 | Music streaming |
+| Jellyfin | media.jimmygan.com | 8097 | Media server |
+| Audiobookshelf | books.jimmygan.com | 13378 | Audiobooks & podcasts |
+| Immich | photos.jimmygan.com | 2283 | Photo/video backup |
+| t-youtube | yt.jimmygan.com | 8001 | YouTube subscription reader |
+| Transmission | (sidebar route) | 9091 | BitTorrent client |
+
+### Tools
+| Service | URL | Description |
+|---------|-----|-------------|
+| Gitea | git.jimmygan.com | Git hosting + CI (Gitea Actions) |
+| LiteLLM | (dashboard route) | LLM proxy |
+| OPC | (dashboard route) | Kanban + agents |
+| n8n | n8n.jimmygan.com | Workflow automation |
+| Vaultwarden | vault.jimmygan.com | Password manager |
+| Hermes | hermes-agent.nousresearch.com/docs | AI Agent docs |
+
+## CI/CD (Gitea Actions)
+
+### Workflows
+- **deploy.yml** — Main branch: tests → build → deploy to production
+- **deploy-dev.yml** — Dev branch: tests → build → deploy to dev
+
+### Runners
+- **VPS runner** (`vps` label) — server2 (Oracle Tokyo, 158.101.140.85). Used for build + test jobs. Uses podman.
+- **NAS runner** (`nas` label) — DS224+. Used for deploy jobs. Uses Docker via `/volume1/@appstore/ContainerManager/usr/bin/docker`. Runs with `nas:host` label (host networking).
+
+### Build & Deploy Flow
+1. VPS runner builds Docker image
+2. Pushes to local registry: `100.78.131.124:5501/nas-dashboard:latest` (podman push --tls-verify=false)
+3. Streams image to NAS via SSH pipe: `podman save | gzip | ssh nasts "gunzip | docker load"`
+4. NAS runner deploys: `docker compose up -d`
+
+### CI Speed Notes
+- Build is the bottleneck (~12 min first run due to npm ci + Vite build)
+- npm ci is cached between runs (node_modules saved to disk on VPS)
+- pip is cached between runs
+- Registry push enables future layer caching
+- Synology Docker daemon doesn't support `--tls-verify=false` for pulls; SSH pipe used instead
+
+### Recent CI Fixes (July 2026)
+| Fix | Date | Description |
+|-----|------|-------------|
+| Checkout URL | Jul 8 | Changed from `gitea:3000` to `127.0.0.1:3300` (NAS host networking) |
+| TRANSMISSION_USER/PASS | Jul 8 | Added missing env vars to deploy step |
+| Gzip transfer | Jul 8 | Added gzip compression to SSH pipe |
+| Local registry | Jul 9 | Build pushes to local registry for layer caching |
+| NAS runner crash | Jul 8 | `.runner` address changed from `gitea:3000` to `127.0.0.1:3300` |
+
+## Local Registry
+
+Registry container: `registry-mirror` on NAS, port 5501.
+- Standalone mode (NOT Docker Hub proxy — Hub is blocked from China)
+- Listens on `0.0.0.0:5501`
+- Images pushed by VPS CI, pulled by NAS fallback via SSH pipe
+- API: `http://100.78.131.124:5501/v2/`
+
+## Dashboard Sidebar Layout
+
+### Main
+Overview, LiteLLM, OPC, Files, Terminal, Security
+
+### Media
+Navidrome, Jellyfin, Audiobookshelf, Immich, t-youtube, Media Management, Transmission
+
+### Tools
+Hermes, Chat Digest, Code Sessions, Repos, Gitea Web, Stirling PDF, Vaultwarden, n8n, Speedtest
+
+All external links use clean HTTPS URLs (no `:8443` port).
+
+## Cmd+K Palette
+Press `⌘K` (Mac) or `Ctrl+K` to fuzzy-search all sidebar items. New in July 2026.
+
+## NAS Quirks
+- No `crontab` — edit `/etc/crontab` with `sudo` + `printf`, restart crond
+- No `scp` subsystem — use `cat file | ssh ... 'cat > dest'`
+- ACLs override Unix perms — use `sudo chmod 777` + `synoacltool -enforce-inherit`
+- Docker at `/volume1/@appstore/ContainerManager/usr/bin/docker`
+- Tailscale userspace mode — cannot bind to Tailscale IP directly in Docker