222 lines
8.3 KiB
Markdown
222 lines
8.3 KiB
Markdown
# 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](https://bun.sh/install))
|
|
- **SQLite** (via `@moduletrace/bun-sqlite`)
|
|
- **git**
|
|
- **zip** and **unzip**
|
|
- **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://url.tben.me/wg-ui | sudo bash
|
|
```
|
|
|
|
Or clone the repo and run the script manually:
|
|
|
|
```bash
|
|
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`)
|
|
|
|
### Manual (Development)
|
|
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
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`:
|
|
|
|
```typescript
|
|
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
|
|
├── public/ # Static assets served by the server
|
|
├── assets/ # Project assets
|
|
├── 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:
|
|
|
|
```bash
|
|
bun run db:schema
|
|
```
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```typescript
|
|
import { Button } from "@/src/components/ui/button";
|
|
import type { BUN_SQLITE_WGUI_USERS } from "@/db/types/db";
|
|
```
|
|
|
|
### Type-Checking
|
|
|
|
Run type checks with:
|
|
|
|
```bash
|
|
bunx tsc --noEmit
|
|
```
|
|
|
|
### Testing
|
|
|
|
Run individual test files:
|
|
|
|
```bash
|
|
bun test path/to/test.file.test.ts
|
|
```
|
|
|
|
## Repository
|
|
|
|
- **URL**: [https://git.tben.me/Moduletrace/wireguard-ui](https://git.tben.me/Moduletrace/wireguard-ui)
|
|
- **Install Script**: [src/scripts/install-wg-ui.sh](https://git.tben.me/Moduletrace/wireguard-ui/raw/branch/main/src/scripts/install-wg-ui.sh)
|