diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..c29092e --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,22 @@ +name: github-pages +on: + push: + branches: + - master +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: 3.x + - uses: actions/cache@v3 + with: + key: ${{ github.ref }} + path: .cache + - run: pip install mkdocs-material + - run: pip install pillow cairosvg + - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/.gitignore b/.gitignore index 3435ea1..6620fd4 100644 --- a/.gitignore +++ b/.gitignore @@ -35,4 +35,6 @@ sqlite.db go.sum swagger.json swagger.yaml -/config.yml \ No newline at end of file +/config.yml +venv/ +.cache/ \ No newline at end of file diff --git a/docs/assets/images/favicon-large.png b/docs/assets/images/favicon-large.png new file mode 100644 index 0000000..ab03774 Binary files /dev/null and b/docs/assets/images/favicon-large.png differ diff --git a/docs/assets/images/favicon.ico b/docs/assets/images/favicon.ico new file mode 100644 index 0000000..b2a4e1c Binary files /dev/null and b/docs/assets/images/favicon.ico differ diff --git a/docs/assets/images/favicon.png b/docs/assets/images/favicon.png new file mode 100644 index 0000000..6539846 Binary files /dev/null and b/docs/assets/images/favicon.png differ diff --git a/docs/assets/images/logo.svg b/docs/assets/images/logo.svg new file mode 100644 index 0000000..99fdfc3 --- /dev/null +++ b/docs/assets/images/logo.svg @@ -0,0 +1,2 @@ + +WireGuard icon \ No newline at end of file diff --git a/docs/assets/images/screenshot.png b/docs/assets/images/screenshot.png new file mode 100644 index 0000000..da7377c Binary files /dev/null and b/docs/assets/images/screenshot.png differ diff --git a/docs/assets/images/wg-tool.png b/docs/assets/images/wg-tool.png new file mode 100644 index 0000000..efecce3 Binary files /dev/null and b/docs/assets/images/wg-tool.png differ diff --git a/docs/documentation/getting-started/building.md b/docs/documentation/getting-started/building.md new file mode 100644 index 0000000..6eead6a --- /dev/null +++ b/docs/documentation/getting-started/building.md @@ -0,0 +1,11 @@ +To build a standalone application, use the Makefile provided in the repository. +Go version **1.21** or higher has to be installed to build WireGuard Portal. +If you want to re-compile the frontend, NodeJS **18** and NPM >= **9** is required. + +```shell +# build the frontend (optional) +make frontend + +# build the binary +make build +``` \ No newline at end of file diff --git a/docs/documentation/getting-started/docker.md b/docs/documentation/getting-started/docker.md new file mode 100644 index 0000000..34fd2f6 --- /dev/null +++ b/docs/documentation/getting-started/docker.md @@ -0,0 +1,81 @@ +## Image Usage + +The preferred way to start WireGuard Portal as Docker container is to use Docker Compose. + +A sample docker-compose.yml: + +```yaml +version: '3.6' +services: + wg-portal: + image: wgportal/wg-portal:v2 + restart: unless-stopped + cap_add: + - NET_ADMIN + network_mode: "host" + ports: + - "8888:8888" + volumes: + - /etc/wireguard:/etc/wireguard + - ./data:/app/data + - ./config:/app/config +``` + +By default, the webserver is listening on port **8888**. + +Volumes for `/app/data` and `/app/config` should be used ensure data persistence across container restarts. + +## Image Versioning + +All images are hosted on Docker Hub at [https://hub.docker.com/r/wgportal/wg-portal](https://hub.docker.com/r/wgportal/wg-portal). +There are three types of tags in the repository: + +#### Semantic versioned tags +For example, `1.0.19`. + +These are official releases of WireGuard Portal. They correspond to the GitHub tags that we make, and you can see the release notes for them here: [https://github.com/h44z/wg-portal/releases](https://github.com/h44z/wg-portal/releases). + +Once these tags show up in this repository, they will never change. + +For production deployments of WireGuard Portal, we strongly recommend using one of these tags, e.g. **wgportal/wg-portal:1.0.19**, instead of the latest or canary tags. + +If you only want to stay at the same major or major+minor version, use either `v[MAJOR]` or `[MAJOR].[MINOR]` tags. For example `v1` or `1.0`. + +Version **1** is currently **stable**, version **2** is in **development**. + +#### latest +This is the most recent build to master! It changes a lot and is very unstable. + +We recommend that you don't use it except for development purposes. + +#### Branch tags +For each commit in the master and the stable branch, a corresponding Docker image is build. These images use the `master` or `stable` tags. + + + +## Configuration +You can configure WireGuard Portal using a yaml configuration file. +The filepath of the yaml configuration file defaults to `/app/config/config.yml`. +It is possible to override the configuration filepath using the environment variable **WG_PORTAL_CONFIG**. + +By default, WireGuard Portal uses a SQLite database. The database is stored in `/app/data/sqlite.db`. + +You should mount those directories as a volume: +- /app/data +- /app/config + +### Configuration Options +All available YAML configuration options are available [here](https://github.com/h44z/wg-portal#configuration). + +A very basic example: + +```yaml +core: + admin_user: test@wg-portal.local + admin_password: secret + +web: + external_url: http://localhost:8888 + request_logging: true +``` + diff --git a/docs/documentation/getting-started/upgrade.md b/docs/documentation/getting-started/upgrade.md new file mode 100644 index 0000000..fd00cc9 --- /dev/null +++ b/docs/documentation/getting-started/upgrade.md @@ -0,0 +1,25 @@ +For production deployments of WireGuard Portal, we strongly recommend using version 1. +If you want to use version 2, please be aware that it is still in beta and not feature complete. + +## Upgrade from v1 to v2 + +> :warning: Before upgrading from V1, make sure that you have a backup of your currently working configuration files and database! + +To start the upgrade process, start the wg-portal binary with the **-migrateFrom** parameter. +The configuration (config.yml) for WireGuard Portal must be updated and valid before starting the upgrade. + +To upgrade from a previous SQLite database, start wg-portal like: + +```shell +./wg-portal-amd64 -migrateFrom=old_wg_portal.db +``` + +You can also specify the database type using the parameter **-migrateFromType**, supported types: mysql, mssql, postgres or sqlite. +For example: + +```shell +./wg-portal-amd64 -migrateFromType=mysql -migrateFrom=user:pass@tcp(1.2.3.4:3306)/dbname?charset=utf8mb4&parseTime=True&loc=Local +``` + +The upgrade will transform the old, existing database and store the values in the new database specified in the **config.yml** configuration file. +Ensure that the new database does not contain any data! \ No newline at end of file diff --git a/docs/documentation/overview.md b/docs/documentation/overview.md new file mode 100644 index 0000000..770d8fb --- /dev/null +++ b/docs/documentation/overview.md @@ -0,0 +1,29 @@ +**WireGuard Portal** is a simple, web based configuration portal for [WireGuard](https://wireguard.com). +The portal uses the WireGuard [wgctrl](https://github.com/WireGuard/wgctrl-go) library to manage existing VPN +interfaces. This allows for seamless activation or deactivation of new users, without disturbing existing VPN +connections. + +The configuration portal supports using a database (SQLite, MySQL, MsSQL or Postgres), OAuth or LDAP +(Active Directory or OpenLDAP) as a user source for authentication and profile data. + +## Features +* Self-hosted - the whole application is a single binary +* Responsive web UI written in Vue.JS +* Automatically select IP from the network pool assigned to client +* QR-Code for convenient mobile client configuration +* Sent email to client with QR-code and client config +* Enable / Disable clients seamlessly +* Generation of wg-quick configuration file (`wgX.conf`) if required +* User authentication (database, OAuth or LDAP) +* IPv6 ready +* Docker ready +* Can be used with existing WireGuard setups +* Support for multiple WireGuard interfaces +* Peer Expiry Feature +* Handle route and DNS settings like wg-quick does +* ~~REST API for management and client deployment~~ (coming soon) + +## Quick-Start + +The easiest way to get started is to use the provided [Docker image](./getting-started/docker.md). + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..cf8e08a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,4 @@ +--- +template: layouts/home.html +title: WireGuard Portal +--- diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 0000000..080c14a --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,49 @@ +/* This file is used for extra styles that are not part of the theme */ + +span.title { + font-weight: bold; +} + +span.em { + font-weight: bold; +} + +.separator { + border-bottom: 1px solid #e3e8ee; +} + +a.field { + font-weight: 600; + /* color: #3c4257; */ + font-size: .8rem; +} + +span.parent-field { + font-weight: 600; + color:#a3acb9; + font-size: .85em; +} + +span.type { + color: #8792a2; + font-size: .7rem; + margin-right: 4px; +} + +span.version { + color: #8792a2; + font-size: .7rem; + float: right; +} + +span.faint { + color: #8792a2; +} + +.md-social__link svg { + fill: rgb(61, 61, 61); +} + +.md-tabs__link { + font-size: 0.8rem; +} \ No newline at end of file diff --git a/docs/theme-overrides/layouts/home.html b/docs/theme-overrides/layouts/home.html new file mode 100644 index 0000000..8894bd4 --- /dev/null +++ b/docs/theme-overrides/layouts/home.html @@ -0,0 +1,433 @@ + +{% extends "main.html" %} + + +{% block tabs %} + {{ super() }} + + + + + +
+
+
+
+

