Documentation - UnifiedBGM Server Management Panel

Overview

UnifiedBGM turns Tencent Cloud CVM into a powerful server management appliance. The built-in WiFi (wlan0) runs as an access point (UnifiedBGM-AP), while an optional USB WiFi adapter can bridge or extend to an upstream network for internet access.

The panel provides real-time monitoring, per-device internet access control, WireGuard VPN management, firewall rules, Docker container monitoring, HIPAA-compliant audit logging, session security with single-session enforcement, file management, and a built-in web terminal — all secured with role-based access control.

Architecture

Hardware	Tencent Cloud CVM, 15.1GB RAM
OS	Ubuntu 24.04.4 LTS (x86_64)
WiFi AP Interface	`eth0` — AP mode, SSID: UnifiedBGM-AP
AP Software	hostapd (WPA2, Channel auto, HT20, 802.11n)
DHCP Server	dnsmasq — 10.253.92.107 to 10.253.92.1007
Web Panel	Flask 3.0 + Flask-SocketIO, Python 3.12, Port 8080
VPN	WireGuard / Headscale (optional)
Audit Database	SQLite (WAL mode) — 90-day TTL
Hostname	`rpp-bma`

Features

Dashboard Real-time network topology, bridge status, device count, VPN, WiFi config at a glance

Device Management See all connected clients with hostname, IP, MAC, signal strength, traffic

Network Management Server IP, DHCP config, local domain, host directory, DHCP leases viewer

WiFi Bridge NAT bridge mode — clients on 192.168.4.x, internet via upstream WiFi

WiFi Extender Transparent relay — clients get upstream IPs, extends WiFi range

WireGuard VPN Full VPN server/client management with QR codes for mobile setup

Firewall Custom iptables rules, per-device internet allow/deny control

Internet Access Grant or revoke internet per device with one click

Docker Monitoring Real-time container stats via WebSocket, start/stop/restart, resource tuning

File Manager Web-based file upload/download/rename/delete with drag-and-drop

Web Terminal Full SSH terminal in the browser — admin only

System Logs Live logs: hostapd, dnsmasq, iptables, WireGuard, bridge, panel, Docker

HIPAA Audit Log 90-day retention SQLite audit trail — filterable, exportable CSV

Session Security Idle timeout, single-session per user, real-time kicked-session alerts

User Profile & Avatar Profile photo upload, password change, per-user customization

Telegram Notifications Bot integration for server alerts and monitoring notifications

Cloudflare Tunnel Expose the panel securely to the internet — no port forwarding

Mobile Responsive Hamburger menu sidebar, works on phones and tablets

Headscale VPN Self-hosted mesh VPN — node status, ping, pre-auth keys, route controls

Packet Sniffer Real-time packet capture with BPF filters, PCAP export for Wireshark

App Detection DNS-based application identification — see what apps devices are using

Docker Deploy Deploy containers and Compose stacks with a guided web interface

OTA Updates Push panel updates to remote servers via SSH — base/client role support

Dashboard

The dashboard provides a live overview in 5 sections:

Network Topology — Animated diagram showing the full traffic path (Internet → Router → Pi → AP → Clients) with real-time data rates
Connected Devices — All clients on UnifiedBGM-AP with hostname resolution (4 fallback methods)
Devices with Network Access — Devices that have been granted internet access
Bridge/Extender Status — Upstream connection, signal strength, mode
WiFi Configuration — Current AP settings (SSID, channel, security)

The dashboard auto-refreshes every 5 seconds via the /api/clients endpoint.

Device Management

The Clients page shows all WiFi clients connected to UnifiedBGM-AP. For each device:

Hostname — Resolved using 4 fallback methods: reverse DNS → NetBIOS → mDNS → MAC OUI vendor lookup
IP Address — DHCP lease from 192.168.4.10–100 (bridge mode) or upstream DHCP (extender mode)
MAC Address — Hardware identifier; randomized MACs shown with vendor prefix
Signal / TX Rate — WiFi signal strength and link speed

The Static Hosts page allows assigning fixed DHCP leases to specific MAC addresses.

Network Management

The Network page provides centralized management of the server's core network configuration:

Server IP & Netmask — Change the AP interface IP address and subnet mask
DHCP Configuration — Set DHCP range start/end, lease time, and DNS servers
Local Domain — Configure a local domain name (e.g., unifiedbgm.local) for the network
Network Host Directory — Add/remove custom DNS entries for local hosts
DHCP Leases — View all active DHCP leases with MAC, IP, hostname, and expiry time

Changing the server IP or DHCP configuration will restart dnsmasq and may briefly disconnect clients.

WiFi Bridge & Extender

A USB WiFi adapter enables the Pi to connect to an upstream WiFi network while simultaneously running UnifiedBGM-AP. Two modes are available:

BRIDGE MODE

NAT Routing

Clients stay on 192.168.4.x
Internet via NAT (MASQUERADE)
Network isolation from upstream
Pi firewall controls apply
Best for: managed/controlled access

EXTENDER MODE

Transparent Relay (parprouted)

Clients get upstream IPs (same subnet)
Transparent ARP proxy relay
No NAT — seamless roaming
Extends WiFi coverage area
Best for: range extension

