nas-tools/docs/architecture.md

# 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

## Docker Networks

### NAS Dashboard Networks

| Network | Type | Used By | Purpose |
|---|---|---|---|
| `internal` | compose-defined | docker-socket-proxy, dashboard | Internal communication between dashboard containers |
| `nas-dashboard_internal` | external (pre-created) | docker-socket-proxy, dashboard, dashboard-dev | Shared internal network for dashboard services |
| `gitea_gitea` | external | dashboard, dashboard-dev | Connect dashboard to Gitea container |

Note: `internal` network is redundant — both services are also on `nas-dashboard_internal`. Consider removing `internal` and consolidating to `nas-dashboard_internal` only.

### Full NAS Network Inventory (all services)

| Network | Service |
|---|---|
| `gitea_gitea` | Gitea |
| `nas-dashboard_internal` | NAS Dashboard |
| `internal` | NAS Dashboard (compose-defined) |
| `authelia_auth` | Authelia |
| `immich_immich` | Immich |
| `jellyfin_default` | Jellyfin |
| `audiobookshelf_default` | Audiobookshelf |
| `calibre-web_default` | Calibre-Web |
| `navidrome_default` | Navidrome |
| `vaultwarden_default` | Vaultwarden |
| `stirling-pdf_default` | Stirling PDF |
| `n8n_default` | n8n |
| `paperless_paperless` | Paperless |
| `t-youtube_default` | t-youtube |
| `watchtower_default` | Watchtower |
| `dnsmasq_default` | DNS proxy |
| `openclaw_default` | OpenClaw |
| `openconnector_default` | OpenConnector |
| `registry-mirror_default` | Registry mirror |
| `speedtest_default` | Speedtest |
| `metube_default` | MeTube |
| `pixman_default` | Pixman |
| `tmp_default` | Temporary services |
| `bridge` | Docker default |
| `host` | Docker host mode |
| `none` | No networking |