BurgerGames/NetBirdMSP-Appliance
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add i18n, branding, user management, health checks, and cleanup for deployment

Browse Source 
- Multi-language support (EN/DE) with i18n engine and language files
- Configurable branding (name, subtitle, logo) in Settings
- Global default language and per-user language preference
- User management router with CRUD endpoints
- Customer status sync on start/stop/restart
- Health check fixes: derive status from container state, remove broken wget healthcheck
- Caddy reverse proxy and dashboard env templates for customer stacks
- Updated README with real hardware specs, prerequisites, and new features
- Removed .claude settings (JWT tokens) and build artifacts from tracking
- Updated .gitignore for .claude/ and Windows artifacts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Sascha Lustenberger
2026-02-08 17:24:05 +01:00
parent c4d68db2f4
commit 41ba835a99
28 changed files with 2550 additions and 661 deletions
Download Patch File Download Diff File Expand all files Collapse all files

506
README.md
View File

@@ -1,8 +1,8 @@
# NetBird MSP Appliance
🚀 **Self-Hosted Multi-Tenant NetBird Management Platform**
**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.
A management solution for running isolated NetBird instances for your MSP business. Manage all your customers' NetBird networks from a single web interface.
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Docker](https://img.shields.io/badge/docker-required-blue.svg)
@@ -10,123 +10,173 @@ A complete management solution for running 100+ isolated NetBird instances for y
---
## 📋 Table of Contents
## Table of Contents
- [Features](#features)
- [Architecture](#architecture)
- [System Requirements](#system-requirements)
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Usage](#usage)
- [API Documentation](#api-documentation)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [Updates](#updates)
- [Security Best Practices](#security-best-practices)
- [License](#license)
---
## ✨ Features
## 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
### Core
- **Multi-Tenant Management** — Deploy and manage isolated NetBird instances per customer
- **Complete Isolation** — Each customer gets their own NetBird stack with separate data
- **One-Click Deployment** — Deploy new customer instances in under 2 minutes
- **Nginx Proxy Manager Integration** — Automatic SSL certificates and reverse proxy setup
- **Docker-Based** — Everything runs in containers for easy deployment
### Dashboard
- **Modern Web UI** — Responsive Bootstrap 5 interface
- **Real-Time Monitoring** — Container status, health checks, resource usage
- **Container Logs** — View logs per container directly in the browser
- **Start / Stop / Restart** — Control customer instances from the dashboard
- **Customer Status Tracking** — Automatic status sync (active / inactive / error)
### Multi-Language (i18n)
- **English and German** — Full UI translation
- **Global Default Language** — Set a system-wide default language in Settings > Branding
- **Per-User Language** — Each user can have their own preferred language
- **Language Priority** — User preference > System default > Browser language
### Customization
- **Branding** — Configure platform name, subtitle, and logo via Settings
- **Login Page** — Branding is applied to the login page automatically
- **Configurable Docker Images** — Use custom or specific NetBird image versions
### Security
- **JWT Authentication** — Token-based API authentication
- **Azure AD / OIDC** — Optional single sign-on via Microsoft Entra ID
- **Encrypted Credentials** — NPM passwords and relay secrets are Fernet-encrypted
- **User Management** — Create, edit, and delete admin users
---
## 🏗️ Architecture
## 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
+-------------------------------------------------------------+
| NetBird MSP Appliance |
| |
| +--------------+ +--------------+ +---------------+ |
| | Web GUI |--->| FastAPI |-->| SQLite DB | |
| | (Bootstrap) | | Backend | | | |
| +--------------+ +--------------+ +---------------+ |
| | |
| +-------------------+-------------------+ |
| v v v |
| +-------------+ +-------------+ +---------------+ |
| | Docker | | NPM | | Template | |
| | Engine | | API | | Renderer | |
| +-------------+ +-------------+ +---------------+ |
+-------------------------------------------------------------+
|
+-------------------+-------------------+
v v
+------------------+ +------------------+
| Customer 1 | | Customer N |
| +------------+ | | +------------+ |
| | Management | | | | Management | |
| | Signal | | ... | | Signal | |
| | Relay | | | | Relay | |
| | Dashboard | | | | Dashboard | |
| | Caddy | | | | Caddy | |
| +------------+ | | +------------+ |
+------------------+ +------------------+
kunde1.domain.de kundeN.domain.de
UDP 3478 UDP 3478+N-1
```
### 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
### Components per Customer Instance (5 containers):
- **Management** — API and network state management
- **Signal** — WebRTC signaling for peer connections
- **Relay** — STUN/TURN server for NAT traversal (requires public UDP port)
- **Dashboard** — Web UI for end-users
- **Caddy** — Reverse proxy / entry point for the customer stack
All services are accessible via HTTPS through Nginx Proxy Manager, except the Relay STUN port which requires direct UDP access.
---
## 💻 System Requirements
## System Requirements
### For 100 Customers (10-20 devices per customer)
### Hardware Scaling
| 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 |
Based on real-world measurements: **2 customers (11 containers) use ~220 MB RAM**.
### 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
Per customer instance (5 containers): **~100 MB RAM**
For 100 customers: 40-60 GB RAM + 8 GB for OS + 8 GB for Appliance = ~64 GB minimum
```
| Customers | Container RAM | Recommended Total | vCPU | Storage |
|-----------|--------------|-------------------|------|---------|
| 10 | ~1.0 GB | 2 GB | 2 | 20 GB |
| 25 | ~2.5 GB | 4 GB | 2 | 50 GB |
| 50 | ~5.0 GB | 8 GB | 4 | 100 GB |
| 100 | ~10.0 GB | 16 GB | 8 | 200 GB |
| 200 | ~20.0 GB | 32 GB | 16 | 500 GB |
### 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
> **Note:** "Recommended Total" includes OS overhead and headroom. SSD/NVMe storage is recommended for Docker performance.
**⚠️ Important**: Your firewall must allow UDP ports 3478-3577 for full NetBird functionality!
### Port Requirements
### 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
| Port | Protocol | Purpose |
|------|----------|---------|
| 8000 | TCP | NetBird MSP Appliance Web UI |
| 3478+ | UDP | STUN/TURN relay (one per customer) |
Example: Customer 1 = UDP 3478, Customer 2 = UDP 3479, ..., Customer 100 = UDP 3577.
**Your firewall must allow the UDP relay ports for NetBird to function!**
---
## 🚀 Quick Start
## Prerequisites
The following tools and services must be available **before** running the installer.
### Required on the Host
| Tool | Purpose | Check Command |
|------|---------|---------------|
| **Linux OS** | Ubuntu 22.04+, Debian 12+, or similar | `cat /etc/os-release` |
| **sudo / root** | Installation requires root privileges | `sudo -v` |
| **curl** | Used by the installer to install Docker | `curl --version` |
| **git** | Clone the repository | `git --version` |
| **openssl** | Generate encryption keys during install | `openssl version` |
### Installed Automatically
| Tool | Purpose | Notes |
|------|---------|-------|
| **Docker Engine** 24.0+ | Container runtime | Installed by `install.sh` if missing |
| **Docker Compose Plugin** | Multi-container orchestration | Installed with Docker |
### External Services
| Service | Purpose | Notes |
|---------|---------|-------|
| **Nginx Proxy Manager** | Reverse proxy + SSL certificates | Must be running and accessible from the host. Can be on the same server or a separate one. |
| **Wildcard DNS** | Route `*.yourdomain.com` to the server | Configure `*.yourdomain.com` as an A record pointing to your server IP |
### Install Prerequisites (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install -y curl git openssl
```
---
## Quick Start
### 1. Clone the Repository
@@ -143,23 +193,23 @@ sudo ./install.sh
```
The installer will **interactively ask you** for:
- ✅ Admin username and password
- ✅ Admin email address
- ✅ Base domain (e.g., `yourdomain.com`)
- ✅ Nginx Proxy Manager API URL and token
- ✅ Data directory location
- ✅ NetBird Docker images (optional customization)
- Admin username and password
- Admin email address
- Base domain (e.g., `yourdomain.com`)
- Nginx Proxy Manager API URL, email, and password
- Data directory location
- NetBird Docker images (optional customization)
**No manual .env file editing required!** Everything is configured through the installation wizard.
**No manual .env file editing required!** All configuration is stored in the database and editable via the Web UI.
The installer will then:
- ✅ Check system requirements
- ✅ Install Docker if needed
- ✅ Create directories and Docker network
- ✅ Generate encryption keys
- ✅ Build and start all containers
- ✅ Configure firewall (optional)
- ✅ Initialize the database
- Check system requirements
- Install Docker if needed
- Create directories and Docker network
- Generate encryption keys
- Build and start all containers
- Seed configuration into the database
- Optionally configure the firewall (ufw)
### 3. Access the Web Interface
@@ -170,85 +220,61 @@ http://your-server-ip:8000
Login with the credentials you provided during installation.
**All settings can be changed later via the Web UI!**
### 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
2. Fill in customer details (name, subdomain, email, max devices)
3. Click **"Deploy"**
4. Wait ~60-90 seconds
5. Done! ✅
5. Done!
The system will automatically:
- Assign a unique UDP port for the relay
- Generate all config files
- Start Docker containers
- Generate all config files from templates
- Start the 5 Docker containers
- Create NPM proxy hosts with SSL
- Provide the setup URL
- Provide the setup URL for the customer
---
## ⚙️ Configuration
## Configuration
### Environment Variables
Create a `.env` file (or use the one generated by installer):
The installer generates a minimal `.env` file with container-level variables only:
```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
SECRET_KEY=<auto-generated>
DATABASE_PATH=/app/data/netbird_msp.db
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
WEB_UI_PORT=8000
```
### System Configuration via Web UI
> **All application settings** (domain, NPM credentials, Docker images, branding, etc.) are stored in the SQLite database and editable via the Web UI under **Settings**.
All settings can be configured through the web interface under **Settings** → **System Configuration**:
### Web UI Settings
- Base Domain
- Admin Email
- NPM Integration
- Docker Images
- Port Ranges
- Data Directories
Available under **Settings** in the web interface:
| Tab | Settings |
|-----|----------|
| **System** | Base domain, admin email, NPM credentials, Docker images, port ranges, data directory |
| **Branding** | Platform name, subtitle, logo upload, default language |
| **Users** | Create/edit/delete admin users, per-user language preference |
| **Monitoring** | System resources, Docker stats |
Changes are applied immediately without restart.
---
## 📖 Usage
## Usage
### Managing Customers
#### Create a New Customer
1. Dashboard → **New Customer**
1. Dashboard > **New Customer**
2. Fill in details
3. Click **Deploy**
4. Share the setup URL with your customer
@@ -258,56 +284,42 @@ Changes are applied immediately without restart.
- 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
#### Start / Stop / Restart Containers
- Use the action buttons in the customer detail view
- Stopping all containers sets the customer status to "inactive"
- Starting containers sets the status back to "active"
#### Delete a Customer
- Click **Delete** → Confirm
- 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
- **System Overview** — Total customers, active/inactive, errors
- **Resource Usage** — RAM, CPU per container
- **Container Health** — Running/stopped per container with color-coded status
- **Deployment Logs** — Action history per customer
### Bulk Operations
### Language Settings
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
- **Switch language** — Use the language switcher in the top navigation bar
- **Per-user default** — Set in Settings > Users during user creation
- **System default** — Set in Settings > Branding
---
## 🔌 API Documentation
## API Documentation
The appliance provides a REST API for automation.
The appliance provides a REST API.
### Authentication
```bash
# Get API token (after login)
curl -X POST http://localhost:8000/api/auth/token \
-d "username=admin&password=yourpassword"
```
### API Endpoints
### Endpoints
Full interactive documentation available at:
```
@@ -324,10 +336,14 @@ DELETE /api/customers/{id} # Delete customer
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
GET /api/status # System status
GET /api/settings/branding # Get branding (public, no auth)
PUT /api/settings # Update system settings
GET /api/users # List users
POST /api/users # Create user
```
### Example: Create Customer via API
@@ -345,134 +361,96 @@ curl -X POST http://localhost:8000/api/customers \
---
## 🔧 Troubleshooting
## Troubleshooting
### Common Issues
#### 1. Customer deployment fails
### 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
- Verify NPM is accessible from the appliance container
- Check available UDP ports: `ss -ulnp | grep 347`
- View detailed logs in the customer detail page (Logs tab)
#### 2. NetBird clients can't connect
### 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
### NPM integration not working
**Symptom**: Proxy hosts or 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
```
- Verify NPM email and password are correct in Settings
- Check NPM is on same Docker network (`npm-network`)
- Check NPM logs for errors
### Debug Mode
Enable debug logging:
```bash
# Edit .env
# In your .env file:
LOG_LEVEL=DEBUG
# Restart
docker-compose restart
# Restart the appliance:
docker compose restart
```
View detailed logs:
View 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
## Updates
### Updating the Appliance
```bash
cd netbird-msp-appliance
cd /opt/netbird-msp
git pull
docker-compose down
docker-compose up -d --build
docker compose down
docker compose up -d --build
```
The database migrations run automatically on startup.
### Updating NetBird Images
**Via Web UI**:
1. Settings → System Configuration
2. Update image tags
Via the Web UI:
1. Settings > System Configuration
2. Change image tags (e.g., `netbirdio/management:0.35.0`)
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
```
4. Re-deploy individual customers to apply the new images
---
## 🛡️ Security Best Practices
## 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
2. **Use strong passwords** (12+ characters recommended)
3. **Keep NPM credentials secure** — they are stored encrypted in the database
4. **Enable firewall** and only open required ports (TCP 8000, UDP relay range)
5. **Use HTTPS** — put the MSP appliance behind a reverse proxy with SSL
6. **Regular updates** — both the appliance and NetBird images
7. **Backup your database** — `data/netbird_msp.db` contains all configuration
8. **Monitor logs** — check for suspicious activity
9. **Restrict access** — use VPN or IP whitelist for the management interface
---
## 📊 Performance Tuning
## Performance Tuning
### For 100+ Customers:
### For 100+ Customers
```bash
# Increase Docker ulimits
# Add to /etc/docker/daemon.json
# Increase Docker ulimits — add to /etc/docker/daemon.json
{
"default-ulimits": {
"nofile": {
@@ -494,32 +472,14 @@ sudo sysctl -p
---
## 🤝 Contributing
## License
Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
MIT License — see [LICENSE](LICENSE) file for details.
---
## 📄 License
## Acknowledgments
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**
- [NetBird](https://netbird.io/) — Open-source VPN solution
- [FastAPI](https://fastapi.tiangolo.com/) — High-performance Python framework
- [Nginx Proxy Manager](https://nginxproxymanager.com/) — Reverse proxy management