wg easy

The Problem

Setting up a WireGuard server with a management UI normally requires several manual steps: installing WireGuard, creating configuration files, handling QR‑code generation, and building a small web front‑end. For teams that need a quick, repeatable deployment, the lack of an opinionated, container‑first solution creates operational friction and configuration drift.

What This Does

wg-easy bundles the WireGuard daemon and a Vue‑based admin UI into a single Docker image. The UI lives under src/app/ (e.g., src/app/pages/admin.vue, src/app/components/) and communicates with the server through the CLI entry point src/cli/index.ts. Dockerfiles (Dockerfile, Dockerfile.dev) define the build, while docker-compose.yml and docker-compose.dev.yml orchestrate the service, the WireGuard kernel module, and optional reverse‑proxy containers.

Key files:

src/cli/index.ts – parses command‑line flags and starts the backend service. src/app/stores/ – Pinia stores (auth.ts, clients.ts) that power the UI state. Dockerfile – multi‑stage build that compiles the Vue app (pnpm install && pnpm build) and packages it with the WireGuard binaries.

The repository also ships extensive documentation (docs/content/) and CI pipelines (.github/workflows/.yml) that lint, run CodeQL, and publish Docker images.

How To Use It

Setup

Install Docker (required) curl -sSL https://get.docker.com | sh Clone the repo and install Node dependencies via pnpm git clone https://github.com/wg-easy/wg-easy.git cd wg-easy corepack enable # ensures pnpm is available pnpm install --frozen-lockfile

Configuration

The container expects the following environment variables (documented in docs/content/guides/setup.md and reflected in docker-compose.yml):

Create a .env file next to docker-compose.yml or export the variables before launch.

Running

Production (single‑container)

docker compose up -d

Development (hot‑reload UI, separate WireGuard container)

docker compose -f docker-compose.dev.yml up --build

The UI is reachable at http://<WGHOST>:51821 (default port) after the containers are healthy. The CLI can be invoked directly for one‑off actions:

node src/cli/index.ts add-client --name alice --address 10.8.0.2

Real‑World Use

A small office can deploy wg-easy on a cheap VPS: the Docker image isolates WireGuard from host package management, the UI lets the network admin add or revoke client keys without SSH, and Prometheus metrics (docs/content/advanced/metrics/prometheus.md) can be scraped by the existing monitoring stack. The workflow is: Provision a VPS, install Docker. Pull the latest image (docker pull ghcr.io/wg-easy/wg-easy). Run docker compose up -d with a minimal .env. Share the QR code generated by the UI with employees’ WireGuard clients.

Code Health & Issues

Medium – No test suite – The repository contains no .test. files; CI runs only lint and CodeQL. Untested paths increase risk of regression. (src/cli/, src/app/*) Low – Limited type safety – Only 14 TypeScript files; many Vue components are plain .vue with JavaScript sections, reducing static analysis coverage. Medium – Environment‑variable reliance – Critical secrets (PASSWORD, WGHOST) are plain strings; no runtime validation shown in src/cli/index.ts. Low – Dependency hygiene – pnpm-lock.yaml is present, but no automated Dependabot PRs for npm (only for GitHub Actions). Low – Documentation vs code drift – Docs reference a “setup guide” and “migration guide” that are up‑to‑date, but the README’s “Dev Server” section is truncated, leaving developers without a clear pnpm dev command. None – License – A LICENSE file is included (MIT).

Overall, the codebase follows a clean separation (Docker for infra, Vue for UI, CLI for server ops) and the CI pipelines enforce linting and security scanning.

The Bottom Line

wg-easy delivers a ready‑to‑run, containerized WireGuard + UI stack that speeds up VPN provisioning for small‑to‑medium environments. It is production‑ready in terms of deployment and documentation, but the lack of automated tests and sparse runtime validation mean that teams should audit custom changes before wide rollout. Ideal for organizations that value quick setup over exhaustive internal test coverage.