A beautiful and simple UI to manage your WireGuard peers and interfaces

+

WireGuard Portal is an open source web-based user interface that makes it easy to setup and manage + WireGuard VPN connections. It's built on top of WireGuard's official wgctrl library.

+

+ + Get started + + +
+
+
+
+ +
+
+ +
+
+ +
+
+ +
+
+
+

More information about WireGuard

+

+ WireGuard® is an extremely simple yet fast and modern + VPN that utilizes state-of-the-art cryptography. +

+

+ WireGuard uses state-of-the-art cryptography and still + manages to be as easy to configure and deploy as SSH. + A combination of extremely high-speed cryptographic primitives and the fact that WireGuard lives inside + the Linux kernel means that secure networking can be very high-speed. + It is suitable for both small embedded devices like smartphones and fully loaded backbone routers. +

+
+
+
+ +
+
+
+
+

Explore official documentation

+ + +
+ +
+ +
+
Official Website
+

+ If you'd like a general conceptual overview of what WireGuard is about, read onward here. +

+
+
+ + + + +
+ +
+
Protocol & Cryptography
+

+ WireGuard uses state-of-the-art cryptography, like the Noise protocol framework, Curve25519, ChaCha20, Poly1305, BLAKE2, SipHash24, HKDF, and secure trusted constructions. +

