headscale/docker-dev/SETUP-SUMMARY.md

Headscale Docker Environment - Setup Summary

🎯 What We Built

A complete, working Docker Compose environment that simulates a Tailscale network using the open-source Headscale control server. This setup provides:

• Self-hosted Tailscale control plane using Headscale
• Two Tailscale client nodes that communicate securely
• Encrypted mesh networking with zero-configuration
• Real-world protocol behavior in an isolated environment

📁 Files Created

File	Purpose
docker-compose.yml	Main orchestration file with all services
headscale-config.yaml	Headscale server configuration
acl.hujson	Access control policy (allows all communication)
Makefile	Helper commands for easy management
.env	Environment variables and pre-auth keys
scripts/setup-headscale.sh	Automated user and key generation
scripts/client-init.sh	Tailscale client initialization
www/index.html	Test web content
README.md	Complete user documentation
TROUBLESHOOTING.md	Solutions for common issues
NETWORK-ARCHITECTURE.md	Detailed networking explanation
TESTING-CHECKLIST.md	Verification procedures

🌐 Network Architecture

Two-Layer Design

1. Docker Bridge Network (10.99.0.0/24)

   • Physical infrastructure layer
   • Container-to-container communication
   • Headscale control plane access

2. Tailscale Overlay Network (100.64.0.0/10)

   • Encrypted VPN tunnel layer
   • Secure node-to-node communication
   • WireGuard-based encryption

IP Assignments

Service	Docker IP	Tailscale IP	Role
headscale-server	10.99.0.10	N/A	Control server
tailscale-client1	10.99.0.21	100.64.0.1	VPN node 1
tailscale-client2	10.99.0.22	100.64.0.2	VPN node 2
test-webserver	10.99.0.30	N/A	HTTP test server

✅ Verified Working Features

Control Plane

• ✅ Headscale server startup and configuration
• ✅ User creation and management
• ✅ Pre-auth key generation and usage
• ✅ Node registration and IP assignment
• ✅ ACL policy enforcement

Data Plane

• ✅ Encrypted tunnels between clients
• ✅ Bidirectional connectivity testing
• ✅ DNS resolution (Docker + MagicDNS)
• ✅ HTTP traffic through VPN
• ✅ Real-time status monitoring

Infrastructure

• ✅ Docker networking and isolation
• ✅ Port mapping and external access
• ✅ Persistent storage for Headscale data
• ✅ Health checks and dependency management
• ✅ Graceful startup and shutdown

🔧 Key Insights from Testing

Configuration Evolution

Modern Headscale requires several configuration updates from older versions:

• Noise protocol: Required for Tailscale v2 compatibility
• Prefix format: Changed from ip_prefixes to structured prefixes
• User management: CLI uses user IDs instead of usernames
• ACL syntax: Stricter validation and email-format requirements

Network Behavior

The setup demonstrates how Tailscale creates secure overlay networks:

• Encryption transparency: Applications use Tailscale IPs, but traffic is encrypted
• Path optimization: Direct communication when possible, relayed when necessary
• Zero-trust model: Security doesn't rely on network boundaries

Practical Applications

This environment is ideal for:

• Headscale development: Testing changes before production deployment
• Network policy testing: Experimenting with ACL configurations
• Integration testing: Validating application behavior on Tailscale networks
• Education: Understanding how modern VPN technologies work

🚀 Quick Start Commands

# Navigate to the environment
cd /home/rpm/claude/headscale/docker-dev

# Start everything
make up

# Verify it's working
make status
make ping-test

# Clean up when done
make clean

📚 Documentation Structure

1. README.md - Start here for basic usage
2. NETWORK-ARCHITECTURE.md - Deep dive into networking
3. TROUBLESHOOTING.md - Solutions for common problems
4. TESTING-CHECKLIST.md - Systematic verification steps
5. SETUP-SUMMARY.md - This overview document

🎯 Next Steps

For Development

• Modify ACL policies to test different network topologies
• Add more clients to scale the network
• Integrate with external services
• Test route advertisement and exit nodes

For Production Use

• Replace SQLite with PostgreSQL for scalability
• Add TLS certificates for secure external access
• Implement backup strategies for Headscale data
• Configure monitoring and logging

For Learning

• Study the network packet flows using tcpdump
• Experiment with Headscale API endpoints
• Try different client configurations
• Explore the integration test patterns in the main Headscale repo

🏆 Achievement Summary

We successfully:

1. ✅ Built a complete Tailscale network simulation
2. ✅ Tested all core functionality with real traffic
3. ✅ Documented the architecture and troubleshooting steps
4. ✅ Verified networking behavior matches expectations
5. ✅ Created reusable infrastructure for future development

This environment provides a solid foundation for understanding, developing, and testing Tailscale-based networking solutions using the open-source Headscale project.

---

🎉 Congratulations! You now have a fully functional, well-documented Headscale development environment.