In Extender mode, the Pi's dnsmasq DHCP server is stopped. Clients receive IPs from the upstream router. Existing clients should reconnect after switching modes.

WireGuard VPN

The VPN page provides full WireGuard management:

Server Mode — Run a WireGuard VPN server on the Pi; add peers with auto-generated configs and QR codes
Client Mode — Connect the Pi as a VPN client to a remote WireGuard server
Peer Management — Add, remove, and view connected peers with handshake status

Scan the QR code from the WireGuard mobile app (iOS/Android) for instant setup.

Firewall & Internet Access

Firewall lets you create custom iptables rules (protocol, port, source, action). Rules are stored in /opt/smartbgm-panel/firewall_rules.json.

Internet Access provides one-click per-device internet control. Allowed devices are tracked in /opt/smartbgm-panel/internet_access.json and managed via the SMARTBGM_INET iptables chain.

By default, new devices have no internet access. An admin must explicitly grant it.

Logs & Terminal

The Logs page has tabbed log viewers for system services (hostapd, dnsmasq, Panel, Internet, WireGuard, Bridge) plus auto-generated tabs for each Docker container. Logs auto-refresh every 5 seconds and support keyword filtering.

The Web Terminal (admin only) provides a full interactive shell in the browser. You can open multiple floating terminal dialogs on the page, or Open New Window for a standalone popup session (each session is independent). It uses a real PTY via WebSocket — same as SSH, but directly in the panel.

The terminal runs as root. Use with caution — commands execute directly on the server.

Docker Monitoring

The Docker page displays all containers with real-time resource usage via WebSocket (SocketIO /docker namespace). Stats push every ~3 seconds — no polling required.

Aggregate Resource Cards

Total CPU % — combined CPU across all running containers with progress bar
Total Memory — combined usage / limit with percentage bar
Network I/O — aggregate RX (download) and TX (upload) totals
Block I/O — aggregate disk read / write totals

CPU & Memory History Charts

Chart.js line graphs plot the last 60 data points (~3 min) of aggregate CPU% and Memory%.

Per-Container Cards

Container cards — name, image, state badge, uptime
Live metrics — CPU%, memory usage with progress bar, network I/O
Actions (admin) — start, stop, restart containers
Log viewer — view last 50–500 lines per container in a modal
Docker logs in Logs page — each container gets its own tab with syntax highlighting

Live Connection Indicator

A pulsing green Live badge shows active WebSocket status. Turns red Disconnected if the connection drops.

Docker monitoring is only shown when Docker is installed. If Docker is not found, the nav link redirects to the dashboard.

Docker Resource Tuning

Administrators can inspect and adjust container resource limits (memory, swap, CPU) directly from the Docker page. Changes are applied immediately via docker update — no container restart required.

How to Use

Navigate to Docker Containers from the sidebar
Click the sliders icon () on any container card
The modal shows current resource limits pre-filled in the form
Adjust values and click Apply Changes

Tunable Resources

Memory Limit (MB) — hard memory cap; minimum 6 MB or 0 for unlimited
Memory + Swap (MB) — combined memory+swap limit; -1 for unlimited swap
Memory Reservation (MB) — soft limit for graceful reclaim under pressure
CPUs — CPU count (e.g. 0.5 = half a core, 2 = two cores); 0 for unlimited
CPU Shares — relative weight for CPU scheduling; default 1024

API Endpoints

Endpoint	Method	Auth	Description
`/api/docker/resources/<name>`	GET	login	Returns current memory/CPU limits for a container
`/docker/resources`	POST	admin	Updates container resource limits via `docker update`

The aggregate Docker memory percentage is calculated as total container usage ÷ host RAM, giving accurate values instead of summing per-container percentages.

File Manager

The Files page provides a web-based file manager for uploading, downloading, and organizing files stored on the Raspberry Pi at /opt/smartbgm-panel/files/.

Browse — navigate folders with breadcrumb navigation
Upload — drag-and-drop or click-to-browse with real-time progress bars (max 200 MB per file)
Download — click the download icon on any file
New Folder — create sub-directories for organization (admin)
Rename — rename files or folders inline (admin)
Delete — delete single items or bulk-select multiple items (admin)
File icons — color-coded icons for images, code, archives, documents, and generic files

Viewers can browse and download files. Only admins can upload, create folders, rename, or delete.

System Performance

Real-time system performance graphs appear on Dashboard, Logs, and Terminal pages. Powered by psutil with 5-second refresh intervals.

CPU — usage percentage, core count, system load average
RAM — usage percentage, used / total memory
Disk — usage percentage, used / total disk space
Network per interface — separate RX/TX throughput graphs for each interface:
- eth0 (LAN) — wired Ethernet
- wlan0 (AP) — WiFi access point
- wlx… (USB WiFi) — bridge adapter (when connected)

Each graph maintains a rolling 60-point history (~5 minutes). Network charts show dual lines — solid for download (RX), dashed for upload (TX).

HIPAA Audit Log

The Audit Log page (admin only) provides a HIPAA-compliant audit trail of all critical actions performed in the panel. Data is stored in an SQLite database (/opt/smartbgm-panel/audit_log.db) using WAL mode.

What Gets Logged

Over 40 action types across these categories:

