Ryan Malloy
5abc3c87b2
- Add Groups field to User struct with JSON storage - Include GetGroups() and SetGroups() helper methods - Extract groups from OIDC claims in FromClaim() - Add database migration 202509161200 for groups column - Update config-example.yaml with groups scope - Add comprehensive documentation and testing
153 lines
5.4 KiB
Markdown
153 lines
5.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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.** |