Improve CLAUDE.md with enhanced operational guidance
- Add comprehensive command reference with quick scripts - Include node onboarding workflow and health monitoring - Update operational patterns with security and data management - Add critical setup requirements and constraints - Incorporate important information from README.md - Focus on practical operational aspects rather than generic practices Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
131
CLAUDE.md
Normal file
131
CLAUDE.md
Normal file
@@ -0,0 +1,131 @@
|
||||
# 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 (`headscale/headscale:latest`)
|
||||
- **Configuration**: `/config/config.yaml` with extensive Chinese comments
|
||||
- **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
|
||||
|
||||
### 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
|
||||
|
||||
### 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
|
||||
Reference in New Issue
Block a user