Category	Actions
auth	Login (success/failure), Logout, Session expired, Session kicked
user_mgmt	User created, deleted, edited
profile	Password changed, Avatar uploaded/removed
network	Server IP, DHCP config, local domain, host add/remove, client kicked, MAC filter, static IPs
firewall	Rule added, removed, toggled
vpn	Server/client configured, peer add/remove/toggle, VPN start/stop/reset
bridge	Adapter switched, bridge connected/disconnected
docker	Container start/stop/restart
file	File upload, folder created, file delete/rename/chmod
config	WiFi settings, Telegram config, captive portal, Cloudflare tunnel, session config
system	System reboot, shutdown

Features

90-Day Retention — Entries older than 90 days are automatically purged daily
Filterable — Filter by category, user, status, date range, or keyword search
Paginated — 25 entries per page with smart page navigation
CSV Export — Download the full audit trail as a CSV file
Stats Dashboard — Total events, today's count, failed actions, category breakdown

Each audit entry records: timestamp (UTC), username, role, IP address, category, action, detail, status, and user-agent.

Session Security

The panel enforces strict session management for security:

Idle Timeout

Sessions automatically expire after a configurable idle period (default: 60 minutes)
Configurable in Settings → Session Security (range: 5–1440 minutes)
Every request updates the last_activity timestamp
Expired sessions are logged in the audit trail

Single Session Per User

Only one active session per username at any time
When the same user logs in from another browser/device, the previous session is immediately invalidated
The existing session receives a real-time overlay dialog: "Your account has been logged in from another location"
Session validity is polled every 5 seconds via /api/session/check
A unique session token is generated on each login and tracked in memory

Cookie Security

HttpOnly — Prevents JavaScript access to session cookie
SameSite=Lax — Prevents CSRF attacks

User Profile & Avatar

Each user can customize their profile from the top-right avatar menu:

Avatar Photo — Upload a profile picture (displayed in the sidebar and top bar)
Change Password — Update your password (minimum 8 characters, requires current password)
Remove Avatar — Reset to the default initial icon

Avatars are stored in /opt/smartbgm-panel/avatars/ and served at /avatars/<filename>. Uploads are limited to common image formats (PNG, JPG, GIF, WebP) with size validation.

Telegram Notifications

In Settings → Telegram Notifications, configure a Telegram bot to receive server alerts:

Bot Token — Get from @BotFather
Chat ID — Your Telegram chat or group ID
Enable/Disable — Toggle notifications on or off
Test Message — Send a test notification with server info (hostname, IPs, bridge status, version)

Automatic Notification Triggers

When enabled, Telegram alerts are sent automatically for the following events:

Event	Trigger	Details Included
Panel Online	Panel service starts up	Hostname, LAN IPs, internet IP, NAT mode, bridge status, version, uptime
Headscale VPN Connected	Successfully joined Headscale mesh	Hostname, server URL, assigned Headscale IP
Headscale VPN Disconnected	Manually disconnected from Headscale	Hostname, previous Headscale IP
WireGuard VPN Started	WireGuard interface brought up	Hostname, mode (Server/Client), VPN address
WireGuard VPN Stopped	WireGuard interface brought down	Hostname, mode (Server/Client)
WireGuard Peer Connected	New peer handshake detected (server mode, polled every 30s)	Hostname, peer endpoint
WiFi Bridge Lost	Bridge watchdog detects WiFi connection dropped	Hostname, AP SSID, interface
Internet Reconnected	Bridge watchdog successfully reconnects to same AP	Hostname, bridge SSID, IP, signal, internet IP, NAT mode, cause scenario, resumed by action
WiFi Bridge Fallback	Bridge watchdog falls back to a different saved AP	Original AP, new AP SSID, IP, signal, internet IP, cause, resumed by
All Networks Failed	Watchdog tried all saved networks but none connected	Hostname, tried SSIDs, cause scenario, retry interval
Admin Timeout Auto-Reconnect	Admin disconnected bridge but forgot to reconnect (5min timer)	Hostname, SSID, IP, cause, resumed by
Docker Container Down	Running container state changes to non-running (polled every 30s)	Hostname, container name, state transition
Docker Container Up	Non-running container transitions back to running	Hostname, container name, state transition

All messages include the server hostname and timestamp. Background watchers (Docker, WireGuard peers, bridge) poll every 30 seconds. Recovery messages include Cause (what triggered the disconnect) and Resumed by (what action restored it). All bridge events are logged to the Activity Log.

Cloudflare Tunnel

In Settings → Cloudflare Tunnel, you can securely expose the panel to the internet without port forwarding using cloudflared:

Setup Process

Authenticate — Login to your Cloudflare account (domain must already be added to Cloudflare)
Configure DNS — Enter the subdomain for your tunnel (e.g., panel.yourdomain.com)
Start Tunnel — Launch the tunnel; Cloudflare automatically creates the DNS record

Controls

Start / Stop / Restart — Manage the tunnel process
Destroy — Remove the tunnel configuration entirely
Status Badge — Shows Running (green), Stopped (red), or Not Configured
Recent Logs — View the last cloudflared log output

The Cloudflare tunnel requires cloudflared to be installed on the server. Authentication happens via browser redirect.

Headscale VPN

