nas-tools/PLAN.md

NAS Dashboard — Implementation Plan

Context

A modern, self-hosted web dashboard on your Synology DS224+ NAS (Tailscale-only) that serves as a single entry point to manage repos, Docker containers, files, terminal sessions, and media — plus an AI assistant. Replaces the need to SSH into the NAS for routine tasks. Public access via a dedicated Caddy reverse proxy VPS.

Architecture

Public Internet → nas.jimmygan.com / music.jimmygan.com
  │
  └── New AMD VPS (Caddy, HTTPS, Tailscale)
        │
        └── Tailscale → NAS (100.78.131.124)
              ├── :4000  NAS Dashboard (FastAPI + Svelte)
              │     ├── /api/docker/*  → Docker socket proxy (limited API)
              │     ├── /api/gitea/*   → Gitea REST API
              │     ├── /api/files/*   → /volume1 filesystem
              │     ├── /ws/terminal   → WebSocket pty (Tailscale-only)
              │     └── /*             → Svelte SPA
              ├── :4533  Navidrome (music)
              ├── :2283  Immich (photos, Tailscale-only)
              ├── :3300  Gitea (Tailscale-only)
              ├── :8096  Jellyfin (video, Tailscale-only)
              ├── :3100  OpenClaw (AI assistant, Tailscale-only)
              ├── :8080  Speedtest (Tailscale-only)
              ├── :13378 Audiobookshelf (audiobooks, Tailscale-only)
              ├── :8030  Stirling PDF (PDF tools, Tailscale-only)
              └── :8222  Vaultwarden (passwords, Tailscale-only)

Existing VPS (158.101.140.85): xray VLESS+REALITY on :443 — untouched

Tech Stack (Dashboard)

• Backend: Python FastAPI + uvicorn
• Frontend: Svelte + Tailwind CSS (light theme default, with dark/light toggle)
• Terminal: xterm.js + WebSocket pty bridge
• Docker mgmt: via docker-socket-proxy (Tecnativa) for safety
• Gitea: httpx async client
• Build: Multi-stage Dockerfile (node → python-slim), built on Mac, pushed to Gitea container registry
• LLM: Claude API (key from ~/.zshrc)

File Structure

nas-tools/
  PLAN.md
  backup.sh                   # Daily backup cron script
  notify.sh                   # Telegram notification utility
  dashboard/
    docker-compose.yml
    Dockerfile
    .env.example
    backend/
      main.py
      config.py
      auth.py
      requirements.txt
      routers/
        auth.py
        docker.py
        gitea.py
        files.py
        terminal.py
        system.py
    frontend/
      package.json
      vite.config.js
      svelte.config.js
      src/
        App.svelte
        lib/
          api.js
          terminal.js
        routes/
          Dashboard.svelte
          Docker.svelte
          Gitea.svelte
          Files.svelte
          Terminal.svelte
        components/
          Sidebar.svelte
          ContainerCard.svelte
          LogViewer.svelte
  navidrome/
    docker-compose.yml
  immich/
    docker-compose.yml
  openclaw/
    docker-compose.yml

Implementation Phases

Phase 1 — Provision new AMD VPS ✅

1. Add oci-amd-monitor.py to cloud-monitor repo:
   • Shape: VM.Standard.E2.1.Micro (1 OCPU, 1GB RAM, AMD free tier)
   • Display name: free-amd-caddy
   • AMD-compatible image (Ubuntu x86_64)
   • Same compartment, availability domain, subnet as existing VPS
2. Run script to grab AMD instance
3. Harden new VPS: SSH key-only, firewall (only 22/80/443), fail2ban, unattended-upgrades
4. Install Tailscale + Caddy on new VPS
5. Configure Caddy with HTTP basic auth immediately (placeholder until Phase 7 upgrades to 2FA)
6. Update Cloudflare DNS: nas.jimmygan.com and music.jimmygan.com → new VPS IP (set to "DNS only", let Caddy handle TLS)
7. Clean up stale DNS: moldcost → dead server1 (152.53.226.207) — remove or update

Phase 2 — Dashboard MVP: Docker management ✅

8. Create directory structure, Dockerfile, docker-compose.yml
9. Add docker-socket-proxy (Tecnativa) to limit Docker API access
10. Backend: main.py + config.py + docker router (list, start/stop, logs)
11. Frontend: Svelte app with sidebar + Docker container view
12. Terminal access control: backend middleware blocks /ws/terminal for non-Tailscale IPs (100.x.x.x)
13. File browser: read-write (mount /volume1 as rw), with path traversal protection
14. Add Docker log rotation to all compose files (max-size: 10m, max-file: 3)
15. Build image on Mac, push to Gitea container registry
16. Deploy on NAS, port 4000
17. Configure Caddy on new VPS: nas.jimmygan.com → NAS :4000 via Tailscale (behind basic auth from Phase 1)

Phase 3 — Gitea + Files + Terminal ✅

18. Add gitea router (repos, commits, trigger workflows) — needs Gitea API token
19. Add files router (browse /volume1, download, upload, delete) with path traversal protection
20. Add terminal router (WebSocket pty bridge + xterm.js) — blocked for non-Tailscale IPs
21. Dashboard overview page with links to all services

Phase 4 — Navidrome (Music) ✅

22. Deploy Navidrome Docker stack on port 4533 (with log rotation)
23. Point at /volume1/music
24. Link from dashboard sidebar
25. Configure Caddy: music.jimmygan.com → NAS :4533 via Tailscale

Phase 5 — Immich (Photos) ✅

26. Deploy Immich Docker stack on port 2283 (disable ML/face recognition, with log rotation)
27. Point at /volume1/photo + /volume1/homes/zjgump/Photos
28. Link from dashboard sidebar (Tailscale-only)

Phase 6 — OpenClaw (AI Assistant) ✅

29. Deploy OpenClaw Docker stack on port 3100 (with log rotation)
30. Configure Claude API as LLM provider
31. Configure messaging channels (Telegram, etc.)
32. Link from dashboard sidebar (Tailscale-only)

Phase 7 — Authentication & Security ✅

33. Upgrade dashboard auth from Caddy basic auth → session-based login + TOTP 2FA — Done (password + TOTP 2FA + passkey/WebAuthn login)
34. Rate limiting for brute force protection on Caddy — Done (fail2ban + failed login Telegram alerts)

Phase 8 — CI/CD for Dashboard ✅

35. Add Gitea workflow to nas-tools: on push to main, auto-deploy — Done (Gitea Actions runs docker compose up -d on push)
36. Tag images with git SHA + latest — Done
37. Auto-deploy on NAS — Done
38. Rollback: docker compose pull <previous-tag> && docker compose up -d

Phase 9 — Backup & Recovery ✅

33. Automated daily backup script — Done (Gitea DB, Immich DB, Gitea dump, docker configs + Vaultwarden, Paperless, n8n, Audiobookshelf, Calibre-web)
34. Backups stored to /volume1/backups — Done (7-day retention)
35. Telegram failure alerts — Done (sources creds from nas-dashboard .env)
36. Periodic restore test to verify backups work

Phase 10 — Monitoring & Alerts ✅

36. Add system stats to dashboard overview: CPU, RAM, disk usage — Done
37. Container health checks in docker-compose files — Done
38. Notification on failure (Telegram bot) — Done (container monitor + failed login alerts)

Phase 11 — Polish ✅

39. Light/dark theme toggle — Done
40. Add Jellyfin link to dashboard sidebar (port 8096) — Done (replaced Emby)

Phase 12 — Additional Services ✅

41. Deploy Audiobookshelf on port 13378 — Done, in dashboard sidebar
42. Deploy Stirling PDF on port 8030 — Done, in dashboard sidebar
43. Deploy Vaultwarden on port 8222 — Done, in dashboard sidebar
44. Deploy Watchtower for auto-updates — Done (internal, no sidebar link needed)
45. Deploy Speedtest on port 8080 — Done, in dashboard sidebar

Phase 14 — Hybrid AI Gateway (LiteLLM + cc-connect) 🚧

49. Add litellm/ service scaffold (docker-compose.yml, config/litellm.yaml, .env.example) with localhost-only host binding and env-driven provider keys — Done
50. Add dashboard backend LiteLLM operational probe (/api/litellm/health) and wire into protected routes — Done
51. Add cc-connect/ templates (README.md, config.example.toml, optional compose) for mobile bridge rollout — Done
52. Deploy LiteLLM image to NAS using server2 pull + stream load workflow to avoid slow GHCR pulls on NAS — Done
53. Network fix: attach LiteLLM to nas-dashboard_internal and set dashboard-dev LITELLM_URL=http://litellm:4005 — Done
54. Update backend health probe to support auth-required mode and configured health auth key — Done
55. Add LiteLLM dashboard UI page with sidebar link and health status card — Done
56. Add cc-connect dashboard UI page, sidebar link, and backend health/status endpoint — Done

Phase 13 — Off-site Backup

46. Add cloud backup (OneDrive or Google Drive) for critical data
47. Encrypt backups before upload
48. Retention policy for cloud copies

Media Paths

• Music: /volume1/music (70GB, FLAC/WAV/DSD/ALAC)
• Photos: /volume1/photo (186GB) + /volume1/homes/zjgump/Photos
• Video: /volume1/video (759GB)
• Emby: replaced by Jellyfin (port 8096)

VPS Strategy

• Existing VPS (158.101.140.85): xray VLESS+REALITY on :443 — untouched
• New AMD VPS: Caddy on :80/:443, Tailscale, reverse proxy to NAS
• Both in Tokyo region, Oracle free tier

DNS (Cloudflare)

• nas.jimmygan.com → new AMD VPS IP (DNS only, Caddy handles TLS)
• music.jimmygan.com → new AMD VPS IP (DNS only)
• moldcost.jimmygan.com → remove (dead server1)
• Existing jimmygan.com A record → keep as-is

Build Strategy

• Docker images built on Mac (faster than NAS Celeron)
• Push to Gitea container registry (100.78.131.124:3300)
• NAS pulls and runs images
• CI/CD automates this via Gitea Actions

Verification

1. Dashboard at http://100.78.131.124:4000 — Docker page shows containers, start/stop works
2. Gitea page lists repos and commits
3. Files page browses /volume1
4. Terminal opens a working shell session
5. Navidrome at :4533 — plays music from /volume1/music
6. Immich at :2283 — browses photos
7. OpenClaw at :3100 — responds via Claude API
8. https://nas.jimmygan.com — dashboard accessible from internet with login + 2FA
9. https://music.jimmygan.com — Navidrome accessible from internet
10. Backups run daily, restore tested
11. Dashboard shows system stats, alerts on disk/container issues