Update README.md
This commit is contained in:
@@ -1,5 +1,273 @@
|
|||||||
# Wireguard UI
|
# Wireguard UI
|
||||||
|
|
||||||
An admin dashboard for Wireguard.
|
An admin dashboard for Wireguard — manage hosts, clients, tunnels, and IP rules through a web interface.
|
||||||
|
|
||||||
Installation script located at `https://git.tben.me/Moduletrace/wireguard-ui/raw/branch/main/src/scripts/install-wg-ui.sh`
|
## 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** — MariaDB-backed 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))
|
||||||
|
- **MariaDB** (or compatible SQL database)
|
||||||
|
- **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
|
||||||
|
REPO_URL=https://git.tben.me/Moduletrace/wireguard-ui.git bash -c '$(< <(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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.tben.me/Moduletrace/wireguard-ui.git
|
||||||
|
cd wireguard-ui
|
||||||
|
REPO_URL=https://git.tben.me/Moduletrace/wireguard-ui.git 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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)
|
||||||
|
|
||||||
|
```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 build` | Build with bunext |
|
||||||
|
| `bun run db:schema` | Generate/update database schema and types |
|
||||||
|
| `bun run db:admin` | Open database admin interface |
|
||||||
|
| `bun run deploy:prod` | Deploy to production server |
|
||||||
|
| `bunx tsc --noEmit` | Type-check only (no emit) |
|
||||||
|
| `bun test <file>` | Run individual test files |
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bun run db:schema
|
||||||
|
```
|
||||||
|
|
||||||
|
## Deployment
|
||||||
|
|
||||||
|
### Production Deployment
|
||||||
|
|
||||||
|
The deployment script (`deploy/deploy-prod.sh`) handles production deployment:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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` with MariaDB client tools installed:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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:
|
||||||
|
|
||||||
|
```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)
|
||||||
|
|||||||
Reference in New Issue
Block a user