The Headscale page manages a self-hosted mesh VPN — an open-source, self-hosted alternative to Tailscale's control server. This allows secure peer-to-peer connectivity between all UnifiedBGM servers across different networks without port forwarding.

Connection Management

VPS Configuration — Set Headscale server address, API key, and SSH credentials
Connect / Disconnect — Join or leave the Headscale mesh network with one click
Start Daemon — Start the local Tailscale daemon if not running
Node Status — View all registered nodes with online/offline status, IP addresses, and last seen time

Admin Features

Pre-Auth Keys — Create reusable or one-time keys for onboarding new nodes
Ping — Test connectivity to any node in the mesh network
Route & ACL Controls — Manage advertised routes and access control policies

Network Info

Headscale IP — Assigned mesh IP (e.g., 100.64.0.x)
LAN IP — Local network address
External IP — Public-facing IP address

Headscale requires a VPS running the Headscale server (Docker recommended). Nodes connect using the Tailscale client with --login-server pointed to your VPS.

Packet Sniffer

The Packet Sniffer page provides real-time network packet capture directly from the browser using tcpdump with WebSocket streaming.

Interface Selection — Choose any network interface (wlan0, eth0, etc.) to capture on
BPF Filters — Apply Berkeley Packet Filter expressions to narrow capture scope
Live Streaming — Packets stream to the browser in real-time via SocketIO /sniffer namespace
Packet Count — Set capture limit or run continuously
PCAP Export — Optionally save captures as .pcap files for analysis in Wireshark
PCAP Management — Download or delete saved capture files

Packet capture runs as root and can capture sensitive network traffic. Use responsibly and only on networks you are authorized to monitor.

App Detection

The App Detection page identifies applications and services in use on the network by analyzing DNS queries from connected devices.

Start / Stop — Toggle DNS-based application detection monitoring
Live Results — View detected apps and services with domain categorization
Device Mapping — See which devices are accessing which applications
Clear History — Reset detection results

App detection works by monitoring DNS queries through dnsmasq. HTTPS-encrypted DNS (DoH) traffic from devices will not be detected.

Docker Deploy

The Docker Deploy page provides a guided interface for deploying Docker containers and managing Docker Compose stacks on the server.

Container Deployment — Deploy containers with custom image, ports, volumes, and environment variables
Compose Support — Upload or paste docker-compose.yml files for multi-container stacks
Template Library — Quick-deploy common services with pre-configured templates

Docker must be installed on the server. The deploy page provides installation guidance if Docker is not found.

OTA Updates

The OTA (Over-The-Air) Updates page enables remote deployment of panel updates to other UnifiedBGM servers across the network.

Server Roles

Base Server — The primary server that pushes updates to other servers
Client Server — Receives updates only; push functionality is disabled (API returns 403)

Push Process

Package is created containing app.py, all templates/, and static/vendor/ assets
Package is transferred via SSH/SCP to target servers
Target server extracts files and restarts the smartbgm-panel service

Version Management

Version Display — Shows current version and checksum (covers app.py, templates, and vendor files)
Server Status — View version info for all configured target servers
Deploy Servers — Configure target servers with hostname, IP (Headscale VPN recommended), and SSH port

Configuration

ota_config.json — Defines server role (base or client) and base server reference
deploy_servers.json — List of target servers for OTA push

Use Headscale VPN IPs (100.64.0.x) for deploy targets to ensure reliable connectivity across different networks.

Bridge vs Extender — Deep Dive

