headscale/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Production deployment of **Headscale** - a self-hosted WireGuard control plane providing Tailscale-compatible networking with complete infrastructure control. This setup enables secure device-to-device connectivity for personal and server environments.

**Server Endpoint**: https://headscale.lotimmy.com
**Network Range**: 100.64.0.0/10 (IPv4), fd7a:115c:a1e0::/48 (IPv6)

## Essential Commands

### Service Management
- `make up` - Start all services in background
- `make up-fg` - Start services in foreground (debugging)
- `make down` - Stop and remove containers
- `make restart` - Restart all services
- `make logs` - View service logs (last 100 lines)
- `make ps` - Show container status
- `make exec` - Enter container shell
- `./run.sh` - Quick service start
- `./restart.sh` - Quick service restart
- `./stop.sh` - Quick service stop

### Headscale Operations
- `headscale nodes list` - List all connected devices
- `headscale nodes register --user <username> --key <preauth-key>` - Register new node
- `headscale nodes tag --identifier <id> --tags tag:server/mobile` - Apply tags
- `headscale nodes approve-routes --identifier <id> --routes <routes>` - Approve routes
- `headscale users list` - List user namespaces
- `headscale preauthkeys list --user <id>` - List pre-auth keys
- `headscale apikeys list` - List API keys
- `headscale apikeys revoke <key-id>` - Revoke API key

### Node On Workflow
1. Create pre-auth key: `headscale preauthkeys create --user 1 --reusable --ephemeral=false --expiration 87600h`
2. Client connects: `tailscale up --login-server https://headscale.lotimmy.com --auth-key <key>`
3. Register node: `headscale nodes register --user <username> --key <returned-key>`

### Backup and Recovery
- `./headscale_backup_and_restore.sh` - Automated backup with remote verification
- Manual backup: `docker compose down && tar czvf backup_$(date +%Y%m%d).tar.gz . && docker compose up -d`

### Health Monitoring
- `./api_user_request.sh` - API health check (returns 200 if healthy)
- `curl -s http://localhost:9090/metrics` - Prometheus metrics
- `make logs` - Service logs monitoring

## Architecture

### Core Components
- **Headscale Service**: Docker container, pinned to `headscale/headscale:v0.29.0` (do not use `:latest` — breaking config changes crash-loop the container)
- **Configuration**: `/config/config.yaml` with extensive Chinese comments
- **ACL Policy**: `/config/policy.hujson` (HuJSON), enabled via `policy.mode: file` + `policy.path`. Holds the allow-all ACL plus Taildrive `nodeAttrs`/`grants`
- **Data Storage**: `/data` directory containing SQLite database, keys, and certificates
- **Networking**: Three ports exposed (8080 HTTP API, 9090 metrics, 50443 gRPC)
- **External Network**: Requires `shared-net` Docker network

### Configuration Architecture
The `config.yaml` file contains:
- **Server Settings**: HTTPS endpoint (https://headscale.lotimmy.com) with multi-port binding
- **WireGuard Networking**: Tailscale-compatible IP ranges (100.64.0.0/10, fd7a:115c:a1e0::/48)
- **DNS Management**: Multi-provider setup with NextDNS primary, Cloudflare/Google fallback
- **Authentication**: API key and pre-authentication key system
- **Database**: SQLite with WAL mode for performance

The `policy.hujson` file contains:
- **acls**: allow-all (`accept * -> *:*`) to preserve full-mesh — REQUIRED, removing it locks out every node
- **nodeAttrs**: grants `drive:share` / `drive:access` to all nodes (Taildrive)
- **grants**: `tailscale.com/cap/drive` with all shares set to `rw` (Taildrive read/write)

### Data Persistence Structure
```
/data/
├── db.sqlite           # SQLite database (with -shm, -wal files)
├── noise_private.key   # WireGuard encryption key
└── [certificates/]      # TLS certificates (if using ACME)
```

### Management Scripts
- **Device Management**: `list_headscale_nodes.sh`, create/revoke API keys
- **Backup System**: `headscale_backup_and_restore.sh` with MD5 verification
- **Health Check**: `api_user_request.sh` verifies API availability
- **Onboarding**: `create_headscale_preauthkey.sh` creates 10-year device keys

### Network Architecture
- **Public Endpoint**: https://headscale.lotimmy.com (managed reverse proxy)
- **Internal Range**: 100.64.0.0/10 for IPv4, fd7a:115c:a1e0::/48 for IPv6
- **Exit Nodes**: Support for full internet routing through designated nodes
- **Custom Routes**: Advertisement of local subnets (e.g., 192.168.42.0/24)

## Operational Patterns

### Service Architecture
- Single-container deployment using `headscale/headscale:latest`
- External Docker network (`shared-net`) for connectivity
- Three critical ports: 8080 (HTTP API), 9090 (metrics), 50443 (gRPC)
- Watchtower integration for automatic image updates
  > ⚠️ Because the image is pinned to `:latest` **and** auto-updated by Watchtower, a breaking change in a new Headscale release can crash-loop the container (a removed config key triggers a startup FATAL, taking every node offline). Removed keys seen so far: `randomize_client_port` (FATAL), `ephemeral_node_inactivity_timeout` (renamed to `node.ephemeral.inactivity_timeout`). Prefer pinning a specific version tag, or review the CHANGELOG BREAKING section before upgrading. See OPERATIONS.md → 故障排除.

### Security Model
- Bearer token authentication for API access (hardcoded in scripts)
- Pre-authentication keys for device enrollment
- Tag-based node classification (server/mobile) for ACL policies
- Random WireGuard ports to avoid firewall conflicts
- TLS encryption required for all external communications

### Data Management
- SQLite database with WAL mode for performance
- Persistent volumes for config (`/config`) and data (`/data`)
- Automatic key generation for WireGuard encryption
- MD5 checksum verification for backups

### Critical Scripts
- **Device Onboarding**: `create_headscale_preauthkey.sh` creates 10-year reusable keys
- **API Management**: Automated key creation/revocation with JSON parsing
- **Backup System**: `headscale_backup_and_restore.sh` with remote verification
- **Health Monitoring**: `api_user_request.sh` verifies API endpoint availability

## Critical Setup Requirements

### Network Prerequisites
- Must create `shared-net` Docker network before deployment
- Public endpoint https://headscale.lotimmy.com requires reverse proxy
- All scripts execute from project root directory

### Configuration Details
- Chinese comments throughout config.yaml explain each parameter
- SQLite database with WAL mode enabled automatically
- Multi-provider DNS: NextDNS (primary) with Cloudflare/Google fallback
- MagicDNS enabled with base_domain: internal.lotimmy.com

### Operational Constraints
- All scripts interact via `docker exec -it headscale`
- Backup script stops service during backup process
- API scripts use hardcoded authentication tokens
- Container name fixed as "headscale" across all operations