First Project description
This commit is contained in:
459
CLAUDE_CODE_SPEC.md
Normal file
459
CLAUDE_CODE_SPEC.md
Normal file
@@ -0,0 +1,459 @@
|
||||
# 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!
|
||||
240
PROJECT_SUMMARY.md
Normal file
240
PROJECT_SUMMARY.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# 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
Normal file
148
QUICKSTART.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 🚀 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! 🎉
|
||||
519
README.md
519
README.md
@@ -1,2 +1,519 @@
|
||||
# NetBirdMSP-Appliance
|
||||
# NetBird MSP Appliance
|
||||
|
||||
🚀 **Self-Hosted Multi-Tenant NetBird Management Platform**
|
||||
|
||||
A complete management solution for running 100+ isolated NetBird instances for your MSP business. Manage all your customers' NetBird networks from a single, powerful web interface.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📋 Table of Contents
|
||||
|
||||
- [Features](#features)
|
||||
- [Architecture](#architecture)
|
||||
- [System Requirements](#system-requirements)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Configuration](#configuration)
|
||||
- [Usage](#usage)
|
||||
- [API Documentation](#api-documentation)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- **🎯 Multi-Tenant Management**: Manage 100+ isolated NetBird instances from one dashboard
|
||||
- **🔒 Complete Isolation**: Each customer gets their own NetBird instance with separate databases
|
||||
- **🌐 Nginx Proxy Manager Integration**: Automatic SSL certificate management and reverse proxy setup
|
||||
- **🐳 Docker-Based**: Everything runs in containers for easy deployment and updates
|
||||
- **📊 Web Dashboard**: Modern, responsive UI for managing customers and deployments
|
||||
- **🚀 One-Click Deployment**: Deploy new customer instances in under 2 minutes
|
||||
- **📈 Monitoring**: Real-time status monitoring and health checks
|
||||
- **🔄 Automated Updates**: Bulk update NetBird containers across all customers
|
||||
- **💾 Backup & Restore**: Built-in backup functionality for all customer data
|
||||
- **🔐 Secure by Default**: Encrypted credentials, API tokens, and secrets management
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ NetBird MSP Appliance │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌───────────────┐ │
|
||||
│ │ Web GUI │───▶│ FastAPI │──▶│ SQLite DB │ │
|
||||
│ │ (Bootstrap) │ │ Backend │ │ │ │
|
||||
│ └──────────────┘ └──────────────┘ └───────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────────────────┼───────────────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||||
│ │ Docker │ │ NPM │ │ Firewall │ │
|
||||
│ │ Engine │ │ API │ │ Manager │ │
|
||||
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────┴───────────────────┐
|
||||
▼ ▼
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ Customer 1 │ │ Customer 100 │
|
||||
│ ┌────────────┐ │ │ ┌────────────┐ │
|
||||
│ │ Management │ │ │ │ Management │ │
|
||||
│ │ Signal │ │ ... │ │ Signal │ │
|
||||
│ │ Relay │ │ │ │ Relay │ │
|
||||
│ │ Dashboard │ │ │ │ Dashboard │ │
|
||||
│ └────────────┘ │ │ └────────────┘ │
|
||||
└──────────────────┘ └──────────────────┘
|
||||
kunde1.domain.de kunde100.domain.de
|
||||
UDP 3478 UDP 3577
|
||||
```
|
||||
|
||||
### Components per Customer Instance:
|
||||
- **Management Service**: API and network state management
|
||||
- **Signal Service**: WebRTC signaling for peer connections
|
||||
- **Relay Service**: STUN/TURN server for NAT traversal (requires public UDP port)
|
||||
- **Dashboard**: Web UI for end-users
|
||||
|
||||
All services are accessible via HTTPS through Nginx Proxy Manager, except the Relay STUN port which requires direct UDP access.
|
||||
|
||||
---
|
||||
|
||||
## 💻 System Requirements
|
||||
|
||||
### For 100 Customers (10-20 devices per customer)
|
||||
|
||||
| Component | Minimum | Recommended | Notes |
|
||||
|-----------|---------|-------------|-------|
|
||||
| **CPU** | 8 cores | 16 cores | More cores = better concurrent deployment performance |
|
||||
| **RAM** | 64 GB | 128 GB | ~600 MB per customer instance + OS overhead |
|
||||
| **Storage** | 500 GB SSD | 1 TB NVMe SSD | Fast I/O critical for Docker performance |
|
||||
| **Network** | 100 Mbps | 1 Gbps | Dedicated server recommended |
|
||||
| **OS** | Ubuntu 22.04 LTS | Ubuntu 24.04 LTS | Other Debian-based distros work too |
|
||||
|
||||
### Resource Calculation Formula:
|
||||
```
|
||||
Per Customer Instance:
|
||||
- Management: ~100 MB RAM
|
||||
- Signal: ~50 MB RAM
|
||||
- Relay: ~150 MB RAM
|
||||
- Dashboard: ~100 MB RAM
|
||||
Total: ~400-600 MB RAM per customer
|
||||
|
||||
For 100 customers: 40-60 GB RAM + 8 GB for OS + 8 GB for Appliance = ~64 GB minimum
|
||||
```
|
||||
|
||||
### Port Requirements:
|
||||
- **TCP 8000**: NetBird MSP Appliance Web UI
|
||||
- **UDP 3478-3577**: STUN/TURN relay ports (one per customer)
|
||||
- Customer 1: UDP 3478
|
||||
- Customer 2: UDP 3479
|
||||
- ...
|
||||
- Customer 100: UDP 3577
|
||||
|
||||
**⚠️ Important**: Your firewall must allow UDP ports 3478-3577 for full NetBird functionality!
|
||||
|
||||
### Prerequisites:
|
||||
- **Docker Engine** 24.0+ with Docker Compose plugin
|
||||
- **Nginx Proxy Manager** (running separately or on same host)
|
||||
- **Domain with wildcard DNS** (e.g., `*.yourdomain.com` → your server IP)
|
||||
- **Root or sudo access** to the Linux VM
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### 1. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/netbird-msp-appliance.git
|
||||
cd netbird-msp-appliance
|
||||
```
|
||||
|
||||
### 2. Run the Installation Script
|
||||
|
||||
```bash
|
||||
chmod +x install.sh
|
||||
sudo ./install.sh
|
||||
```
|
||||
|
||||
The installer will:
|
||||
- ✅ Check system requirements
|
||||
- ✅ Install Docker if needed
|
||||
- ✅ Create Docker network
|
||||
- ✅ Generate secure secrets
|
||||
- ✅ Build and start all containers
|
||||
- ✅ Initialize the database
|
||||
|
||||
### 3. Complete the Setup Wizard
|
||||
|
||||
Open your browser and navigate to:
|
||||
```
|
||||
http://your-server-ip:8000
|
||||
```
|
||||
|
||||
On first access, you'll be guided through:
|
||||
1. **Admin Account Creation**: Set your admin username and password
|
||||
2. **System Configuration**:
|
||||
- Base Domain (e.g., `yourdomain.com`)
|
||||
- Admin Email
|
||||
- NPM API URL (e.g., `http://npm-host:81/api`)
|
||||
- NPM API Token
|
||||
3. **Firewall Rules**: Instructions for opening required UDP ports
|
||||
|
||||
### 4. Deploy Your First Customer
|
||||
|
||||
1. Click **"New Customer"** button
|
||||
2. Fill in customer details:
|
||||
- Name
|
||||
- Subdomain (e.g., `customer1` → `customer1.yourdomain.com`)
|
||||
- Email
|
||||
- Max Devices
|
||||
3. Click **"Deploy"**
|
||||
4. Wait ~60-90 seconds
|
||||
5. Done! ✅
|
||||
|
||||
The system will automatically:
|
||||
- Assign a unique UDP port for the relay
|
||||
- Generate all config files
|
||||
- Start Docker containers
|
||||
- Create NPM proxy hosts with SSL
|
||||
- Provide the setup URL
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create a `.env` file (or use the one generated by installer):
|
||||
|
||||
```bash
|
||||
# Security
|
||||
SECRET_KEY=your-secure-random-key-here
|
||||
ADMIN_USERNAME=admin
|
||||
ADMIN_PASSWORD=your-secure-password
|
||||
|
||||
# Nginx Proxy Manager
|
||||
NPM_API_URL=http://nginx-proxy-manager:81/api
|
||||
NPM_API_TOKEN=your-npm-api-token
|
||||
|
||||
# System
|
||||
DATA_DIR=/opt/netbird-instances
|
||||
DOCKER_NETWORK=npm-network
|
||||
BASE_DOMAIN=yourdomain.com
|
||||
ADMIN_EMAIL=admin@yourdomain.com
|
||||
|
||||
# NetBird Images (optional - defaults to latest)
|
||||
NETBIRD_MANAGEMENT_IMAGE=netbirdio/management:latest
|
||||
NETBIRD_SIGNAL_IMAGE=netbirdio/signal:latest
|
||||
NETBIRD_RELAY_IMAGE=netbirdio/relay:latest
|
||||
NETBIRD_DASHBOARD_IMAGE=netbirdio/dashboard:latest
|
||||
|
||||
# Database
|
||||
DATABASE_PATH=/app/data/netbird_msp.db
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=INFO
|
||||
```
|
||||
|
||||
### System Configuration via Web UI
|
||||
|
||||
All settings can be configured through the web interface under **Settings** → **System Configuration**:
|
||||
|
||||
- Base Domain
|
||||
- Admin Email
|
||||
- NPM Integration
|
||||
- Docker Images
|
||||
- Port Ranges
|
||||
- Data Directories
|
||||
|
||||
Changes are applied immediately without restart.
|
||||
|
||||
---
|
||||
|
||||
## 📖 Usage
|
||||
|
||||
### Managing Customers
|
||||
|
||||
#### Create a New Customer
|
||||
1. Dashboard → **New Customer**
|
||||
2. Fill in details
|
||||
3. Click **Deploy**
|
||||
4. Share the setup URL with your customer
|
||||
|
||||
#### View Customer Details
|
||||
- Click on customer name in the list
|
||||
- See deployment status, container health, logs
|
||||
- Copy setup URL and credentials
|
||||
|
||||
#### Start/Stop/Restart Containers
|
||||
- Click the action buttons in the customer list
|
||||
- Or use the detail view for more control
|
||||
|
||||
#### Delete a Customer
|
||||
- Click **Delete** → Confirm
|
||||
- All containers, data, and NPM entries are removed
|
||||
|
||||
### Monitoring
|
||||
|
||||
The dashboard shows:
|
||||
- **System Overview**: Total customers, active/inactive, errors
|
||||
- **Resource Usage**: RAM, CPU, disk usage
|
||||
- **Container Status**: Running/stopped/failed
|
||||
- **Recent Activity**: Deployment logs and events
|
||||
|
||||
### Bulk Operations
|
||||
|
||||
Select multiple customers using checkboxes:
|
||||
- **Bulk Update**: Update NetBird images across selected customers
|
||||
- **Bulk Restart**: Restart all selected instances
|
||||
- **Bulk Backup**: Create backups of selected customers
|
||||
|
||||
### Backups
|
||||
|
||||
#### Manual Backup
|
||||
```bash
|
||||
docker exec netbird-msp-appliance python -m app.backup --customer-id 1
|
||||
```
|
||||
|
||||
#### Automatic Backups
|
||||
Configure in Settings → Backup:
|
||||
- Schedule: Daily/Weekly
|
||||
- Retention: Number of backups to keep
|
||||
- Destination: Local path or remote storage
|
||||
|
||||
---
|
||||
|
||||
## 🔌 API Documentation
|
||||
|
||||
The appliance provides a REST API for automation.
|
||||
|
||||
### Authentication
|
||||
```bash
|
||||
# Get API token (after login)
|
||||
curl -X POST http://localhost:8000/api/auth/token \
|
||||
-d "username=admin&password=yourpassword"
|
||||
```
|
||||
|
||||
### API Endpoints
|
||||
|
||||
Full interactive documentation available at:
|
||||
```
|
||||
http://your-server:8000/docs
|
||||
```
|
||||
|
||||
**Common Endpoints:**
|
||||
```
|
||||
POST /api/customers # Create customer + deploy
|
||||
GET /api/customers # List all customers
|
||||
GET /api/customers/{id} # Get customer details
|
||||
PUT /api/customers/{id} # Update customer
|
||||
DELETE /api/customers/{id} # Delete customer
|
||||
|
||||
POST /api/customers/{id}/start # Start containers
|
||||
POST /api/customers/{id}/stop # Stop containers
|
||||
GET /api/customers/{id}/logs # Get container logs
|
||||
GET /api/customers/{id}/health # Health check
|
||||
|
||||
GET /api/status # System status
|
||||
```
|
||||
|
||||
### Example: Create Customer via API
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/customers \
|
||||
-H "Authorization: Bearer YOUR_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Acme Corp",
|
||||
"subdomain": "acme",
|
||||
"email": "admin@acme.com",
|
||||
"max_devices": 20
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### 1. Customer deployment fails
|
||||
**Symptom**: Status shows "error" after deployment
|
||||
|
||||
**Solutions**:
|
||||
- Check Docker logs: `docker logs netbird-msp-appliance`
|
||||
- Verify NPM is accessible: `curl http://npm-host:81/api`
|
||||
- Check available UDP ports: `netstat -ulnp | grep 347`
|
||||
- View detailed logs in the customer detail page
|
||||
|
||||
#### 2. NetBird clients can't connect
|
||||
**Symptom**: Clients show "relay unavailable"
|
||||
|
||||
**Solutions**:
|
||||
- **Most common**: UDP port not open in firewall
|
||||
```bash
|
||||
# Check if port is open
|
||||
sudo ufw status
|
||||
|
||||
# Open the relay port
|
||||
sudo ufw allow 3478/udp
|
||||
```
|
||||
- Verify relay container is running: `docker ps | grep relay`
|
||||
- Test STUN server: Use online STUN tester with your port
|
||||
|
||||
#### 3. NPM integration not working
|
||||
**Symptom**: SSL certificates not created
|
||||
|
||||
**Solutions**:
|
||||
- Verify NPM API token is correct
|
||||
- Check NPM is on same Docker network: `npm-network`
|
||||
- Test NPM API manually:
|
||||
```bash
|
||||
curl -X GET http://npm-host:81/api/nginx/proxy-hosts \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
#### 4. Out of memory errors
|
||||
**Symptom**: Containers crashing, system slow
|
||||
|
||||
**Solutions**:
|
||||
- Check RAM usage: `free -h`
|
||||
- Reduce number of customers or upgrade RAM
|
||||
- Stop inactive customer instances
|
||||
- Configure swap space:
|
||||
```bash
|
||||
sudo fallocate -l 16G /swapfile
|
||||
sudo chmod 600 /swapfile
|
||||
sudo mkswap /swapfile
|
||||
sudo swapon /swapfile
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging:
|
||||
```bash
|
||||
# Edit .env
|
||||
LOG_LEVEL=DEBUG
|
||||
|
||||
# Restart
|
||||
docker-compose restart
|
||||
```
|
||||
|
||||
View detailed logs:
|
||||
```bash
|
||||
docker logs -f netbird-msp-appliance
|
||||
```
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. **Check the logs**: Most issues are explained in the logs
|
||||
2. **GitHub Issues**: Search existing issues or create a new one
|
||||
3. **NetBird Community**: For NetBird-specific questions
|
||||
4. **Documentation**: Read the full docs in `/docs` folder
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Updates
|
||||
|
||||
### Updating the Appliance
|
||||
|
||||
```bash
|
||||
cd netbird-msp-appliance
|
||||
git pull
|
||||
docker-compose down
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
### Updating NetBird Images
|
||||
|
||||
**Via Web UI**:
|
||||
1. Settings → System Configuration
|
||||
2. Update image tags
|
||||
3. Click "Save"
|
||||
4. Use Bulk Update for customers
|
||||
|
||||
**Via CLI**:
|
||||
```bash
|
||||
# Update all customer instances
|
||||
docker exec netbird-msp-appliance python -m app.update --all
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Security Best Practices
|
||||
|
||||
1. **Change default credentials** immediately after installation
|
||||
2. **Use strong passwords** (20+ characters, mixed case, numbers, symbols)
|
||||
3. **Keep NPM API token secure** - never commit to git
|
||||
4. **Enable firewall** and only open required ports
|
||||
5. **Regular updates** - both the appliance and NetBird images
|
||||
6. **Backup regularly** - automate daily backups
|
||||
7. **Use HTTPS** - always access the web UI via HTTPS (configure reverse proxy)
|
||||
8. **Monitor logs** - check for suspicious activity
|
||||
9. **Limit access** - use VPN or IP whitelist for the management interface
|
||||
|
||||
---
|
||||
|
||||
## 📊 Performance Tuning
|
||||
|
||||
### For 100+ Customers:
|
||||
|
||||
```bash
|
||||
# Increase Docker ulimits
|
||||
# Add to /etc/docker/daemon.json
|
||||
{
|
||||
"default-ulimits": {
|
||||
"nofile": {
|
||||
"Name": "nofile",
|
||||
"Hard": 64000,
|
||||
"Soft": 64000
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Restart Docker
|
||||
sudo systemctl restart docker
|
||||
|
||||
# Increase inotify limits
|
||||
echo "fs.inotify.max_user_instances=512" | sudo tee -a /etc/sysctl.conf
|
||||
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
|
||||
sudo sysctl -p
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - see [LICENSE](LICENSE) file for details.
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- **NetBird Team** - for the amazing open-source VPN solution
|
||||
- **FastAPI** - for the high-performance Python framework
|
||||
- **Nginx Proxy Manager** - for easy reverse proxy management
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/yourusername/netbird-msp-appliance/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/netbird-msp-appliance/discussions)
|
||||
- **Email**: support@yourdomain.com
|
||||
|
||||
---
|
||||
|
||||
**Made with ❤️ for MSPs and System Administrators**
|
||||
|
||||
215
VS_CODE_SETUP.md
Normal file
215
VS_CODE_SETUP.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# 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! 🚀
|
||||
BIN
netbird-msp-appliance.tar.gz
Normal file
BIN
netbird-msp-appliance.tar.gz
Normal file
Binary file not shown.
Reference in New Issue
Block a user