Feature	Bridge Mode (NAT)	Extender Mode (Relay)
Client IP Range	192.168.4.10–100 (Pi's DHCP)	Upstream DHCP (e.g. 10.1.1.x)
DHCP Server	dnsmasq on Pi	Upstream router
Routing Technique	iptables NAT MASQUERADE	parprouted (proxy ARP)
Network Isolation	Yes — separate subnet	No — same subnet
Per-device Internet Control	Yes (via SMARTBGM_INET chain)	Limited (traffic not NATed)
Client Visibility	Clients hidden behind Pi's IP	Clients visible on upstream network
Best Used For	Controlled access, captive portal	WiFi range extension
Throughput	Shared 2.4GHz (reduced)	Shared 2.4GHz (reduced)

Traffic Flow Diagrams

# Bridge Mode (NAT)
Client (192.168.4.x) → wlan0 (AP) → iptables NAT → USB WiFi → Upstream Router → Internet

# Extender Mode (Relay)
Client (upstream IP) → wlan0 (AP) → parprouted → USB WiFi → Upstream Router → Internet

Network Layout

Interface	Role	IP Address	Details
`eth0`	LAN (Ethernet)	10.1.1.163	Management access, wired connection
`wlan0`	WiFi AP	192.168.4.1	UnifiedBGM-AP, hostapd, dnsmasq DHCP
`wlxd037451a0730`	USB WiFi	DHCP from upstream	Bridge/Extender to upstream network
`wg0`	WireGuard VPN	10.0.0.1 (server)	VPN tunnel interface (when active)

# Key paths on the server
/opt/smartbgm-panel/ — Panel application root
/opt/smartbgm-panel/app.py — Main Flask application
/opt/smartbgm-panel/templates/ — HTML templates
/etc/hostapd/hostapd.conf — AP configuration
/etc/dnsmasq.conf — DHCP configuration
/etc/wireguard/ — WireGuard configs

Accessing the Panel

Default Access

Panel URL	`http://192.168.4.1:8080` (from WiFi clients) or `http://10.1.1.163:8080` (from LAN)
SSH Access	`ssh root@10.1.1.163 -p 2222`
WiFi SSID	UnifiedBGM-AP
WiFi Password	`hello@unifiedBGM`

User Roles

Role	Access
ADMIN	Full access — Dashboard, Clients, Network, Firewall, Internet, VPN, Bridge, Docker, Files, Logs, Audit Log, Terminal, Settings
VIEWER	Read-only — Dashboard, Clients, Logs

Commissioning & Deploy

Use these project-root scripts to commission a new Raspberry Pi panel server and push day-2 software updates. Full detail lives in documents/Commissioning-Deploy-Handbook.md.

Script	When	Run from
`deploy.sh`	First-time full commission	Laptop → Pi over SSH
`update-panel.sh`	Day-2 Cloud OTA release (recommended)	Laptop → Cloud OTA
`ota-upload.sh`	Alternate OTA packager (dry-run / version override)	Laptop → Cloud OTA
`headscale-panel/deploy.sh`	Headscale VPN panel on VPS	Laptop → VPS
`lan-import.sh`	smartBGM LAN app import (Docker Compose)	Unified Server → `/opt/smartbgm`
`lan-online-pull.sh`	Cloud pull + deploy LAN bundle	Unified Server → Cloud API

Do not re-run deploy.sh for software updates — it can overwrite config.json and hostapd settings. Use ./update-panel.sh --bump instead.

Fresh Panel Deploy

Prerequisites: fresh Ubuntu 24.04 on Pi 5 with WiFi, root SSH access, run from the project root (directory containing smartbgm-panel/).

./deploy.sh <server_ip> [ssh_port]
# Examples
./deploy.sh 10.1.1.163
./deploy.sh 10.1.1.163 2222

What it configures:

System packages (hostapd, dnsmasq, Flask, WireGuard, iptables, netplan)
Netplan — wlan0 static 192.168.4.1/24, eth0 DHCP; masks wpa_supplicant
WiFi AP — isolated clients (no default gateway by default), DHCP .10–.100
Panel files → /opt/smartbgm-panel/ + hashed admin in config.json
smartbgm-panel.service, 7-day journal retention, ip_forward=0 by default
Starts hostapd → dnsmasq → panel and prints service status

Default SSID	`SmartBGM-AP`
Default WiFi password	`hello@smartBGM`
Default admin	`admin` / `smartbgm2026`
Panel port	`8080`

Change the default admin password immediately after first login. Edit defaults at the top of deploy.sh before site commissioning if needed.

Cloud OTA Updates

After first commission, push panel updates through https://unifiedbgm.my-firstcare.com. Registered panels self-update within ~5 minutes.

mkdir -p ~/.config/smartbgm
echo "<ota-token>" > ~/.config/smartbgm/ota-token
chmod 600 ~/.config/smartbgm/ota-token

./update-panel.sh --bump # recommended
./update-panel.sh --bump --no-push # upload only
./ota-upload.sh --dry-run # package without upload

Package = app.py + templates/ + error-pages/. Emergency SCP bootstrap if OTA is down:

scp -P 2222 smartbgm-panel/app.py root@<ip>:/opt/smartbgm-panel/
scp -P 2222 smartbgm-panel/templates/*.html root@<ip>:/opt/smartbgm-panel/templates/
ssh root@<ip> -p 2222 'systemctl restart smartbgm-panel'

Post-Commission Checklist

Pi panel appliance (WiFi AP via deploy.sh):

hostapd, dnsmasq, smartbgm-panel all active
Panel loads on LAN :8080 and/or http://192.168.4.1:8080
Test client joins AP and receives DHCP in 192.168.4.10–100
Admin password changed from default
Headscale connected and panel registered with Cloud OTA when required

Unified Server (Ethernet-only — no WiFi adapter required):

eth0 static hospital LAN IP; LAN_IP in /opt/smartbgm/.env matches
Skip hostapd / SmartBGM-AP — server does not run a WiFi AP
Hospital WiFi: same subnet; Client Isolation OFF
SmartBGM LAN app via Docker Compose under /opt/smartbgm (not PM2)
Firewall: TCP 4011, 4012, 6901, 21115–21119; UDP 21116
curl -s http://localhost:4012/health returns healthy
Android on hospital WiFi can reach Admin :4011 / API :4012

SmartBGM LAN / Unified Server (Docker Compose)

Do not deploy smartBGM with PM2. Admin, Backend, MongoDB, Redis, Mock HIS, etc. run as Docker Compose services under /opt/smartbgm.

Item	Value
Install path	`/opt/smartbgm`
Compose file	`docker-compose.lan-smartbgm.yml`
Process manager	Docker / Docker Compose (not PM2)
Key ports	Admin `4011`, API `4012`

Ethernet-only Unified Server (no WiFi adapter)

A WiFi adapter on the Unified Server is not required. Connect with Ethernet to the hospital switch. Hospital WiFi is for Android devices only (same subnet; Client Isolation OFF). Do not expect hostapd / SmartBGM-AP on this host — that path is for Pi panel deploy.sh only.

Static IP on eth0; keep LAN_IP in /opt/smartbgm/.env in sync
Firewall unchanged vs with-adapter case: TCP 4011, 4012, 6901, 21115–21119; UDP 21116 (optional 80/443 domain mode; outbound 443 for Online Pull)
No extra AP/WiFi ports needed on the server

Fresh install (commissioning / init)

Ubuntu Server + Docker. Get a full bundle (smartbgm-lan-*.tar.gz) via USB/SCP or Online Pull, then:

sudo bash lan-import.sh

cd /opt/smartbgm
docker compose -f docker-compose.lan-smartbgm.yml --env-file .env up -d

Online Pull (preferred when internet is available)

sudo bash /opt/smartbgm/lan-online-pull.sh --setup # one-time: Cloud API URL + LAN_PULL_SECRET
sudo bash /opt/smartbgm/lan-online-pull.sh # Download → SHA-256 → Extract → lan-import
sudo bash /opt/smartbgm/lan-online-pull.sh --check
sudo bash /opt/smartbgm/lan-online-pull.sh --status
sudo bash /opt/smartbgm/lan-online-pull.sh --force

Outbound HTTPS (443) from Unified Server → Cloud API
Bundle generated on Cloud Admin → LAN Deployment → Generate Bundle
LAN_PULL_SECRET must match Cloud .env

Verify

cd /opt/smartbgm
docker compose -f docker-compose.lan-smartbgm.yml --env-file .env ps
curl -s http://localhost:4012/health

Full detail: documents/SmartBGM-Local-Server/ — especially LAN_DEVOPS_DEPLOYMENT_GUIDE.md §7.6 and lan-import.sh / lan-online-pull.sh.

API Reference

All API endpoints return JSON and require authentication (session cookie).

Endpoint	Method	Description
`/api/clients`	GET	Connected clients, bridge status, internet devices, VPN info
`/api/bridge_status`	GET	Bridge/extender status with traffic counters and mode
`/api/logs`	GET	System logs (hostapd, dnsmasq, panel, iptables, wireguard, bridge) + Docker container logs
`/api/system-stats`	GET	CPU, RAM, Disk, per-interface network stats with rolling history
`/api/docker`	GET	Docker containers list with live resource stats
`ws /docker`	SocketIO	Real-time Docker stats push (connect/disconnect auto-managed)
`/bridge/scan`	GET	Scan for nearby WiFi networks (admin)
`/bridge/connect`	POST	Connect to upstream WiFi (params: ssid, password, mode)
`/bridge/disconnect`	POST	Disconnect bridge/extender
`/docker/action`	POST	Start/stop/restart a Docker container (admin)
`/docker/logs/<name>`	GET	Fetch last N lines of a container's logs
`/api/files`	GET	List files and folders (param: path)
`/api/files/upload`	POST	Upload files to a directory (multipart form, admin)
`/api/files/download`	GET	Download a file (param: path)
`/api/files/mkdir`	POST	Create a new folder (admin)
`/api/files/delete`	POST	Delete a file or folder (admin)
`/api/files/rename`	POST	Rename a file or folder (admin)
Audit & Session
`/api/audit`	GET	Paginated audit log with filters (admin)
`/api/audit/stats`	GET	Audit statistics — total, today, failed, categories (admin)
`/api/audit/export`	GET	Full audit log CSV download (admin)
`/api/session/config`	GET/POST	Get or update session timeout setting (admin)
`/api/session/check`	GET	Check session validity — used for kicked-session polling
Profile
`/api/profile/password`	POST	Change current user's password
`/api/profile/avatar`	POST/DELETE	Upload or remove profile avatar
Integrations
`/api/telegram/save`	POST	Save Telegram bot configuration
`/api/telegram/test`	POST	Send a test Telegram notification

Troubleshooting

Clients can't get internet via bridge

Check if USB WiFi is connected: Bridge page should show "Connected"
Verify FORWARD rules exist: check Logs → Internet (iptables)
Try disconnecting and reconnecting the bridge
Ensure IP forwarding is enabled: sysctl net.ipv4.ip_forward should be 1

Extender mode: clients not getting IPs

Ensure parprouted is running: check Logs → Bridge
Clients must disconnect and reconnect to get upstream DHCP IPs
Upstream router must have DHCP enabled with available leases

USB WiFi not detected

Plug the adapter into a USB 2.0 port (not USB 3.0 for RTL8188EU)
Check lsusb output in the Terminal page
Run ip link to see all interfaces

Panel not loading

systemctl status smartbgm-panel # Check service status
journalctl -u smartbgm-panel -n 50 # View recent logs
systemctl restart smartbgm-panel # Restart the panel

WiFi AP not broadcasting

systemctl status hostapd # Check hostapd status
systemctl restart hostapd # Restart AP
iw dev wlan0 info # Check interface mode

Changelog

v1.17.0 — 2026-04-15

Bluetooth Management — new page to manage onboard Bluetooth (Pi 5 BT 5.0)
Adapter controls — toggle power on/off and discoverable mode with live status display
Paired devices — view, connect, disconnect, and remove paired Bluetooth devices
Device discovery — scan for nearby Bluetooth devices with 10-second timed scan (bluetoothctl --timeout)
Pair & trust — one-click pairing with automatic trust for discovered devices
Smart device names — shows friendly name or "Unknown Device" for unnamed BLE devices, always displays MAC address
Device count header in scan results
All Bluetooth actions logged to audit log
Requires apt install bluez for bluetoothctl

v1.16.0 — 2026-04-13

IP Forwarding Fix — apply_internet_rules() now always keeps ip_forward=1 and NAT enabled, preventing WiFi clients from losing internet after OTA updates
DHCP Config API — empty DHCP fields now auto-fill with defaults from the AP subnet (e.g. .10 to .100)
Settings Page — Server IP and DHCP Range now display dynamic values from actual server config instead of hardcoded 192.168.4.x
Docs Page — Architecture section now shows dynamic system info (hardware model, OS, RAM, hostname, AP interface, SSID, channel, DHCP range) instead of hardcoded values
Improved validation error messages for DHCP config showing which field is invalid
Headscale VPN JSON API — 8 new endpoints for mobile app Headscale/Tailscale management

v1.15.0 — 2026-04-12

Mobile App Discovery API — new public /api/discovery endpoint for BGM Admin mobile app auto-discovery (no auth required)
mDNS/Zeroconf Service — server now broadcasts _smartbgm._tcp service for automatic network discovery
Discovery endpoint returns: hostname, version, IP addresses, uptime, and available features
mDNS properties include version, hostname, and API endpoint for mobile app integration
Requires pip install zeroconf for mDNS functionality

v1.14.0 — 2026-04-10

Docker Resource Tuning — inspect and adjust container memory/CPU limits from the web UI via docker update
New API: GET /api/docker/resources/<name> — returns container memory, swap, CPU limits
New API: POST /docker/resources — updates container resource limits (admin, audit-logged)
Resource Tuning modal — pre-fills current limits, validates input, applies changes without restart
Docker memory % fix — aggregate now calculated as total usage ÷ host RAM (was summing per-container percentages, causing >100%)
Display dashboard memory % fix — display-dashboard.py now parses MemUsage bytes instead of summing MemPerc

v1.13.0 — 2026-04-08

Hardware model detection — new _detect_hw_model() reads /proc/device-tree/model (RPi) or DMI product name (VMware/x86) automatically
Dashboard topology — server IP now shows dynamic ap_ip instead of hardcoded 192.168.4.1
Dashboard topology — LAN label now shows detected interface name (e.g. ens160) instead of eth0
Bridge topology — hardware label now shows detected model (e.g. “VMware Virtual Platform”) instead of “Raspberry Pi 5”
Bridge topology — server IP and LAN label now fully dynamic
New API route /api/network/eth0/neighbors — fixes 404 error on Network Neighbors tab refresh
Network page — all DHCP/DNS placeholder values use dynamic AP subnet prefix instead of 192.168.4.x
WiFi AP detection fix — has_wifi now checks /sys/class/net/<iface>/wireless instead of startswith("wlan"), supporting wlx* interface names
LAN apply commands — api_eth0_apply now uses _detect_primary_iface() instead of hardcoded eth0 for IP flush, set, and DHCP
Bridge template — ap_ip, lan_iface, and hw_model now passed from all bridge render paths

v1.12.0 — 2026-04-05

Dynamic Hardware Detection — all network interface names (wlan0, eth0, etc.) now auto-detected at runtime instead of hardcoded
New helper: _detect_ap_iface() — finds the WiFi AP interface (hostapd-bound or first non-bridged wireless)
New helper: _get_ap_ip() — returns the AP interface’s IPv4 address dynamically
New helper: _get_ap_subnet() — derives the AP subnet (e.g. 192.168.4.0/24) from the live interface
New helper: _get_ap_subnet_prefix() — returns the first 3 octets of the AP subnet for DHCP range config
Enhanced _detect_primary_iface() — uses default route to find the primary LAN interface
Enhanced _detect_net_ifaces() — returns LAN, AP, and bridge interfaces with dynamic aliases
Portal page — captive portal URL now uses dynamic AP IP instead of hardcoded 192.168.4.1
Sniffer page — default capture interface now set to detected AP interface
Network page — interface labels use detected LAN/AP names instead of eth0/wlan0
Bridge page — AP traffic aliases (ap_rx/ap_tx) replace hardcoded wlan0 references
Terminal & Logs pages — pattern-based getNetColor/getNetIcon/getNetLabel functions for any interface naming convention
WireGuard page — dynamic LAN interface display
Firewall, Static Hosts, DHCP — all use dynamic AP interface and subnet
OTA-ready — single codebase now deploys correctly across RPi5, VMware VMs, and other hardware without manual edits
~130 hardcoded references replaced across app.py and 7 template files

v1.11.0 — 2026-04-02

WiFi Bridge SSID Unicode fix — iw scan escape sequences (\xHH) now decoded to proper UTF-8 (fixes smart quotes, accented chars)
WiFi Bridge reconnect Telegram notification — fixed missing alert when wpa_supplicant auto-reconnects
All Networks Failed notification — Telegram alert with backoff when all saved networks fail to connect
Admin disconnect auto-reconnect — 5-minute safety timer auto-reconnects to saved networks if admin forgets
Scenario/action tracking — Telegram messages and audit logs now include Cause and Resumed by for all bridge recovery events
Activity Log integration — all bridge events (lost, recovered, fallback failed, auto-reconnect) logged to audit system
14 Telegram notification triggers (up from 11) — added All Networks Failed, Admin Timeout Auto-Reconnect, SSID fallback detection
Documentation updated with new trigger rows, scenario tracking, and changelog

v1.10.0 — 2026-03-28

Telegram notification triggers — automatic alerts for 11 server events
Headscale VPN connect/disconnect notifications via Telegram
WireGuard VPN start/stop notifications via Telegram
WireGuard peer connected detection (background watcher, 30s poll)
WiFi Bridge lost & fallback notifications — alerts when AP drops or falls back to saved network
Docker container down/up monitoring (background watcher, 30s poll)
Documentation — Telegram triggers table, new feature sections, updated changelog

v1.9.0 — 2026-03-22

OTA Base/Client Roles — servers designated as base (push source) or client (receive only)
Client push guard — API returns 403 if a client-role server attempts OTA push
Deploy targets use Headscale VPN IPs for reliable cross-network OTA
Documentation updated to v1.9.0 with all new sections

v1.8.0 — 2026-03-18

OTA full-package push — includes static/vendor/ assets, all templates, and app.py
Version checksum now covers static vendor files for accurate change detection
Complete offline-capable OTA packages with bundled Bootstrap CSS/JS/Icons

v1.7.0 — 2026-03-12

Headscale VPN page — node status, ping, pre-auth key management, route/ACL controls
LAN IP & External IP display on Headscale, WireGuard, and OTA pages
Merged Static IP Assignments into Network Management page
Offline vendor assets — Bootstrap CSS/JS/Icons bundled at /opt/smartbgm-panel/static/vendor/
Fixed OTA deploy page JavaScript syntax error
Removed tailscale netcheck from login flow for faster authentication

v1.6.0 — 2026-03-05

Renamed to UnifiedBGM Server Management Panel
Session Security — configurable idle timeout (5–1440 min) with auto-logout
Single-session enforcement — only one active session per user; real-time kicked-session dialog
Session validity polling via /api/session/check every 5 seconds
HIPAA Audit Log — SQLite-backed, 90-day retention, 40+ instrumented actions
Audit Log page — filterable, paginated, CSV export, stats dashboard
Network Management — server IP/netmask, DHCP config, local domain, host directory, DHCP leases
User Profile & Avatar — upload/remove profile photo, password change
Telegram Notifications — bot token/chat ID config, enable/disable, test message
Cloudflare Tunnel — secure external access without port forwarding
Session cookie security — HttpOnly, SameSite=Lax
Updated login page with server management branding

v1.5.0 — 2026-02-28

File Manager — web-based file upload/download/rename/delete with drag-and-drop, progress bars, folder navigation
File storage at /opt/smartbgm-panel/files/ with path-traversal protection
Bulk selection and multi-delete support
Color-coded file type icons (images, code, archives, documents)

v1.4.1 — 2026-02-22

System performance graphs (CPU, RAM, Disk, per-interface Network) added to Terminal page

v1.4.0 — 2026-02-18

Docker real-time monitoring — WebSocket push via SocketIO /docker namespace (~3s updates, no polling)
Aggregate resource cards — total CPU%, memory (usage/limit/%), network I/O (RX/TX), block I/O (R/W)
CPU & memory history charts — Chart.js rolling 60-point line graphs
Live connection indicator — pulsing badge with connected/disconnected status
Dynamic version management — single APP_VERSION constant + context_processor for all pages

v1.3.0 — 2026-02-10

Docker container monitoring — live CPU/memory/net stats, start/stop/restart, log viewer
Docker container logs integrated into Logs page as dynamic tabs
System performance graphs (CPU, RAM, Disk) with Chart.js on Dashboard & Logs
Per-interface network throughput monitoring (eth0, wlan0, USB WiFi) with RX/TX charts
NAT outbound interface selector — choose WLAN or LAN for bridge NAT
Policy-based routing for WLAN NAT with DHCP gateway wait loop
AP settings — band (2.4/5GHz), channel, HT mode, TX power, hidden SSID
Loading overlay with context-specific messages for all form submissions
Live date/time clock in the top bar
Reboot persistence — iptables rules, IP forwarding, bridge auto-reconnect

v1.2.0 — 2026-02-01

WiFi Bridge & Extender — dual mode support (NAT bridge + parprouted extender)
Dashboard redesign — 5-section layout with animated network topology
Real-time data rates — live bandwidth display on topology map
Hostname resolution — 4-fallback method (DNS, NetBIOS, mDNS, MAC OUI)
Mobile responsive — hamburger menu, sidebar overlay
6 log tabs — hostapd, dnsmasq, panel, iptables, WireGuard, bridge
Bridge auto-reconnect on service restart
Documentation page

v1.1.0 — 2026-01-20

WireGuard VPN server/client management with QR codes
WiFi Bridge — USB WiFi adapter to upstream network
Web Terminal — full PTY in the browser
Per-device internet access control
Firewall rules management

v1.0.0 — 2026-01-10

Initial release — AP management, client monitoring
Login with RBAC, password hashing
DHCP and static host management
System logs viewer