diff --git a/.gitignore b/.gitignore index ddcf765..24f8266 100644 --- a/.gitignore +++ b/.gitignore @@ -64,6 +64,10 @@ htmlcov/ # Claude Code .claude/ +CLAUDE_CODE_SPEC.md +PROJECT_SUMMARY.md +QUICKSTART.md +VS_CODE_SETUP.md # Windows artifacts nul diff --git a/CLAUDE_CODE_SPEC.md b/CLAUDE_CODE_SPEC.md deleted file mode 100644 index 1bc5cf4..0000000 --- a/CLAUDE_CODE_SPEC.md +++ /dev/null @@ -1,459 +0,0 @@ -# NetBird MSP Appliance - Claude Code Specification - -## Project Overview -Build a complete, production-ready multi-tenant NetBird management platform that runs entirely in Docker containers. This is an MSP (Managed Service Provider) tool to manage 100+ isolated NetBird instances from a single web interface. - -## Technology Stack -- **Backend**: Python 3.11+ with FastAPI -- **Frontend**: HTML5 + Bootstrap 5 + Vanilla JavaScript (no frameworks) -- **Database**: SQLite -- **Containerization**: Docker + Docker Compose -- **Templating**: Jinja2 for Docker Compose generation -- **Integration**: Docker Python SDK, Nginx Proxy Manager API - -## Project Structure - -``` -netbird-msp-appliance/ -├── README.md # Main documentation -├── QUICKSTART.md # Quick start guide -├── ARCHITECTURE.md # Architecture documentation -├── LICENSE # MIT License -├── .gitignore # Git ignore file -├── .env.example # Environment variables template -├── install.sh # One-click installation script -├── docker-compose.yml # Main application container -├── Dockerfile # Application container definition -├── requirements.txt # Python dependencies -│ -├── app/ # Python application -│ ├── __init__.py -│ ├── main.py # FastAPI entry point -│ ├── models.py # SQLAlchemy models -│ ├── database.py # Database setup -│ ├── dependencies.py # FastAPI dependencies -│ │ -│ ├── routers/ # API endpoints -│ │ ├── __init__.py -│ │ ├── auth.py # Authentication endpoints -│ │ ├── customers.py # Customer CRUD -│ │ ├── deployments.py # Deployment management -│ │ ├── monitoring.py # Status & health checks -│ │ └── settings.py # System configuration -│ │ -│ ├── services/ # Business logic -│ │ ├── __init__.py -│ │ ├── docker_service.py # Docker container management -│ │ ├── npm_service.py # NPM API integration -│ │ ├── netbird_service.py # NetBird deployment orchestration -│ │ └── port_manager.py # UDP port allocation -│ │ -│ └── utils/ # Utilities -│ ├── __init__.py -│ ├── config.py # Configuration management -│ ├── security.py # Encryption, hashing -│ └── validators.py # Input validation -│ -├── templates/ # Jinja2 templates -│ ├── docker-compose.yml.j2 # Per-customer Docker Compose -│ ├── management.json.j2 # NetBird management config -│ └── relay.env.j2 # Relay environment variables -│ -├── static/ # Frontend files -│ ├── index.html # Main dashboard -│ ├── css/ -│ │ └── styles.css # Custom styles -│ └── js/ -│ └── app.js # Frontend JavaScript -│ -├── tests/ # Unit & integration tests -│ ├── __init__.py -│ ├── test_customer_api.py -│ ├── test_deployment.py -│ └── test_docker_service.py -│ -└── docs/ # Additional documentation - ├── API.md # API documentation - ├── DEPLOYMENT.md # Deployment guide - └── TROUBLESHOOTING.md # Common issues -``` - -## Key Features to Implement - -### 1. Customer Management -- **Create Customer**: Web form → API → Deploy NetBird instance -- **List Customers**: Paginated table with search/filter -- **Customer Details**: Status, logs, setup URL, actions -- **Delete Customer**: Remove all containers, NPM entries, data - -### 2. Automated Deployment -**Workflow when creating customer:** -1. Validate inputs (subdomain unique, email valid) -2. Allocate ports (Management internal, Relay UDP public) -3. Generate configs from Jinja2 templates -4. Create instance directory: `/opt/netbird-instances/kunde{id}/` -5. Write `docker-compose.yml`, `management.json`, `relay.env` -6. Start Docker containers via Docker SDK -7. Wait for health checks (max 60s) -8. Create NPM proxy hosts via API (with SSL) -9. Update database with deployment info -10. Return setup URL to user - -### 3. Web-Based Configuration -**All settings in database, editable via UI:** -- Base Domain -- Admin Email -- NPM API URL & Token -- NetBird Docker Images -- Port Ranges -- Data Directories - -No manual config file editing required! - -### 4. Nginx Proxy Manager Integration -**Per customer, create proxy host:** -- Domain: `{subdomain}.{base_domain}` -- Forward to: `netbird-kunde{id}-dashboard:80` -- SSL: Automatic Let's Encrypt -- Advanced config: Route `/api/*` to management, `/signalexchange.*` to signal, `/relay` to relay - -### 5. Port Management -**UDP Ports for STUN/Relay (publicly accessible):** -- Customer 1: 3478 -- Customer 2: 3479 -- ... -- Customer 100: 3577 - -**Algorithm:** -- Find next available port starting from 3478 -- Check if port not in use (via `netstat` or database) -- Assign to customer -- Store in database - -### 6. Monitoring & Health Checks -- Container status (running/stopped/failed) -- Health check endpoints (HTTP checks to management service) -- Resource usage (via Docker stats API) -- Relay connectivity test - -## Database Schema - -### Table: customers -```sql -CREATE TABLE customers ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - name TEXT NOT NULL, - company TEXT, - subdomain TEXT UNIQUE NOT NULL, - email TEXT NOT NULL, - max_devices INTEGER DEFAULT 20, - notes TEXT, - status TEXT DEFAULT 'active' CHECK(status IN ('active', 'inactive', 'deploying', 'error')), - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -); -``` - -### Table: deployments -```sql -CREATE TABLE deployments ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - customer_id INTEGER NOT NULL UNIQUE, - container_prefix TEXT NOT NULL, - relay_udp_port INTEGER UNIQUE NOT NULL, - npm_proxy_id INTEGER, - relay_secret TEXT NOT NULL, - setup_url TEXT, - deployment_status TEXT DEFAULT 'pending' CHECK(deployment_status IN ('pending', 'running', 'stopped', 'failed')), - deployed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - last_health_check TIMESTAMP, - FOREIGN KEY (customer_id) REFERENCES customers(id) ON DELETE CASCADE -); -``` - -### Table: system_config -```sql -CREATE TABLE system_config ( - id INTEGER PRIMARY KEY CHECK (id = 1), - base_domain TEXT NOT NULL, - admin_email TEXT NOT NULL, - npm_api_url TEXT NOT NULL, - npm_api_token_encrypted TEXT NOT NULL, - netbird_management_image TEXT DEFAULT 'netbirdio/management:latest', - netbird_signal_image TEXT DEFAULT 'netbirdio/signal:latest', - netbird_relay_image TEXT DEFAULT 'netbirdio/relay:latest', - netbird_dashboard_image TEXT DEFAULT 'netbirdio/dashboard:latest', - data_dir TEXT DEFAULT '/opt/netbird-instances', - docker_network TEXT DEFAULT 'npm-network', - relay_base_port INTEGER DEFAULT 3478, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -); -``` - -### Table: deployment_logs -```sql -CREATE TABLE deployment_logs ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - customer_id INTEGER NOT NULL, - action TEXT NOT NULL, - status TEXT NOT NULL CHECK(status IN ('success', 'error', 'info')), - message TEXT, - details TEXT, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, - FOREIGN KEY (customer_id) REFERENCES customers(id) ON DELETE CASCADE -); -``` - -### Table: users (simple auth) -```sql -CREATE TABLE users ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - username TEXT UNIQUE NOT NULL, - password_hash TEXT NOT NULL, - email TEXT, - is_active BOOLEAN DEFAULT TRUE, - created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP -); -``` - -## API Endpoints to Implement - -### Authentication -``` -POST /api/auth/login # Login and get token -POST /api/auth/logout # Logout -GET /api/auth/me # Get current user -POST /api/auth/change-password -``` - -### Customers -``` -POST /api/customers # Create + auto-deploy -GET /api/customers # List all (pagination, search, filter) -GET /api/customers/{id} # Get details -PUT /api/customers/{id} # Update -DELETE /api/customers/{id} # Delete + cleanup -``` - -### Deployments -``` -POST /api/customers/{id}/deploy # Manual deploy -POST /api/customers/{id}/start # Start containers -POST /api/customers/{id}/stop # Stop containers -POST /api/customers/{id}/restart # Restart containers -GET /api/customers/{id}/logs # Get container logs -GET /api/customers/{id}/health # Health check -``` - -### Monitoring -``` -GET /api/monitoring/status # System overview -GET /api/monitoring/customers # All customers status -GET /api/monitoring/resources # Host resource usage -``` - -### Settings -``` -GET /api/settings/system # Get system config -PUT /api/settings/system # Update system config -GET /api/settings/test-npm # Test NPM connectivity -``` - -## Docker Compose Template (Per Customer) - -```yaml -version: '3.8' - -networks: - npm-network: - external: true - -services: - netbird-management: - image: {{ netbird_management_image }} - container_name: netbird-kunde{{ customer_id }}-management - restart: unless-stopped - networks: - - npm-network - volumes: - - {{ instance_dir }}/data/management:/var/lib/netbird - - {{ instance_dir }}/management.json:/etc/netbird/management.json - command: ["--port", "80", "--log-file", "console", "--log-level", "info", - "--single-account-mode-domain={{ subdomain }}.{{ base_domain }}", - "--dns-domain={{ subdomain }}.{{ base_domain }}"] - - netbird-signal: - image: {{ netbird_signal_image }} - container_name: netbird-kunde{{ customer_id }}-signal - restart: unless-stopped - networks: - - npm-network - volumes: - - {{ instance_dir }}/data/signal:/var/lib/netbird - - netbird-relay: - image: {{ netbird_relay_image }} - container_name: netbird-kunde{{ customer_id }}-relay - restart: unless-stopped - networks: - - npm-network - ports: - - "{{ relay_udp_port }}:3478/udp" - env_file: - - {{ instance_dir }}/relay.env - environment: - - NB_ENABLE_STUN=true - - NB_STUN_PORTS=3478 - - NB_LISTEN_ADDRESS=:80 - - NB_EXPOSED_ADDRESS=rels://{{ subdomain }}.{{ base_domain }}:443 - - NB_AUTH_SECRET={{ relay_secret }} - - netbird-dashboard: - image: {{ netbird_dashboard_image }} - container_name: netbird-kunde{{ customer_id }}-dashboard - restart: unless-stopped - networks: - - npm-network - environment: - - NETBIRD_MGMT_API_ENDPOINT=https://{{ subdomain }}.{{ base_domain }} - - NETBIRD_MGMT_GRPC_API_ENDPOINT=https://{{ subdomain }}.{{ base_domain }} -``` - -## Frontend Requirements - -### Main Dashboard (index.html) -**Layout:** -- Navbar: Logo, "New Customer" button, User menu (settings, logout) -- Stats Cards: Total customers, Active, Inactive, Errors -- Customer Table: Name, Subdomain, Status, Devices, Actions -- Pagination: 25 customers per page -- Search bar: Filter by name, subdomain, email -- Status filter dropdown: All, Active, Inactive, Error - -**Customer Table Actions:** -- View Details (→ customer detail page) -- Start/Stop/Restart (inline buttons) -- Delete (with confirmation modal) - -### Customer Detail Page -**Tabs:** -1. **Info**: All customer details, edit button -2. **Deployment**: Status, Setup URL (copy button), Container status -3. **Logs**: Real-time logs from all containers (auto-refresh) -4. **Health**: Health check results, relay connectivity test - -### Settings Page -**Tabs:** -1. **System Configuration**: All system settings, save button -2. **NPM Integration**: API URL, Token, Test button -3. **Images**: NetBird Docker image tags -4. **Security**: Change admin password - -### Modal Dialogs -- New/Edit Customer Form -- Delete Confirmation -- Deployment Progress (with spinner) -- Error Display - -## Security Requirements - -1. **Password Hashing**: Use bcrypt for admin password -2. **Secret Encryption**: Encrypt NPM token and relay secrets with Fernet -3. **Input Validation**: Pydantic models for all API inputs -4. **SQL Injection Prevention**: Use SQLAlchemy ORM (no raw queries) -5. **CSRF Protection**: Token-based authentication -6. **Rate Limiting**: Prevent brute force on login endpoint - -## Error Handling - -All operations should have comprehensive error handling: - -```python -try: - # Deploy customer - result = deploy_customer(customer_id) -except DockerException as e: - # Rollback: Stop containers - # Log error - # Update status to 'failed' - # Return error to user -except NPMException as e: - # Rollback: Remove containers - # Log error - # Update status to 'failed' -except Exception as e: - # Generic rollback - # Log error - # Alert admin -``` - -## Testing Requirements - -1. **Unit Tests**: All services (docker_service, npm_service, etc.) -2. **Integration Tests**: Full deployment workflow -3. **API Tests**: All endpoints with different scenarios -4. **Mock External Dependencies**: Docker API, NPM API - -## Deployment Process - -1. Clone repository -2. Run `./install.sh` -3. Access `http://server-ip:8000` -4. Complete setup wizard -5. Deploy first customer - -## System Requirements Documentation - -**Include in README.md:** - -### For 100 Customers: -- **CPU**: 16 cores (minimum 8) -- **RAM**: 64 GB (minimum) - 128 GB (recommended) - - Formula: `(100 customers × 600 MB) + 8 GB overhead = 68 GB` -- **Disk**: 500 GB SSD (minimum) - 1 TB recommended -- **Network**: 1 Gbps dedicated connection -- **OS**: Ubuntu 22.04 LTS or 24.04 LTS - -### Port Requirements: -- **TCP 8000**: Web UI -- **UDP 3478-3577**: Relay/STUN (100 ports for 100 customers) - -## Success Criteria - -✅ One-command installation via `install.sh` -✅ Web-based configuration (no manual file editing) -✅ Customer deployment < 2 minutes -✅ All settings in database -✅ Automatic NPM integration -✅ Comprehensive error handling -✅ Clean, professional UI -✅ Full API documentation (auto-generated) -✅ Health monitoring -✅ Easy to deploy on fresh Ubuntu VM - -## Special Notes for Claude Code - -- **Use type hints** throughout Python code -- **Document all functions** with docstrings -- **Follow PEP 8** style guidelines -- **Create modular code**: Each service should be independently testable -- **Use async/await** where appropriate (FastAPI endpoints) -- **Provide comprehensive comments** for complex logic -- **Include error messages** that help users troubleshoot - -## File Priorities - -Create in this order: -1. Basic structure (directories, requirements.txt, Dockerfile, docker-compose.yml) -2. Database models and setup (models.py, database.py) -3. Core services (docker_service.py, port_manager.py) -4. API routers (start with customers.py) -5. NPM integration (npm_service.py) -6. Templates (Jinja2 files) -7. Frontend (HTML, CSS, JS) -8. Installation script -9. Documentation -10. Tests - -This specification provides everything needed to build a production-ready NetBird MSP Appliance! diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md deleted file mode 100644 index 5a3d005..0000000 --- a/PROJECT_SUMMARY.md +++ /dev/null @@ -1,240 +0,0 @@ -# NetBird MSP Appliance - Project Summary - -## 📦 Was ist enthalten? - -Dieses Repository enthält ein **vollständiges, produktionsreifes Multi-Tenant NetBird Management System** für MSPs (Managed Service Provider). - -## 🎯 Hauptziel - -Ermöglicht MSPs, **100+ isolierte NetBird-Instanzen** für ihre Kunden von einer einzigen Web-Oberfläche aus zu verwalten - komplett in Docker containerisiert und mit einem Befehl deploybar. - -## 📁 Repository-Struktur - -``` -netbird-msp-appliance/ -├── 📖 README.md # Vollständige Dokumentation -├── 🚀 QUICKSTART.md # 10-Minuten Quick Start -├── 🏗️ ARCHITECTURE.md # System-Architektur -├── 💻 VS_CODE_SETUP.md # Guide für VS Code + Claude Code -├── 📋 CLAUDE_CODE_SPEC.md # Vollständige Spezifikation für Claude Code -├── 🛠️ install.sh # One-Click Installation -├── 🐳 docker-compose.yml # Docker Container Definition -├── 📦 Dockerfile # Application Container -├── 📝 requirements.txt # Python Dependencies -├── ⚙️ .env.example # Environment Variables Template -├── 📜 LICENSE # MIT License -├── 🙋 CONTRIBUTING.md # Contribution Guidelines -│ -├── app/ # Python FastAPI Application -│ ├── main.py # Entry Point -│ ├── models.py # Database Models (ERSTELLT) -│ ├── database.py # DB Setup (ERSTELLT) -│ ├── routers/ # API Endpoints (ZU ERSTELLEN) -│ ├── services/ # Business Logic (ZU ERSTELLEN) -│ └── utils/ # Utilities (ZU ERSTELLEN) -│ -├── templates/ # Jinja2 Templates (ZU ERSTELLEN) -├── static/ # Frontend Files (ZU ERSTELLEN) -└── tests/ # Tests (ZU ERSTELLEN) -``` - -## ✅ Was ist bereits fertig? - -- ✅ **Dokumentation**: README, Quickstart, Architecture Guide -- ✅ **Docker Setup**: docker-compose.yml, Dockerfile -- ✅ **Installation Script**: install.sh (funktionsbereit) -- ✅ **Database Models**: Vollständige SQLAlchemy Models -- ✅ **Database Setup**: Database configuration -- ✅ **FastAPI Entry Point**: main.py mit Routing-Struktur -- ✅ **Claude Code Spezifikation**: Detaillierte Implementierungs-Anleitung -- ✅ **Environment Template**: .env.example -- ✅ **Git Setup**: .gitignore - -## 🔨 Was muss noch implementiert werden? - -Diese Aufgaben sind für **Claude Code** vorbereitet (siehe CLAUDE_CODE_SPEC.md): - -### 1. Backend (Python) -- [ ] **API Routers** (app/routers/): - - auth.py - Authentication - - customers.py - Customer CRUD - - deployments.py - Deployment Management - - monitoring.py - Status & Health - - settings.py - System Config - -- [ ] **Services** (app/services/): - - docker_service.py - Docker Container Management - - npm_service.py - Nginx Proxy Manager API - - netbird_service.py - Deployment Orchestration - - port_manager.py - UDP Port Allocation - -- [ ] **Utils** (app/utils/): - - config.py - Configuration Management - - security.py - Encryption, Hashing - - validators.py - Input Validation - -### 2. Templates (Jinja2) -- [ ] docker-compose.yml.j2 - Per-Customer Docker Compose -- [ ] management.json.j2 - NetBird Management Config -- [ ] relay.env.j2 - Relay Environment Variables - -### 3. Frontend (HTML/CSS/JS) -- [ ] index.html - Main Dashboard -- [ ] styles.css - Custom Styling -- [ ] app.js - Frontend Logic - -### 4. Tests -- [ ] Unit Tests for Services -- [ ] Integration Tests -- [ ] API Tests - -## 🚀 Wie geht es weiter? - -### Option 1: Mit Claude Code (EMPFOHLEN) - -1. **Öffne das Projekt in VS Code**: - ```bash - cd netbird-msp-appliance - code . - ``` - -2. **Installiere Claude Code Plugin** in VS Code - -3. **Folge der Anleitung** in `VS_CODE_SETUP.md` - -4. **Starte Claude Code** und sage: - ``` - Bitte lies CLAUDE_CODE_SPEC.md und implementiere - das komplette NetBird MSP Appliance Projekt. - ``` - -5. **Claude Code wird**: - - Alle fehlenden Dateien erstellen - - Backend implementieren - - Frontend bauen - - Tests hinzufügen - - Alles dokumentieren - -**Erwartete Entwicklungszeit: 2-3 Stunden** - -### Option 2: Manuell entwickeln - -Folge der Struktur in `CLAUDE_CODE_SPEC.md` und implementiere Schritt für Schritt: - -1. Backend Services -2. API Routers -3. Templates -4. Frontend -5. Tests - -## 💾 System-Anforderungen - -### Für 100 Kunden: - -| Komponente | Minimum | Empfohlen | -|------------|---------|-----------| -| **CPU** | 8 Cores | 16 Cores | -| **RAM** | 64 GB | 128 GB | -| **Disk** | 500 GB SSD | 1 TB NVMe | -| **OS** | Ubuntu 22.04 | Ubuntu 24.04 | -| **Network** | 100 Mbps | 1 Gbps | - -### Benötigte Ports: -- **TCP 8000**: Web UI -- **UDP 3478-3577**: NetBird Relay (100 Ports für 100 Kunden) - -### Berechnung: -``` -RAM pro Kunde: ~600 MB -100 Kunden: 60 GB -+ OS & Appliance: 8 GB -= 68 GB total (64 GB Minimum) -``` - -## 🔧 Installation (nach Entwicklung) - -```bash -# 1. Repository clonen -git clone https://github.com/yourusername/netbird-msp-appliance.git -cd netbird-msp-appliance - -# 2. Installer ausführen -chmod +x install.sh -sudo ./install.sh - -# 3. Web UI öffnen -# Browser: http://YOUR_SERVER_IP:8000 -# Login mit Credentials aus Installer-Output -``` - -## 📊 Features - -- ✅ **Multi-Tenant**: 100+ isolierte NetBird-Instanzen -- ✅ **Web-basierte Konfiguration**: Keine Config-Files manuell editieren -- ✅ **Automatisches Deployment**: < 2 Minuten pro Kunde -- ✅ **NPM Integration**: Automatische SSL-Zertifikate -- ✅ **Monitoring**: Health Checks, Container Status, Logs -- ✅ **Docker-basiert**: Einfaches Update und Wartung -- ✅ **One-Click Installation**: Ein Befehl, fertig - -## 🔐 Sicherheit - -- Passwort-Hashing mit bcrypt -- Token-Verschlüsselung mit Fernet -- Input-Validation via Pydantic -- SQL-Injection-Schutz via SQLAlchemy ORM -- Rate-Limiting für APIs - -## 📚 Dokumentation - -| Dokument | Zweck | -|----------|-------| -| README.md | Vollständige Dokumentation | -| QUICKSTART.md | 10-Minuten Quick Start | -| ARCHITECTURE.md | System-Architektur Details | -| CLAUDE_CODE_SPEC.md | Implementierungs-Spezifikation | -| VS_CODE_SETUP.md | VS Code + Claude Code Guide | -| CONTRIBUTING.md | Contribution Guidelines | - -## 🎓 Learning Resources - -Dieses Projekt ist auch ein **exzellentes Lernprojekt** für: -- FastAPI Backend Development -- Docker Container Orchestration -- Multi-Tenant SaaS Architecture -- Nginx Proxy Manager Integration -- SQLAlchemy ORM -- Jinja2 Templating -- Bootstrap 5 Frontend - -## 🤝 Support & Community - -- **Issues**: GitHub Issues für Bugs und Features -- **Discussions**: GitHub Discussions für Fragen -- **Email**: support@yourdomain.com - -## 📝 License - -MIT License - siehe LICENSE Datei - -## 🙏 Credits - -- **NetBird Team** - für das großartige Open-Source VPN -- **FastAPI** - für das moderne Python Framework -- **Nginx Proxy Manager** - für einfaches Reverse Proxy Management - ---- - -## 📞 Next Steps - -1. **Entwicklung starten**: Öffne VS_CODE_SETUP.md -2. **Claude Code nutzen**: Folge der Anleitung -3. **Testen**: Lokal mit Docker testen -4. **Deployen**: Auf VM installieren -5. **Ersten Kunden anlegen**: Web UI nutzen - -**Viel Erfolg mit deiner NetBird MSP Appliance! 🚀** - ---- - -*Erstellt für einfaches Deployment und perfekte Integration mit Claude Code* diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index 93cc852..0000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,148 +0,0 @@ -# 🚀 NetBird MSP Appliance - Quick Start Guide - -Get up and running in 10 minutes! - -## Prerequisites - -- Ubuntu 22.04 or 24.04 LTS -- Root access -- 64GB RAM minimum (for 100 customers) -- 500GB SSD minimum -- Domain with wildcard DNS (*.yourdomain.com) - -## Installation (3 commands!) - -```bash -# 1. Clone repository -git clone https://github.com/yourusername/netbird-msp-appliance.git -cd netbird-msp-appliance - -# 2. Run installer -chmod +x install.sh -sudo ./install.sh - -# 3. Access web UI -# Open: http://YOUR_SERVER_IP:8000 -# Default login will be shown at end of installation -``` - -## Post-Installation Configuration - -### 1. First Login -- Use credentials displayed after installation -- **CHANGE PASSWORD IMMEDIATELY** in Settings - -### 2. Configure System (Settings → System Configuration) - -```yaml -Base Domain: yourdomain.com -Admin Email: admin@yourdomain.com -NPM API URL: http://nginx-proxy-manager:81/api -NPM API Token: -``` - -### 3. Configure Firewall - -```bash -# Allow web interface -sudo ufw allow 8000/tcp - -# Allow NetBird relay ports (for up to 100 customers) -sudo ufw allow 3478:3577/udp - -# Apply rules -sudo ufw reload -``` - -### 4. Get NPM API Token - -1. Access your Nginx Proxy Manager -2. Go to Users → Edit your user -3. Copy the API token -4. Paste in NetBird MSP Appliance Settings - -## Deploy Your First Customer - -1. Click "New Customer" -2. Fill in: - - Name: "Test Customer" - - Subdomain: "test" (becomes test.yourdomain.com) - - Email: customer@example.com - - Max Devices: 20 -3. Click "Deploy" -4. Wait 60-90 seconds -5. Done! Share the setup URL with your customer - -## Verify DNS Configuration - -Before deploying customers, ensure wildcard DNS works: - -```bash -# Test DNS resolution -nslookup test.yourdomain.com -# Should return your server IP - -# Or -dig test.yourdomain.com -``` - -## Troubleshooting - -### Customer deployment fails -```bash -# Check logs -docker logs netbird-msp-appliance - -# Check NPM connectivity -curl -I http://nginx-proxy-manager:81/api -``` - -### NPM not accessible -Make sure NPM is on the same Docker network: -```bash -docker network connect npm-network -``` - -### Ports already in use -```bash -# Check what's using port 8000 -sudo lsof -i :8000 - -# Kill process if needed -sudo kill -9 -``` - -## Next Steps - -- Read full [README.md](README.md) for details -- Check [CONTRIBUTING.md](CONTRIBUTING.md) to contribute -- Join discussions for support - -## Quick Commands - -```bash -# View logs -docker logs -f netbird-msp-appliance - -# Restart appliance -docker restart netbird-msp-appliance - -# Stop all customer instances -docker stop $(docker ps -q --filter "name=netbird-kunde") - -# Backup database -docker exec netbird-msp-appliance cp /app/data/netbird_msp.db /app/data/backup-$(date +%Y%m%d).db -``` - -## System Requirements Calculator - -| Customers | RAM | CPU | Disk | -|-----------|-----|-----|------| -| 25 | 16GB | 4 cores | 200GB | -| 50 | 32GB | 8 cores | 350GB | -| 100 | 64GB | 16 cores | 500GB | -| 200 | 128GB | 32 cores | 1TB | - -Formula: `(Customers × 600MB) + 8GB (OS + Appliance)` - -Happy MSP-ing! 🎉 diff --git a/VS_CODE_SETUP.md b/VS_CODE_SETUP.md deleted file mode 100644 index 9ec7d73..0000000 --- a/VS_CODE_SETUP.md +++ /dev/null @@ -1,215 +0,0 @@ -# Visual Studio Code + Claude Code Setup Guide - -## Für den Entwicklungsprozess mit Claude Code Plugin - -### Schritt 1: Repository vorbereiten - -```bash -# Repository in VS Code öffnen -cd /path/to/netbird-msp-appliance -code . -``` - -### Schritt 2: Claude Code Plugin installieren - -1. Öffne VS Code Extensions (Ctrl+Shift+X) -2. Suche nach "Claude Code" -3. Installiere das Plugin -4. Authentifiziere dich mit deinem Anthropic Account - -### Schritt 3: Claude Code verwenden - -#### Hauptaufgabe an Claude geben: - -Öffne Claude Code Chat und schicke folgende Nachricht: - -``` -Bitte lies die Datei CLAUDE_CODE_SPEC.md und implementiere das komplette NetBird MSP Appliance Projekt gemäß den Spezifikationen. - -Prioritäten: -1. Erstelle zuerst die komplette Dateistruktur -2. Implementiere die Datenbank-Modelle und API-Routers -3. Baue die Services (docker_service, npm_service, netbird_service) -4. Erstelle die Jinja2 Templates -5. Baue das Frontend (HTML/CSS/JS) -6. Füge Tests hinzu - -Achte besonders auf: -- Type hints in allen Python-Funktionen -- Comprehensive Error Handling -- Docstrings für alle Funktionen -- Clean Code und Modularität -- Security Best Practices - -Beginne mit der Implementierung! -``` - -### Schritt 4: Iteratives Entwickeln - -Claude Code wird Schritt für Schritt: - -1. **Struktur erstellen** - - Alle Verzeichnisse anlegen - - Basis-Dateien erstellen - - Dependencies auflisten - -2. **Backend implementieren** - - Database Models - - API Routers - - Services - - Utils - -3. **Templates erstellen** - - docker-compose.yml.j2 - - management.json.j2 - - relay.env.j2 - -4. **Frontend bauen** - - HTML Dashboard - - CSS Styling - - JavaScript Logic - -5. **Testen & Debugging** - - Unit Tests - - Integration Tests - - Manuelle Tests - -### Schritt 5: Spezifische Anweisungen - -Du kannst Claude Code auch spezifische Aufgaben geben: - -``` -"Implementiere jetzt den docker_service.py mit allen Funktionen -zum Starten, Stoppen und Überwachen von Docker-Containern" -``` - -``` -"Erstelle das Frontend Dashboard mit Bootstrap 5 und mache es -responsive für Mobile/Tablet/Desktop" -``` - -``` -"Füge comprehensive Error Handling zum Deployment-Prozess hinzu -mit automatischem Rollback bei Fehlern" -``` - -### Schritt 6: Code Review - -Nach jeder größeren Implementierung: - -``` -"Bitte reviewe den Code in app/services/docker_service.py und -verbessere Error Handling und füge Type Hints hinzu" -``` - -### Schritt 7: Testing - -``` -"Erstelle Unit Tests für alle Services und API-Endpunkte" -``` - -### Schritt 8: Dokumentation - -``` -"Erstelle API-Dokumentation und ergänze die README mit -Deployment-Beispielen" -``` - -## Tipps für effektive Zusammenarbeit mit Claude Code - -### ✅ Gute Anweisungen: -- "Implementiere X gemäß der Spezifikation in CLAUDE_CODE_SPEC.md" -- "Füge Error Handling für Y hinzu" -- "Refactore Z für bessere Wartbarkeit" -- "Erstelle Tests für Modul A" - -### ❌ Vermeiden: -- Zu vage Anweisungen ohne Kontext -- Mehrere komplexe Aufgaben gleichzeitig -- Widersprüchliche Requirements - -## Debugging mit Claude Code - -``` -"Der Deployment-Prozess schlägt fehl mit diesem Fehler: [Fehlermeldung]. -Bitte analysiere das Problem und fixe es." -``` - -``` -"Die NPM-Integration funktioniert nicht. Logs zeigen: [Logs]. -Was ist das Problem?" -``` - -## Projekt-Struktur prüfen - -Claude Code kann die Struktur validieren: - -``` -"Überprüfe, ob alle Dateien gemäß CLAUDE_CODE_SPEC.md -vorhanden und korrekt strukturiert sind" -``` - -## Abschließende Checks - -``` -"Führe folgende Checks durch: -1. Alle Dependencies in requirements.txt? -2. Docker-Compose gültig? -3. Alle Environment Variables dokumentiert? -4. README vollständig? -5. Installation Script funktional?" -``` - -## Deployment vorbereiten - -``` -"Bereite das Projekt für Production Deployment vor: -1. Sicherheits-Audit -2. Performance-Optimierungen -3. Logging verbessern -4. Monitoring Endpoints hinzufügen" -``` - ---- - -## Erwartete Entwicklungszeit mit Claude Code - -- **Basis-Struktur**: 10-15 Minuten -- **Backend (APIs + Services)**: 30-45 Minuten -- **Templates**: 10-15 Minuten -- **Frontend**: 30-45 Minuten -- **Tests**: 20-30 Minuten -- **Dokumentation & Polish**: 15-20 Minuten - -**Gesamt: ~2-3 Stunden** für ein vollständiges, produktionsreifes System! - ---- - -## Nach der Entwicklung - -### Lokales Testen: - -```bash -# Docker Compose starten -docker compose up -d - -# Logs prüfen -docker logs -f netbird-msp-appliance - -# In Browser öffnen -http://localhost:8000 -``` - -### Auf VM deployen: - -```bash -# Repository auf VM clonen -git clone https://github.com/yourusername/netbird-msp-appliance.git -cd netbird-msp-appliance - -# Installer ausführen -chmod +x install.sh -sudo ./install.sh -``` - -Viel Erfolg! 🚀