Wireguard UI

An admin dashboard for Wireguard — manage hosts, clients, tunnels, and IP rules through a web interface.

Features

• Host Management — Create and configure WireGuard hosts with public keys, IP addresses, and listen ports
• Client Management — Add clients per host with WireGuard configs, allowed IPs, and notes
• Client Rules — Define IP table rules per client (rule type, destination, ports, protocol)
• Media Management — Upload and manage media assets (images, documents, etc.) with tagging, thumbnails, and RAG ingestion
• User Management — Multi-user support with role-based access (user types)
• Persistent Storage — SQLite database with automatic schema generation
• WebSocket Support — Real-time updates via WebSocket connections
• Responsive UI — Tailwind CSS v4 with twui design system components

Prerequisites

• Bun 1.3.1 or later (install)
• SQLite (via @moduletrace/bun-sqlite)
• git
• Linux (Debian, Ubuntu, Fedora, Arch, Alpine, or similar)
• Root access (for installation script and system service setup)

Installation

Automatic (Recommended)

Run the install script on a fresh machine:

bash < <(curl -fsSL https://git.tben.me/Moduletrace/wireguard-ui/raw/branch/main/src/scripts/install-wg-ui.sh)

Or clone the repo and run the script manually:

git clone https://git.tben.me/Moduletrace/wireguard-ui.git
cd wireguard-ui
bash src/scripts/install-wg-ui.sh

The install script will:

1. Install system dependencies (git, curl, ca-certificates, openssl)
2. Install Bun 1.3.14 to /opt/bun
3. Set up library directories under /var/lib/wgui (keys, clients, hosts, iptables, scripts)
4. Clone or update the repo to /var/lib/wgui/webapp
5. Install app dependencies (bun install)
6. Generate .env with encryption secrets
7. Run WireGuard setup (if available)
8. Install the wg-quick helper script
9. Set up a systemd or OpenRC service (wgui)

Docker

Build and run with the provided Dockerfile:

docker build -t wireguard-ui .
docker run -d --name wireguard-ui \
  -p 10752:10752 \
  -v wgui-data:/app/db \
  --restart unless-stopped \
  wireguard-ui

The entrypoint (entrypoint.sh) installs dependencies and starts the server.

Manual (Development)

git clone https://git.tben.me/Moduletrace/wireguard-ui.git
cd wireguard-ui
bun install
NODE_ENV=development bun run dev

The dev server runs on port 10752 by default.

Configuration

Environment Variables

The .env file (gitignored) controls runtime behavior. It is auto-generated during installation if missing:

Variable	Description	Default
NODE_ENV	Environment (development/production)	production
ENCRYPTION_KEY	Encryption key for sensitive data	Auto-generated
ENCRYPTION_SALT	Encryption salt for sensitive data	Auto-generated
DATA_DIR	Application data directory	$INSTALL_DIR/.data

Database Configuration

Edit bun-sqlite.config.ts to change database settings:

const config: BunSQLiteConfig = {
    db_name: "wgui", // Database file name
    db_dir: "./db", // Database directory
    typedef_file_path: "./db/types/db.ts", // Generated types
    db_schema_file_name: "schema.ts", // Schema definition
};

Server Port

The server port is defined in src/data/site-data.ts:

export const SiteData = {
    ServerPort: 10752,
    // ...
} as const;

Available Scripts

Command	Description
bun run dev	Start development server (requires root)
bun run start	Start production server
bun run db:schema	Generate/update database schema and types
bun run db:admin	Open database admin interface

Project Structure

wireguard-ui/
├── src/
│   ├── pages/              # File-system based routes (__root.tsx, index.tsx, etc.)
│   │   ├── (sections)/     # Page sections
│   │   ├── (partials)/     # Page-local components
│   │   ├── (data)/         # Page-local data
│   │   ├── (functions)/    # Page-local functions
│   │   ├── (utils)/        # Page-local utilities
│   │   └── (hooks)/        # Page-local hooks
│   ├── components/
│   │   ├── twui/           # Local design system (publishable package)
│   │   ├── ui/             # shadcn/ui components
│   │   ├── shadcnblocks/   # shadcnblocks registry components
│   │   └── general/        # Shared page components (chat, date-picker, logo, etc.)
│   ├── hooks/              # Shared React hooks
│   ├── functions/
│   │   ├── backend/        # Server-only: DB queries, email, media upload, RAG
│   │   ├── frontend/       # Client-safe: CRUD handlers, fetch handlers
│   │   └── general/        # Platform-agnostic: join builders
│   ├── utils/              # Utility modules (auth, crypto, CSRF, hashing, etc.)
│   ├── dict/               # Constants and dictionaries (user types, gates, etc.)
│   ├── data/               # Static data (app constants, location data, etc.)
│   ├── types/              # Type definitions
│   ├── scripts/            # Install and setup scripts
│   └── server.ts           # Entry point — starts Bun.serve with WebSocket support
├── db/
│   ├── schema.ts           # Database schema definition
│   └── types/db.ts         # Generated database types
├── deploy/
│   └── deploy-prod.sh      # Production deployment script (rsync + Docker)
├── public/                 # Static assets served by the server
├── assets/                 # Project assets
├── Dockerfile              # Container image (oven/bun:1.3.1-debian)
├── entrypoint.sh           # Docker entrypoint
├── bun-sqlite.config.ts    # Database configuration
├── bunext.config.ts        # Bunext configuration
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
└── .env                    # Environment variables (gitignored)

Database Schema

The database consists of the following tables:

Table	Description
users	User accounts (name, email, username, password)
user_types	User type assignments per user
media	Media assets (images, documents, etc.)
media_paradigms	Media paradigm classifications per media item
clients	WireGuard clients per host
hosts	WireGuard host configurations
client_rules	IP table rules for each client
variables	Application-wide key-value variables

Generate types from the schema:

bun run db:schema

Deployment

Production Deployment

The deployment script (deploy/deploy-prod.sh) handles production deployment:

SOURCE_DIRECTORY=/path/to/wireguard-ui bun run deploy:prod

This will:

1. Rsync the project files to the production server ([email protected]:/docker/bunext-mariadb)
2. SSH into the server, rebuild the Docker image, and restart the container

Docker Production

The Docker image (Dockerfile) is based on oven/bun:1.3.1-debian:

docker build -t bunext-mariadb .
docker run --name bunext-mariadb -d \
  --network cloudflare --network mariadb \
  -v server-data:/data \
  --restart unless-stopped \
  bunext-mariadb:latest

The server runs on the port defined in SiteData.ServerPort (default: 10752).

Admin Route Hierarchy

Route Pattern	Access	Features
/admin/*	Residents	Access booking, payments, chat, dependants, notifications, events, settings, support
/admin/admin/*	Admin / ExCo	User management, payment schemes, documents, chat group management
/admin/security/*	Security / ExCo / Manager / ACo	Gate control, guest access monitoring, dependant verification

Development

Development Mode

Set NODE_ENV=development and run:

NODE_ENV=development bun run dev

In development mode, the install script skips cloning and system service setup — the server is assumed to already be running.

Path Alias

@/* resolves from the repository root. Examples:

import { Button } from "@/src/components/ui/button";
import type { BUN_SQLITE_WGUI_USERS } from "@/db/types/db";

Type-Checking

Run type checks with:

bunx tsc --noEmit

Testing

Run individual test files:

bun test path/to/test.file.test.ts

Repository

• URL: https://git.tben.me/Moduletrace/wireguard-ui
• Install Script: src/scripts/install-wg-ui.sh