# 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)