How gurucomputing/headscale-ui works
Project type and purpose
• This is a single-page application (SPA) “web frontend” for the Headscale coordination server.
• It is implemented in Svelte + Vite + Tailwind, packaged as a static site and served from the /web mount via a reverse proxy (e.g., Caddy).
• It communicates via REST/HTTP to the Headscale backend (the Tailscale-compatible server).
File structure
• Top-level dirs:
• src/ – Svelte app, components organized by feature (common, devices, users, settings).
• routes/ – SvelteKit (or Vite) route definitions and layouts.
• docker/ – Dockerfiles and scripts for development & production images.
• .github/workflows/ – CI/CD pipelines for publishing dev and release container images.
• documentation/ – MD files describing architecture, configuration, development, testing, style.
• Config files: Caddyfile, vite.config.js, tailwind.config.cjs, svelte.config.js, plus .npmrc, Prettier, etc.
README for additional insights
• Confirms it is packaged as a static site, expecting to be reverse-proxied under /web.
• Describes Docker compose integration with Headscale server; emphasizes CORS requirements.
• References documentation/architecture.md for more details on design.
a. Main Components
• Client (Browser) – runs the Svelte SPA.
• Reverse Proxy (Caddy / Traefik) – serves static UI files on /web, proxies API calls.
• Headscale-UI Container – serves the UI on ports 8080/8443 (static assets + SPA engine).
• Headscale Server Container – the actual coordination server (API endpoints).
• Docker Registry / GitHub Container Registry – stores built images.
• CI/CD (GitHub Actions) – builds & publishes images (dev & release).
• Developer Workstation / Dev Container – local development VS Code Server, live reload.
b. Relationships & Interactions
• User → HTTP(S) Request → Reverse Proxy /web → Headscale-UI Container → serves index.html + JS/CSS.
• Browser → API calls (e.g., /api/devices, /api/users) → Reverse Proxy → Headscale Server → JSON response → Browser.
• Git Push → GitHub Actions → Build Docker images → Push to Registry → (automated) Deploy to Prod.
• Dev: mount local source into Dev Container → live rebuild on file change → browser reload.
c. Architectural Patterns & Principles
• SPA served as static assets + client-side routing.
• API Gateway / Reverse Proxy pattern (Caddy handles static + dynamic routes, CORS fixes).
• Containerization for consistency between dev & prod.
• CI/CD pipelines for automated image builds & releases.
• Feature-based component organization in Svelte (common, devices, users, settings).
d. Key Technologies & Frameworks
• Svelte + SvelteKit or Vite for the frontend.
• Tailwind CSS for utility-first styling.
• Docker (multi-stage builds) for dev & prod images.
• Caddy (or Traefik) as reverse proxy with CORS injection.
• GitHub Actions for CI/CD.
• GitHub Container Registry (ghcr.io) as Docker registry.
Essential Elements to Capture
• Browser → Reverse Proxy path routing /web vs. API path.
• CORS handling block within the proxy.
• Ports mapping: 80/443 (external) → 8080/8443 (UI) → 8080 (Headscale API).
• Local dev container mapping vs. production container mapping.
• CI workflows: publish-dev-image.yaml & publish-release.yaml.