diff --git a/.gitignore b/.gitignore
index c36465bd..2d1e2d0d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
.DS_Store
*.swp
-node_modules
\ No newline at end of file
+node_modules
+
+docs/site
+docs/.cache
\ No newline at end of file
diff --git a/.vscode/settings.json b/.vscode/settings.json
index f62f2c98..691bcfba 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -26,5 +26,8 @@
"i18n-ally.sortKeys": false,
"i18n-ally.keepFulfilled": false,
"i18n-ally.keystyle": "nested",
- "editor.gotoLocation.multipleDefinitions": "goto"
+ "editor.gotoLocation.multipleDefinitions": "goto",
+ "[toml]": {
+ "editor.defaultFormatter": "tamasfe.even-better-toml"
+ }
}
diff --git a/docs/content/advanced/api.md b/docs/content/advanced/api.md
index 58d5df2d..e285d98a 100644
--- a/docs/content/advanced/api.md
+++ b/docs/content/advanced/api.md
@@ -5,6 +5,7 @@ title: API
/// warning | Breaking Changes
This API is not yet stable and may change in the future. The API is currently in development and is subject to change without notice. The API is not yet documented, but we will add documentation as the API stabilizes.
+
///
You can use the API to interact with the application programmatically. The API is available at `/api` and supports both GET and POST requests. The API is designed to be simple and easy to use, with a focus on providing a consistent interface for all endpoints.
diff --git a/docs/content/advanced/config/amnezia.md b/docs/content/advanced/config/amnezia.md
index 1d4f2b5b..3e8d4d0a 100644
--- a/docs/content/advanced/config/amnezia.md
+++ b/docs/content/advanced/config/amnezia.md
@@ -39,14 +39,14 @@ If a parameter is not set, it will not be added to the configuration. If all Amn
### Parameter Compatibility Table
-| Parameter | Can differ between server and client | Configurable on server | Configurable on client |
-| --------- | ------------------------------------ | ---------------------- | ----------------------- |
-| Jc | ✅ Yes | ✅ | ✅ |
-| Jmin | ✅ Yes | ✅ | ✅ |
-| Jmax | ✅ Yes | ✅ | ✅ |
-| S1-S4 | ❌ No, must match | ✅ | ❌ (copied from server) |
-| H1-H4 | ❌ No, must match | ✅ | ❌ (copied from server) |
-| I1-I5 | ✅ Yes | ✅ | ✅ |
+| Parameter | Can differ between server and client | Configurable on server | Configurable on client |
+| --------- | ------------------------------------ | ---------------------- | ------------------------ |
+| Jc | :white_check_mark: Yes | :white_check_mark: | :white_check_mark: |
+| Jmin | :white_check_mark: Yes | :white_check_mark: | :white_check_mark: |
+| Jmax | :white_check_mark: Yes | :white_check_mark: | :white_check_mark: |
+| S1-S4 | :x: No, must match | :white_check_mark: | :x: (copied from server) |
+| H1-H4 | :x: No, must match | :white_check_mark: | :x: (copied from server) |
+| I1-I5 | :white_check_mark: Yes | :white_check_mark: | :white_check_mark: |
## Client Applications
diff --git a/docs/content/advanced/config/external-authentication.md b/docs/content/advanced/config/external-authentication.md
index 420c3275..aeb33e4f 100644
--- a/docs/content/advanced/config/external-authentication.md
+++ b/docs/content/advanced/config/external-authentication.md
@@ -24,7 +24,7 @@ To automatically register users that log in with an OAuth provider, set the foll
| Env | Required | Default | Description |
| --------------------- | -------- | ------- | ------------------------ |
-| `OAUTH_AUTO_REGISTER` | ✖️ | `false` | Enable auto-registration |
+| `OAUTH_AUTO_REGISTER` | :x: | `false` | Enable auto-registration |
When enabled:
@@ -46,7 +46,7 @@ To only allow users with an email address from a specific domain to log in, set
| Env | Required | Default | Description |
| ----------------------- | -------- | ------- | --------------------- |
-| `OAUTH_ALLOWED_DOMAINS` | ✖️ | - | Allowed email domains |
+| `OAUTH_ALLOWED_DOMAINS` | :x: | - | Allowed email domains |
You can allow multiple domains by separating them with a comma:
@@ -58,7 +58,7 @@ To automatically launch the OAuth login flow when visiting the login page, set t
| Env | Required | Default | Description |
| ------------------- | -------- | ------- | ----------------------------- |
-| `OAUTH_AUTO_LAUNCH` | ✖️ | - | Auto launch an OAuth provider |
+| `OAUTH_AUTO_LAUNCH` | :x: | - | Auto launch an OAuth provider |
When enabled:
@@ -83,10 +83,10 @@ If your provider does not support multiple redirect URIs (e.g. GitHub) but allow
#### Google
-| Env | Required | Description |
-| ---------------------------- | -------- | -------------------- |
-| `OAUTH_GOOGLE_CLIENT_ID` | ✔️ | Google Client ID |
-| `OAUTH_GOOGLE_CLIENT_SECRET` | ✔️ | Google Client Secret |
+| Env | Required | Description |
+| ---------------------------- | ------------------ | -------------------- |
+| `OAUTH_GOOGLE_CLIENT_ID` | :white_check_mark: | Google Client ID |
+| `OAUTH_GOOGLE_CLIENT_SECRET` | :white_check_mark: | Google Client Secret |
Setup
@@ -97,10 +97,10 @@ If your provider does not support multiple redirect URIs (e.g. GitHub) but allow
#### GitHub
-| Env | Required | Description |
-| ---------------------------- | -------- | -------------------- |
-| `OAUTH_GITHUB_CLIENT_ID` | ✔️ | GitHub Client ID |
-| `OAUTH_GITHUB_CLIENT_SECRET` | ✔️ | GitHub Client Secret |
+| Env | Required | Description |
+| ---------------------------- | ------------------ | -------------------- |
+| `OAUTH_GITHUB_CLIENT_ID` | :white_check_mark: | GitHub Client ID |
+| `OAUTH_GITHUB_CLIENT_SECRET` | :white_check_mark: | GitHub Client Secret |
Setup
@@ -122,12 +122,12 @@ The provider needs to support:
The provider needs to be available with HTTPS and have a valid certificate.
-| Env | Required | Default | Example | Description |
-| -------------------------- | -------- | ------- | -------------------------- | ------------------ |
-| `OAUTH_OIDC_SERVER` | ✔️ | - | `https://auth.example.com` | OIDC Server |
-| `OAUTH_OIDC_CLIENT_ID` | ✔️ | - | - | OIDC Client ID |
-| `OAUTH_OIDC_CLIENT_SECRET` | ✔️ | - | - | OIDC Client Secret |
-| `OAUTH_OIDC_NAME` | ✖️ | OIDC | `Authelia` | Provider Name |
+| Env | Required | Default | Example | Description |
+| -------------------------- | ------------------ | ------- | -------------------------- | ------------------ |
+| `OAUTH_OIDC_SERVER` | :white_check_mark: | - | `https://auth.example.com` | OIDC Server |
+| `OAUTH_OIDC_CLIENT_ID` | :white_check_mark: | - | - | OIDC Client ID |
+| `OAUTH_OIDC_CLIENT_SECRET` | :white_check_mark: | - | - | OIDC Client Secret |
+| `OAUTH_OIDC_NAME` | :x: | OIDC | `Authelia` | Provider Name |
##### Authelia Setup
@@ -167,7 +167,7 @@ To disable password-based authentication and only allow login via OAuth provider
| Env | Required | Default | Description |
| ----------------------- | -------- | ------- | ------------------------------- |
-| `DISABLE_PASSWORD_AUTH` | ✖️ | `false` | Disable password authentication |
+| `DISABLE_PASSWORD_AUTH` | :x: | `false` | Disable password authentication |
When enabled:
diff --git a/docs/content/advanced/config/unattended-setup.md b/docs/content/advanced/config/unattended-setup.md
index b0444d93..5572df99 100644
--- a/docs/content/advanced/config/unattended-setup.md
+++ b/docs/content/advanced/config/unattended-setup.md
@@ -23,6 +23,7 @@ These will only be used during the first start of the container. After that, the
If variables are in the same group, you have to set all of them. For example, if you set `INIT_IPV4_CIDR`, you also have to set `INIT_IPV6_CIDR`.
If you want to skip the setup process, you have to configure group `1`
+
///
/// note | Security
@@ -30,4 +31,5 @@ If you want to skip the setup process, you have to configure group `1`
The initial username and password is not checked for complexity. Make sure to set a long enough username and password. Otherwise, the user won't be able to log in.
It's recommended to remove the variables after the setup is done to prevent the password from being exposed.
+
///
diff --git a/docs/content/advanced/metrics/prometheus.md b/docs/content/advanced/metrics/prometheus.md
index 09ad087b..1af384d2 100644
--- a/docs/content/advanced/metrics/prometheus.md
+++ b/docs/content/advanced/metrics/prometheus.md
@@ -39,4 +39,5 @@ You can use the following Grafana dashboard to visualize the metrics:
The Grafana dashboard is not official and is not maintained by the `wg-easy` team. If you have any issues with the dashboard, please contact the author of the dashboard.
See [#1299](https://github.com/wg-easy/wg-easy/pull/1299) for more information.
+
///
diff --git a/docs/content/contributing/issues-and-pull-requests.md b/docs/content/contributing/issues-and-pull-requests.md
index 92f36016..a58a4c31 100644
--- a/docs/content/contributing/issues-and-pull-requests.md
+++ b/docs/content/contributing/issues-and-pull-requests.md
@@ -9,6 +9,7 @@ This project is Open Source. That means that you can contribute on enhancements,
/// note | Attention
**Before opening an issue**, read the [`README`][github-file-readme] carefully, study the docs for your version (maybe [latest][docs-latest]) and your search engine you trust. The issue tracker is not meant to be used for unrelated questions!
+
///
When opening an issue, please provide details use case to let the community reproduce your problem.
@@ -16,6 +17,7 @@ When opening an issue, please provide details use case to let the community repr
/// note | Attention
**Use the issue templates** to provide the necessary information. Issues which do not use these templates are not worked on and closed.
+
///
By raising issues, I agree to these terms and I understand, that the rules set for the issue tracker will help both maintainers as well as everyone to find a solution.
@@ -39,6 +41,7 @@ When an option is marked with "not officially supported" / "unsupported", then s
/// question | Motivation
You want to add a feature? Feel free to start creating an issue explaining what you want to do and how you're thinking doing it. Other users may have the same need and collaboration may lead to better results.
+
///
### Submit a Pull-Request
diff --git a/docs/content/examples/tutorials/adguard.md b/docs/content/examples/tutorials/adguard.md
index 8f357b1c..e65054ae 100644
--- a/docs/content/examples/tutorials/adguard.md
+++ b/docs/content/examples/tutorials/adguard.md
@@ -9,9 +9,11 @@ This tutorial is a follow-up to the official [Traefik tutorial](./traefik.md). I
- A working [wg-easy](./basic-installation.md) and [Traefik](./traefik.md) setup from the previous guides.
/// warning | Important: Following this guide will reset your WireGuard configuration.
+
The process involves re-creating the `wg-easy` container and its data, which means **all existing WireGuard clients and settings will be deleted.**
You will need to create your clients again after completing this guide.
+
///
## Add `adguard` configuration
@@ -152,13 +154,15 @@ networks:
2. Navigate to `https://adguard.$example.com$` to begin the AdGuard Home setup.
/// warning | Important: Configure AdGuard Home Admin Web Interface Port
+
During the initial AdGuard Home setup on the `Step 2/5` page, you **must** set the **Admin Web Interface Port** to **3000**. Do not use the default port 80, as it will not work with the Traefik configuration.
After completing the setup, the AdGuard UI might appear unresponsive. This is expected. **Simply reload the page**, and the panel will display correctly.
-///
> If you accidentally left it default (80), you will need to manually edit the `docker-compose.yml` file for AdGuard Home (`/etc/docker/containers/adguard/docker-compose.yml`) and change the line `traefik.http.services.adguard.loadbalancer.server.port=3000` to `traefik.http.services.adguard.loadbalancer.server.port=80`. After making this change, restart AdGuard Home by navigating to `/etc/docker/containers/adguard` and running `sudo docker compose up -d`.
+///
+
## Final System Checks
### Firewall
diff --git a/docs/content/examples/tutorials/caddy.md b/docs/content/examples/tutorials/caddy.md
index b3bc2d95..c9373d92 100644
--- a/docs/content/examples/tutorials/caddy.md
+++ b/docs/content/examples/tutorials/caddy.md
@@ -5,6 +5,7 @@ title: Caddy
/// note | Opinionated
This guide is opinionated. If you use other conventions or folder layouts, feel free to change the commands and paths.
+
///
We're using [Caddy](https://caddyserver.com/) here as reverse proxy to serve `wg-easy` on [https://wg-easy.example.com](https://wg-easy.example.com) via TLS.
diff --git a/docs/content/examples/tutorials/reverse-proxyless.md b/docs/content/examples/tutorials/reverse-proxyless.md
index 2dfc1191..f7c968d8 100644
--- a/docs/content/examples/tutorials/reverse-proxyless.md
+++ b/docs/content/examples/tutorials/reverse-proxyless.md
@@ -7,6 +7,7 @@ title: No Reverse Proxy
This is insecure. You should use a reverse proxy to secure the connection.
Only use this method if you know what you are doing.
+
///
If you only allow access to the web UI from your local network, you can skip the reverse proxy setup. This is not recommended, but it is possible.
diff --git a/docs/content/examples/tutorials/routed.md b/docs/content/examples/tutorials/routed.md
index 3ed4070d..2afdd9c9 100644
--- a/docs/content/examples/tutorials/routed.md
+++ b/docs/content/examples/tutorials/routed.md
@@ -61,6 +61,7 @@ Pick an IPv4 and IPv6 subnet for your clients and add static routes on your rout
/// note | 2001:db8::/32
The _documentation prefix_ `2001:db8::/32` (RFC 3849) used in this example is not meant for production use, replace it with your own ISP-assigned IPv6 prefix (GUA) or local prefix (ULA)
+
///
I want my WireGuard clients in `192.168.0.0/24` and `2001:db8:abc:0::/64`.
diff --git a/docs/content/examples/tutorials/traefik.md b/docs/content/examples/tutorials/traefik.md
index 51b9e134..1760f4f5 100644
--- a/docs/content/examples/tutorials/traefik.md
+++ b/docs/content/examples/tutorials/traefik.md
@@ -5,6 +5,7 @@ title: Traefik
/// note | Opinionated
This guide is opinionated. If you use other conventions or folder layouts, feel free to change the commands and paths.
+
///
## Create docker compose project
diff --git a/docs/content/getting-started.md b/docs/content/getting-started.md
index 406fbf90..a063cbb3 100644
--- a/docs/content/getting-started.md
+++ b/docs/content/getting-started.md
@@ -24,6 +24,7 @@ There are a few requirements for a suitable host system:
On the host, you need to have a suitable container runtime (like _Docker_ or _Podman_) installed. We assume [_Docker Compose_][docker-compose] is [installed][docker-compose-installation]. We have aligned file names and configuration conventions with the latest [Docker Compose specification][docker-compose-specification].
If you're using podman, make sure to read the related [documentation][docs-podman].
+
///
[docker-compose]: https://docs.docker.com/compose/
@@ -69,6 +70,7 @@ When publishing a tag we follow the [Semantic Versioning][semver] specification.
/// danger | Use the Correct Commands For Stopping and Starting `wg-easy`
**Use `sudo docker compose up / down`, not `sudo docker compose start / stop`**. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state.
+
///
**That's it! It really is that easy**.
diff --git a/docs/content/guides/admin.md b/docs/content/guides/admin.md
index 66c765b3..5f3d0572 100644
--- a/docs/content/guides/admin.md
+++ b/docs/content/guides/admin.md
@@ -23,7 +23,9 @@ This feature is currently experimental. While functional, it should be thoroughl
- The feature cannot be enabled if these tools are not available
/// note
+
Most Linux distributions include iptables by default. If you're running in a minimal container environment, you may need to install the `iptables` package on the host system.
+
///
**Enable this feature if you want to:**
diff --git a/docs/content/guides/clients.md b/docs/content/guides/clients.md
index 6314adac..edb514e1 100644
--- a/docs/content/guides/clients.md
+++ b/docs/content/guides/clients.md
@@ -62,7 +62,9 @@ Protocol specifiers (`/tcp` or `/udp`) require a port number. The following form
- **Disable for specific client**: To disable firewall filtering for a single client while keeping it enabled for others, add `0.0.0.0/0, ::/0` to allow all traffic
/// note
+
To allow clients to reach the VPN server itself (e.g. for DNS), include the server's VPN address in the firewall allowed IPs.
+
///
**Use Case Examples**:
diff --git a/docs/content/index.md b/docs/content/index.md
index e15fd9c0..6c6c8616 100644
--- a/docs/content/index.md
+++ b/docs/content/index.md
@@ -9,6 +9,7 @@ hide:
/// info | This Documentation is Versioned
**Make sure** to select the correct version of this documentation! It should match the version of the image you are using. The default version corresponds to [the most recent stable release][docs-tagging].
+
///
This documentation provides you not only with the basic setup and configuration of `wg-easy` but also with advanced configuration, elaborate usage scenarios, detailed examples, hints and more.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
deleted file mode 100644
index 5247b1c8..00000000
--- a/docs/mkdocs.yml
+++ /dev/null
@@ -1,87 +0,0 @@
-site_name: 'wg-easy'
-site_description: 'The easiest way to run WireGuard VPN + Web-based Admin UI.'
-site_author: 'WireGuard Easy'
-copyright: >
-
- © Wireguard Easy
- This project is licensed under AGPL-3.0-only.
- This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Jason A. Donenfeld, ZX2C4 or Edge Security
- "WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld
-
-
-repo_url: https://github.com/wg-easy/wg-easy
-repo_name: wg-easy
-
-edit_uri: 'edit/master/docs/content'
-
-docs_dir: 'content/'
-
-site_url: https://wg-easy.github.io/wg-easy
-
-theme:
- name: material
- favicon: assets/logo/favicon.png
- logo: assets/logo/logo.png
- icon:
- repo: fontawesome/brands/github
- features:
- - navigation.tabs
- - navigation.top
- - navigation.expand
- - navigation.instant
- - content.action.edit
- - content.action.view
- - content.code.annotate
- palette:
- # Light mode
- - media: '(prefers-color-scheme: light)'
- scheme: default
- primary: grey
- accent: red
- toggle:
- icon: material/weather-night
- name: Switch to dark mode
- # Dark mode
- - media: '(prefers-color-scheme: dark)'
- scheme: slate
- primary: grey
- accent: red
- toggle:
- icon: material/weather-sunny
- name: Switch to light mode
-
-extra:
- version:
- provider: mike
-
-markdown_extensions:
- - toc:
- anchorlink: true
- - abbr
- - attr_list
- - pymdownx.blocks.admonition:
- types:
- - danger
- - note
- - info
- - question
- - warning
- - pymdownx.details
- - pymdownx.superfences:
- custom_fences:
- - name: mermaid
- class: mermaid
- format: !!python/name:pymdownx.superfences.fence_code_format
- - pymdownx.tabbed:
- alternate_style: true
- slugify: !!python/object/apply:pymdownx.slugs.slugify
- kwds:
- case: lower
- - pymdownx.tasklist:
- custom_checkbox: true
- - pymdownx.magiclink
- - pymdownx.inlinehilite
- - pymdownx.tilde
- - pymdownx.emoji:
- emoji_index: !!python/name:material.extensions.emoji.twemoji
- emoji_generator: !!python/name:material.extensions.emoji.to_svg
diff --git a/docs/requirements.txt b/docs/requirements.txt
index e0aaf166..5640c9b8 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,4 +1,2 @@
-mkdocs-material
-pillow
-cairosvg
-mike
+zensical==0.0.45
+git+https://github.com/squidfunk/mike.git
diff --git a/docs/zensical.toml b/docs/zensical.toml
new file mode 100644
index 00000000..98a3a977
--- /dev/null
+++ b/docs/zensical.toml
@@ -0,0 +1,97 @@
+[project]
+site_name = "wg-easy"
+site_description = "The easiest way to run WireGuard VPN + Web-based Admin UI."
+site_author = "WireGuard Easy"
+copyright = """
+
+© Wireguard Easy
+This project is licensed under AGPL-3.0-only.
+This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with Jason A. Donenfeld, ZX2C4 or Edge Security
+"WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld
+
+"""
+
+repo_url = "https://github.com/wg-easy/wg-easy"
+repo_name = "wg-easy"
+
+edit_uri = "edit/master/docs/content"
+
+docs_dir = "content/"
+
+site_url = "https://wg-easy.github.io/wg-easy"
+
+[project.theme]
+variant = "modern"
+favicon = "assets/logo/favicon.png"
+logo = "assets/logo/logo.png"
+features = [
+ "navigation.instant",
+ "navigation.tabs",
+ "navigation.expand",
+ "navigation.path",
+ "navigation.top",
+ "content.action.edit",
+ "content.action.view",
+ "content.code.copy",
+ "content.code.annotate",
+]
+
+[project.theme.icon]
+repo = "fontawesome/brands/github"
+
+# Palette toggle for automatic mode
+[[project.theme.palette]]
+media = "(prefers-color-scheme)"
+toggle.icon = "lucide/sun-moon"
+toggle.name = "Switch to light mode"
+
+# Palette toggle for light mode
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+primary = "grey"
+accent = "red"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+# Palette toggle for dark mode
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+primary = "grey"
+accent = "red"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to system preference"
+
+# [project.plugins.privacy]
+
+[project.extra.version]
+provider = "mike"
+
+[project.markdown_extensions.pymdownx.blocks.admonition]
+types = ["danger", "note", "info", "question", "warning"]
+
+[project.markdown_extensions.md_in_html]
+
+[project.markdown_extensions.toc]
+permalink = true
+
+[project.markdown_extensions.pymdownx.details]
+
+[project.markdown_extensions.pymdownx.emoji]
+emoji_generator = "zensical.extensions.emoji.to_svg"
+emoji_index = "zensical.extensions.emoji.twemoji"
+
+[project.markdown_extensions.pymdownx.highlight]
+anchor_linenums = true
+line_spans = "__span"
+pygments_lang_class = true
+
+[project.markdown_extensions.pymdownx.inlinehilite]
+
+[project.markdown_extensions.pymdownx.smartsymbols]
+
+[project.markdown_extensions.pymdownx.superfences]
+custom_fences = [
+ { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
+]
diff --git a/package.json b/package.json
index d95f8df9..a3690fda 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
"dev": "docker compose -f docker-compose.dev.yml up wg-easy --build",
"cli:dev": "docker compose -f docker-compose.dev.yml run --build --rm -it wg-easy cli:dev",
"build": "docker build -t wg-easy .",
- "docs:preview": "docker run --rm -it -p 8080:8080 -v ./docs:/docs squidfunk/mkdocs-material serve -a 0.0.0.0:8080",
+ "docs:preview": "docker run --rm -it -p 8080:8080 -v ./docs:/docs zensical/zensical serve -a 0.0.0.0:8080",
"scripts:version": "bash scripts/version.sh",
"scripts:i18n": "bash scripts/i18n.sh",
"format:check:docs": "prettier --check docs"