Update README.md
This commit is contained in:
@@ -1,5 +1,273 @@
|
||||
# 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