From 7fb4150a95fbe6877470298358f783467180dd5c Mon Sep 17 00:00:00 2001 From: Bernd Storath <999999bst@gmail.com> Date: Tue, 4 Mar 2025 12:47:19 +0100 Subject: [PATCH] improve docs --- docker-compose.yml | 8 +- .../config/advanced/optional-config.md | 4 +- docs/content/config/advanced/podman.md | 5 - docs/content/contributing/general.md | 8 +- .../contributing/issues-and-pull-requests.md | 23 +++-- .../examples/tutorials/basic-installation.md | 7 ++ docs/content/examples/tutorials/dockerless.md | 5 + docs/content/examples/tutorials/podman.md | 97 +++++++++++++++++++ docs/content/index.md | 5 +- docs/content/usage.md | 52 ++++++---- docs/mkdocs.yml | 8 +- package.json | 3 +- 12 files changed, 176 insertions(+), 49 deletions(-) delete mode 100644 docs/content/config/advanced/podman.md create mode 100644 docs/content/examples/tutorials/dockerless.md create mode 100644 docs/content/examples/tutorials/podman.md diff --git a/docker-compose.yml b/docker-compose.yml index e77a27ad..9260fcd3 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -3,10 +3,10 @@ volumes: services: wg-easy: - environment: - - PORT=51821 - # Optional: - # - HOST=0.0.0.0 + #environment: + # Optional: + # - PORT=51821 + # - HOST=0.0.0.0 image: ghcr.io/wg-easy/wg-easy container_name: wg-easy diff --git a/docs/content/config/advanced/optional-config.md b/docs/content/config/advanced/optional-config.md index 74565bce..7937cfa0 100644 --- a/docs/content/config/advanced/optional-config.md +++ b/docs/content/config/advanced/optional-config.md @@ -1,3 +1,5 @@ --- -title: 'Optional Configuration' +title: Optional Configuration --- + +TODO diff --git a/docs/content/config/advanced/podman.md b/docs/content/config/advanced/podman.md deleted file mode 100644 index dc4ba708..00000000 --- a/docs/content/config/advanced/podman.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Podman ---- - -TODO diff --git a/docs/content/contributing/general.md b/docs/content/contributing/general.md index 018f1ca3..c7720ead 100644 --- a/docs/content/contributing/general.md +++ b/docs/content/contributing/general.md @@ -1,5 +1,5 @@ --- -title: 'General Information' +title: General Information --- ## Coding Style @@ -14,10 +14,10 @@ When refactoring, writing or altering files, adhere to these rules: Make sure to select `nightly` in the dropdown menu at the top. Navigate to the page you would like to edit and click the edit button in the top right. This allows you to make changes and create a pull-request. -Alternatively you can make the changes locally. For that you'll need to have Docker installed. Navigate into the `docs/` directory. Then run: +Alternatively you can make the changes locally. For that you'll need to have Docker installed. Run ```sh -docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material +pnpm docs:serve ``` -This serves the documentation on your local machine on port `8000`. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result. +This serves the documentation on your local machine on port `8080`. Each change will be hot-reloaded onto the page you view, just edit, save and look at the result. diff --git a/docs/content/contributing/issues-and-pull-requests.md b/docs/content/contributing/issues-and-pull-requests.md index b9e51120..82ace683 100644 --- a/docs/content/contributing/issues-and-pull-requests.md +++ b/docs/content/contributing/issues-and-pull-requests.md @@ -1,20 +1,22 @@ --- -title: 'Issues and Pull Requests' +title: Issues and Pull Requests --- This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the documentation. ## Opening an Issue -!!! attention +/// 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! +**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. -!!! attention +/// note | Attention - **Use the issue templates** to provide the necessary information. Issues which do not use these templates are not worked on and closed. +**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. @@ -34,18 +36,19 @@ When an option is marked with "not officially supported" / "unsupported", then s ## Pull Requests -!!! question "Motivation" +/// 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. +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 The development workflow is the following: -1. Fork the project and clone your fork with `git clone --recurse-submodules ...` or run `git submodule update --init --recursive` after you cloned your fork +1. Fork the project 2. Write the code that is needed :D -5. Document your improvements if necessary -6. [Commit][commit] (and [sign your commit][gpg]), push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. +3. Document your improvements if necessary +4. [Commit][commit] (and [sign your commit][gpg]), push and create a pull-request to merge into `master`. Please **use the pull-request template** to provide a minimum of contextual information and make sure to meet the requirements of the checklist. Pull requests are automatically tested against the CI and will be reviewed when tests pass. When your changes are validated, your branch is merged. CI builds the new `:nightly` image every night and your changes will be includes in the next version release. diff --git a/docs/content/examples/tutorials/basic-installation.md b/docs/content/examples/tutorials/basic-installation.md index e69de29b..2ec62572 100644 --- a/docs/content/examples/tutorials/basic-installation.md +++ b/docs/content/examples/tutorials/basic-installation.md @@ -0,0 +1,7 @@ +--- +title: Basic Installation +--- + + + +TODO diff --git a/docs/content/examples/tutorials/dockerless.md b/docs/content/examples/tutorials/dockerless.md new file mode 100644 index 00000000..c8377eb9 --- /dev/null +++ b/docs/content/examples/tutorials/dockerless.md @@ -0,0 +1,5 @@ +--- +title: Without Docker +--- + +TODO diff --git a/docs/content/examples/tutorials/podman.md b/docs/content/examples/tutorials/podman.md new file mode 100644 index 00000000..bd1d6982 --- /dev/null +++ b/docs/content/examples/tutorials/podman.md @@ -0,0 +1,97 @@ +--- +title: Podman +--- + +# Podman + +This guide will show you how to run `wg-easy` with rootful Podman and nftables. + +## Requirements + +1. Podman installed with version 4.4 or higher + +## Configuration + +Create a Folder for the configuration files: + +```shell +sudo mkdir -p /etc/containers/systemd/wg-easy +sudo mkdir -p /etc/containers/volumes/wg-easy +``` + +Create a file `/etc/containers/systemd/wg-easy/wg-easy.container` with the following content: + +```ini +[Container] +ContainerName=wg-easy +Image=ghcr.io/wg-easy/wg-easy:latest + +Volume=/etc/containers/volumes/wg-easy:/etc/wireguard:Z +Network=wg-easy.network +PublishPort=51820:51820/udp +PublishPort=51821:51821/tcp + +AddCapability=NET_ADMIN +AddCapability=SYS_MODULE +AddCapability=NET_RAW +Sysctl=net.ipv4.ip_forward=1 +Sysctl=net.ipv4.conf.all.src_valid_mark=1 +Sysctl=net.ipv6.conf.all.disable_ipv6=0 +Sysctl=net.ipv6.conf.all.forwarding=1 +Sysctl=net.ipv6.conf.default.forwarding=1 + +[Install] +# this is used to start the container on boot +WantedBy=default.target +``` + +Create a file `/etc/containers/systemd/wg-easy/wg-easy.network` with the following content: + +```ini +[Network] +NetworkName=wg-easy +IPv6=true +``` + +## Load Kernel Modules + +You will need to load the following kernel modules + +```txt +wireguard +nft_masq +``` + +Create a file `/etc/modules-load.d/wg-easy.conf` with the following content: + +```txt +wireguard +nft_masq +``` + +## Start the Container + +```shell +sudo systemctl daemon-reload +sudo systemctl start wg-easy +``` + +## Edit Hooks + +In the Admin Panel of your WireGuard server, go to the `Hooks` tab and add the following hook: + +1. PostUp + +```shell +apk add nftables; nft add table inet wg_table; nft add chain inet wg_table postrouting { type nat hook postrouting priority 100 \; }; nft add rule inet wg_table postrouting ip saddr {{ipv4Cidr}} oifname {{device}} masquerade; nft add rule inet wg_table postrouting ip6 saddr {{ipv6Cidr}} oifname {{device}} masquerade; nft add chain inet wg_table input { type filter hook input priority 0 \; }; nft add rule inet wg_table input udp dport {{port}} accept; nft add chain inet wg_table forward { type filter hook forward priority 0 \; }; nft add rule inet wg_table forward iifname "wg0" accept; nft add rule inet wg_table forward oifname "wg0" accept; +``` + +2. PostDown + +```shell +nft delete table inet wg_table +``` + + diff --git a/docs/content/index.md b/docs/content/index.md index 8f0f6c57..6d51bdf2 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -6,9 +6,10 @@ hide: # Welcome to the Documentation for `wg-easy` -!!! info "This Documentation is Versioned" +/// 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 `:latest` image tag - [the most recent stable release][docs-tagging]. +**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 `:latest` image tag - [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/content/usage.md b/docs/content/usage.md index 0d274de3..50d3140a 100644 --- a/docs/content/usage.md +++ b/docs/content/usage.md @@ -4,32 +4,32 @@ hide: - navigation --- -This page explains how to get started with wg-easy. The guide uses Docker Compose as a reference. In our examples, a volume mounts the named volume [`etc_wireguard`][docs::dms-volumes-config] to `/etc/wireguard` inside the container. - -[docs::dms-volumes-config]: ./config/advanced/optional-config.md#volumes-config +This page explains how to get started with wg-easy. The guide uses Docker Compose as a reference. In our examples, we mount the named volume `etc_wireguard` to `/etc/wireguard` inside the container. ## Preliminary Steps Before you can get started with deploying your own VPN, there are some requirements to be met: -1. You need to have a host that you can manage. +1. You need to have a host that you can manage +2. You need to have a domain name or a public IP address +3. You need a supported architecture (x86_64, arm64) ### Host Setup There are a few requirements for a suitable host system: -TODO: Requirements - -!!! note "About the Container Runtime" +1. You need to have a container runtime installed - 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]. +/// note | About the Container Runtime - If you're using podman, make sure to read the related [documentation][docs-podman]. +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/ [docker-compose-installation]: https://docs.docker.com/compose/install/ [docker-compose-specification]: https://docs.docker.com/compose/compose-file/ -[docs-podman]: ./config/advanced/podman.md +[docs-podman]: ./examples/tutorials/podman.md ## Deploying the Actual Image @@ -37,12 +37,12 @@ TODO: Requirements To understand which tags you should use, read this section carefully. [Our CI][github-ci] will automatically build, test and push new images to the following container registry: -2. GitHub Container Registry ([`ghcr.io/wg-easy/wg-easy`][ghcr-image]) +1. GitHub Container Registry ([`ghcr.io/wg-easy/wg-easy`][ghcr-image]) All workflows are using the tagging convention listed below. It is subsequently applied to all images. | Event | Image Tags | -|-------------------------|-------------------------------| +| ----------------------- | ----------------------------- | | `cron` on `master` | `nightly` | | `push` a tag (`v1.2.3`) | `1.2.3`, `1.2`, `1`, `latest` | @@ -53,23 +53,33 @@ All workflows are using the tagging convention listed below. It is subsequently Issue the following command to acquire the necessary file: -``` BASH +```shell wget "https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml" ``` -### Configuration Steps +### Start the Container + +To start the container, issue the following command: + +```shell +sudo docker compose up -d +``` -1. First edit `docker-compose.yml` to your liking -2. Then configure the everything in the UI +### Configuration Steps -### Get Up and Running +Now follow the setup process in your web browser -!!! danger "Using the Correct Commands For Stopping and Starting DMS" +### Stopping the Container - **Use `docker compose up / down`, not `docker compose start / stop`**. Otherwise, the container is not properly destroyed and you may experience problems during startup because of inconsistent state. +To stop the container, issue the following command: - Using `Ctrl+C` **is not supported either**! +```shell +sudo docker compose down +``` -**That's it! It really is that easy**. +/// danger | Using 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/mkdocs.yml b/docs/mkdocs.yml index a32a174f..2e0f888c 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -53,7 +53,13 @@ markdown_extensions: anchorlink: true - abbr - attr_list - - admonition + - pymdownx.blocks.admonition: + types: + - danger + - note + - info + - question + - warning - pymdownx.details - pymdownx.superfences: custom_fences: diff --git a/package.json b/package.json index 938ee103..a22d1060 100644 --- a/package.json +++ b/package.json @@ -3,7 +3,8 @@ "private": true, "scripts": { "dev": "docker compose -f docker-compose.dev.yml up --build", - "build": "docker build -t wg-easy ." + "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" }, "packageManager": "pnpm@10.5.2" }