+
+
+ + + + +
+ +
+
Client Installation
+

+ You may progress to installation and reading the quickstart instructions on how to use it. +

+
+
+ +
+
+
+
+
+{% endblock %} + + +{% block content %}{% endblock %} + + +{% block footer %} + {{ super() }} +{% endblock %} diff --git a/docs/theme-overrides/main.html b/docs/theme-overrides/main.html new file mode 100644 index 0000000..adb180f --- /dev/null +++ b/docs/theme-overrides/main.html @@ -0,0 +1,17 @@ +{% extends "base.html" %} + +{% block extrahead %} +{% if page and page.meta and page.meta.title %} + +{% endif %} +{% if page and page.meta and page.meta.image %} + + + + + + + + +{% endif %} +{% endblock %} \ No newline at end of file diff --git a/docs/theme-overrides/partials/footer.html b/docs/theme-overrides/partials/footer.html new file mode 100644 index 0000000..7634fb7 --- /dev/null +++ b/docs/theme-overrides/partials/footer.html @@ -0,0 +1,32 @@ +{% import "partials/language.html" as lang with context %} + + + diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d6c8926 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,55 @@ +# build with MkDocs 1.5.3, mkdocs-material-9.4.7 + +site_name: WireGuard Portal +site_description: 'Manage WireGuard Peers and Interface using a beautiful and simple web UI.' +site_url: https://wgportal.org +repo_name: 'h44z/wg-portal' +repo_url: 'https://github.com/h44z/wg-portal' +copyright: 'Copyright © 2023 WireGuard Portal Project' +extra_css: + - stylesheets/extra.css +theme: + name: material + custom_dir: docs/theme-overrides + palette: + primary: white + font: false + logo: assets/images/logo.svg + favicon: assets/images/favicon-large.png + language: en + features: + - tabs + - instant + - navigation.tabs + +plugins: + - search + - social + +extra: + social: + - icon: fontawesome/brands/github-alt + link: https://github.com/h44z + - icon: fontawesome/brands/twitter + link: https://twitter.com/chris_h44z + +markdown_extensions: + - admonition + - meta + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.tilde + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg + +nav: + - Home: index.md + - Documentation: + - Overview: documentation/overview.md + - Getting Started: + - Building: documentation/getting-started/building.md + - Docker Container: documentation/getting-started/docker.md + - Upgrade from V1: documentation/getting-started/upgrade.md \ No newline at end of file