Remove dev docs from tracking and add to .gitignore
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
4
.gitignore
vendored
4
.gitignore
vendored
@@ -64,6 +64,10 @@ htmlcov/
|
||||
|
||||
# Claude Code
|
||||
.claude/
|
||||
CLAUDE_CODE_SPEC.md
|
||||
PROJECT_SUMMARY.md
|
||||
QUICKSTART.md
|
||||
VS_CODE_SETUP.md
|
||||
|
||||
# Windows artifacts
|
||||
nul
|
||||
|
||||
@@ -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!
|
||||
@@ -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*
|
||||
148
QUICKSTART.md
148
QUICKSTART.md
@@ -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: <get from NPM interface>
|
||||
```
|
||||
|
||||
### 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 <npm-container-name>
|
||||
```
|
||||
|
||||
### Ports already in use
|
||||
```bash
|
||||
# Check what's using port 8000
|
||||
sudo lsof -i :8000
|
||||
|
||||
# Kill process if needed
|
||||
sudo kill -9 <PID>
|
||||
```
|
||||
|
||||
## 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! 🎉
|
||||
215
VS_CODE_SETUP.md
215
VS_CODE_SETUP.md
@@ -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! 🚀
|
||||
Reference in New Issue
Block a user