OIDC groups implementation

- 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

docker-dev/SETUP-SUMMARY.md

@@ -0,0 +1,153 @@
+# 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.**