jimmy/nas-tools
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
0f1844b0468ee53e98553f465f49859200acd82c
nas-tools/CLAUDE.md
T
Gan, Jimmy b52986fed5
Deploy Dashboard (Dev) / Frontend Tests (push) Successful in 51s
Details
Deploy Dashboard (Dev) / Backend Tests (push) Failing after 13m39s
Details
Deploy Dashboard (Dev) / Build Dev Image (push) Has been skipped
Details
Deploy Dashboard (Dev) / Deploy to Dev (push) Has been skipped
Details
fix(ci): recreate venv after cache restore to fix absolute symlinks 
Running python3 -m venv venv over an existing cached venv recreates
the absolute symlinks and pyvenv.cfg paths so Python resolves to
the current system's python3 binary. Without this, cp -a preserves
stale symlinks from the cache source, causing venv/bin/python to
resolve to /usr/bin/python3 (system, not venv) and pytest not found.

Also switch validation to use python3 to match Ubuntu 24.04 convention.
2026-06-04 23:52:40 +08:00

3.5 KiB
Raw Blame History

NAS Tools Project

Architecture

  • Synology DS224+ (x86_64, 18GB RAM), Tailscale IP: 100.78.131.124, LAN: 192.168.31.221
  • Docker: /volume1/@appstore/ContainerManager/usr/bin/docker, compose dirs: /volume1/docker/*
  • Caddy VPS (161.33.182.109, Tailscale: 100.109.198.126): reverse proxy for nas.jimmygan.com → NAS:4000, music.jimmygan.com → NAS:4533
  • Build VPS (server2, 158.101.140.85, Tailscale: 100.70.115.1): podman, fast network for pulling images

Dashboard

  • Backend: Python FastAPI (dashboard/backend/)
  • Frontend: Svelte 5 + Tailwind CSS (dashboard/frontend/)
  • Svelte 5 runes: use $state, $props, $bindable (not legacy export let)
  • Sidebar: categorized as Main (Overview, Docker, Files, Terminal), Media (Navidrome, Jellyfin, Audiobookshelf, Immich), Tools (OpenClaw, Repos, Gitea Web, Stirling PDF, Vaultwarden, Speedtest)
  • New pages: create route in src/routes/, import in App.svelte, add to appropriate category in Sidebar.svelte

Authentication

  • Gitea API Access: Use a dedicated claude-ci-bot user with a Personal Access Token (PAT).

  • Secret Management: Store the PAT in an environment variable GITEA_TOKEN. Avoid hardcoding paths to secret files.

  • Project Secrets: Keep sensitive configurations (like the PAT) in a local .env file that is ignored by git.

  • Build images on VPS (server2) to avoid NAS HDD I/O saturation:

    1. Build on VPS with Podman
    2. Stream image to NAS: podman save <image> | ssh nasts "/volume1/@appstore/ContainerManager/usr/bin/docker load"
    3. Deploy: git push triggers Gitea Actions CI (builds on VPS, transfers, then docker compose up) — do NOT manually restart

  • CI workflows are in .gitea/workflows/ in this repo

claude-dev CI Contract

  • Source package lives in claude-dev/ (Dockerfile, required-tools.txt, and smoke scripts under claude-dev/scripts/)
  • CI-first only: update claude-dev/* in git, then push; do not do ad-hoc local image rebuild/redeploy for normal changes
  • Required capabilities are declared in claude-dev/required-tools.txt; adding tools must update this file and related smoke checks
  • Build/deploy gate (.gitea/workflows/deploy-claude-dev-dev.yml) uses NAS runner with DOCKER_BUILDKIT=0, then runs:
    • tools smoke (smoke-tools.sh)
    • network smoke (smoke-network.sh)
    • auth/mount smoke (smoke-auth.sh with required runtime mounts)
  • Deployment only happens after smoke pass, using immutable tag format claude-dev:dev-<timestamp>-<sha>
  • Runtime compose definition is claude-dev/docker-compose.yml; CI syncs it to /volume1/docker/claude-dev/docker-compose.yml
  • Runtime requirements preserved: network_mode: host, /volume1/repos mount, /root/.claude mount, /root/.claude.json mount, /root/.gitea_token mount
  • Rollback: run workflow manually with rollback_image (for example the value in /volume1/docker/claude-dev/previous-image.txt) to redeploy a known-good immutable tag via CI

Synology 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 for bind mounts

DNS

  • dnsmasq on NAS resolves *.jimmygan.com → 161.33.182.109 (Caddy VPS)
  • Tailscale split DNS: jimmygan.com → NAS (queries hit dnsmasq)
  • All paths (LAN, Tailscale, public) route through Caddy for TLS

Proxy API

  • URL: https://www.bytecatcode.org
  • Models: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5-20251001 (no date-suffixed names)
Reference in New Issue View Git Blame Copy Permalink