If you want to run the setup without any user interaction, e.g. with a tool like Ansible, you can use these environment variables to configure the setup.
+
These will only be used during the first start of the container. After that, the setup will be disabled.
+
+
+
+
Env
+
Example
+
Description
+
Group
+
+
+
+
+
INIT_ENABLED
+
true
+
Enables the below env vars
+
0
+
+
+
INIT_USERNAME
+
admin
+
Sets admin username
+
1
+
+
+
INIT_PASSWORD
+
Se!ureP%ssw
+
Sets admin password
+
1
+
+
+
INIT_HOST
+
vpn.example.com
+
Host clients will connect to
+
1
+
+
+
INIT_PORT
+
51820
+
Port clients will connect to and wireguard will listen on
+
1
+
+
+
INIT_DNS
+
1.1.1.1,8.8.8.8
+
Sets global dns setting
+
2
+
+
+
INIT_IPV4_CIDR
+
10.8.0.0/24
+
Sets IPv4 cidr
+
3
+
+
+
INIT_IPV6_CIDR
+
2001:0DB8::/32
+
Sets IPv6 cidr
+
3
+
+
+
+
+
Variables have to be used together
+
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
+
+
+
Security
+
The initial username and password is not checked for complexity. Make sure to set a long enough username and a secure password. Otherwise, the user won't be able to log in.
+
Its recommended to remove the variables after the setup is done to prevent the password from being exposed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/Pre-release/advanced/metrics/prometheus/index.html b/Pre-release/advanced/metrics/prometheus/index.html
index 02446f0d..c3c276b9 100644
--- a/Pre-release/advanced/metrics/prometheus/index.html
+++ b/Pre-release/advanced/metrics/prometheus/index.html
@@ -15,14 +15,14 @@
-
+
-
+
@@ -526,6 +526,28 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/Pre-release/search/search_index.json b/Pre-release/search/search_index.json
index 60a001c5..3ca5ae4a 100644
--- a/Pre-release/search/search_index.json
+++ b/Pre-release/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to the Documentation for wg-easy","text":"
\u00a0This 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.
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.
"},{"location":"#about","title":"About","text":"
wg-easy is the easiest way to run WireGuard VPN + Web-based Admin UI.
If you're new to wg-easy, make sure to read the Getting Started chapter first. If you want to look at examples for Docker Run and Compose, we have an Examples page.
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.
There are a few requirements for a suitable host system:
You need to have a container runtime installed
About the Container Runtime
On the host, you need to have a suitable container runtime (like Docker or Podman) installed. We assume Docker Compose is installed. We have aligned file names and configuration conventions with the latest Docker Compose specification. If you're using podman, make sure to read the related documentation.
"},{"location":"getting-started/#deploying-the-actual-image","title":"Deploying the Actual Image","text":""},{"location":"getting-started/#tagging-convention","title":"Tagging Convention","text":"
To understand which tags you should use, read this section carefully. Our CI will automatically build, test and push new images to the following container registry:
All workflows are using the tagging convention listed below. It is subsequently applied to all images.
Event Image Tags cron on masternightlypush a tag (v1.2.3) 1.2.3, 1.2, 1, latest
When publishing a tag we follow the Semantic Versioning specification. The latest tag is always pointing to the latest stable release. If you want to avoid breaking changes, use the major version tag (e.g. 15).
"},{"location":"getting-started/#get-all-files","title":"Get All Files","text":"
Issue the following command to acquire the necessary file:
"},{"location":"getting-started/#stopping-the-container","title":"Stopping the Container","text":"
To stop the container, issue the following command:
sudo docker compose down\n
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.
If you need more help you can read the Basic Installation Tutorial.
Env Default Example Description PORT518216789 TCP port for Web UI. HOST0.0.0.0localhost IP address web UI binds to. INSECUREfalsetrue If access over http is allowed"},{"location":"advanced/metrics/prometheus/","title":"Prometheus","text":"
When refactoring, writing or altering files, adhere to these rules:
Adjust your style of coding to the style that is already present! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all files consistent.
Use pnpm lint to check your scripts! Your contributions are checked by GitHub Actions too, so you will need to do this.
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. Run
pnpm docs:serve\n
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.
"},{"location":"contributing/issues-and-pull-requests/","title":"Issues and Pull Requests","text":"
This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the documentation.
"},{"location":"contributing/issues-and-pull-requests/#opening-an-issue","title":"Opening an Issue","text":"
Attention
Before opening an issue, read the README carefully, study the docs for your version (maybe 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
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.
Maintainers take the time to improve on this project and help by solving issues together. It is therefore expected from others to make an effort and comply with the rules.
"},{"location":"contributing/issues-and-pull-requests/#filing-a-bug-report","title":"Filing a Bug Report","text":"
Thank you for participating in this project and reporting a bug. wg-easy is a community-driven project, and each contribution counts!
Maintainers and moderators are volunteers. We greatly appreciate reports that take the time to provide detailed information via the template, enabling us to help you in the best and quickest way. Ignoring the template provided may seem easier, but discourages receiving any support (via assignment of the label meta/no template - no support).
Markdown formatting can be used in almost all text fields (unless stated otherwise in the description).
Be as precise as possible, and if in doubt, it's best to add more information that too few.
When an option is marked with \"not officially supported\" / \"unsupported\", then support is dependent on availability from specific maintainers.
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.
"},{"location":"contributing/issues-and-pull-requests/#submit-a-pull-request","title":"Submit a Pull-Request","text":"
The development workflow is the following:
Fork the project
Write the code that is needed :D
Document your improvements if necessary
Commit (and sign your commit), 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.
Create a file /etc/containers/systemd/wg-easy/wg-easy.container with the following content:
[Container]\nContainerName=wg-easy\nImage=ghcr.io/wg-easy/wg-easy:15\nAutoUpdate=registry\n\nVolume=/etc/containers/volumes/wg-easy:/etc/wireguard:Z\nNetwork=wg-easy.network\nPublishPort=51820:51820/udp\nPublishPort=51821:51821/tcp\n\n# this is used to allow access over HTTP\n# remove this when using a reverse proxy\nEnvironment=INSECURE=true\n\nAddCapability=NET_ADMIN\nAddCapability=SYS_MODULE\nAddCapability=NET_RAW\nSysctl=net.ipv4.ip_forward=1\nSysctl=net.ipv4.conf.all.src_valid_mark=1\nSysctl=net.ipv6.conf.all.disable_ipv6=0\nSysctl=net.ipv6.conf.all.forwarding=1\nSysctl=net.ipv6.conf.default.forwarding=1\n\n[Install]\n# this is used to start the container on boot\nWantedBy=default.target\n
Create a file /etc/containers/systemd/wg-easy/wg-easy.network with the following content:
"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome to the Documentation for wg-easy","text":"
\u00a0This 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.
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.
"},{"location":"#about","title":"About","text":"
wg-easy is the easiest way to run WireGuard VPN + Web-based Admin UI.
If you're new to wg-easy, make sure to read the Getting Started chapter first. If you want to look at examples for Docker Run and Compose, we have an Examples page.
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.
There are a few requirements for a suitable host system:
You need to have a container runtime installed
About the Container Runtime
On the host, you need to have a suitable container runtime (like Docker or Podman) installed. We assume Docker Compose is installed. We have aligned file names and configuration conventions with the latest Docker Compose specification. If you're using podman, make sure to read the related documentation.
"},{"location":"getting-started/#deploying-the-actual-image","title":"Deploying the Actual Image","text":""},{"location":"getting-started/#tagging-convention","title":"Tagging Convention","text":"
To understand which tags you should use, read this section carefully. Our CI will automatically build, test and push new images to the following container registry:
All workflows are using the tagging convention listed below. It is subsequently applied to all images.
Event Image Tags cron on masternightlypush a tag (v1.2.3) 1.2.3, 1.2, 1, latest
When publishing a tag we follow the Semantic Versioning specification. The latest tag is always pointing to the latest stable release. If you want to avoid breaking changes, use the major version tag (e.g. 15).
"},{"location":"getting-started/#get-all-files","title":"Get All Files","text":"
Issue the following command to acquire the necessary file:
"},{"location":"getting-started/#stopping-the-container","title":"Stopping the Container","text":"
To stop the container, issue the following command:
sudo docker compose down\n
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.
If you need more help you can read the Basic Installation Tutorial.
Env Default Example Description PORT518216789 TCP port for Web UI. HOST0.0.0.0localhost IP address web UI binds to. INSECUREfalsetrue If access over http is allowed"},{"location":"advanced/config/unattended-setup/","title":"Unattended Setup","text":"
If you want to run the setup without any user interaction, e.g. with a tool like Ansible, you can use these environment variables to configure the setup.
These will only be used during the first start of the container. After that, the setup will be disabled.
Env Example Description Group INIT_ENABLEDtrue Enables the below env vars 0 INIT_USERNAMEadmin Sets admin username 1 INIT_PASSWORDSe!ureP%ssw Sets admin password 1 INIT_HOSTvpn.example.com Host clients will connect to 1 INIT_PORT51820 Port clients will connect to and wireguard will listen on 1 INIT_DNS1.1.1.1,8.8.8.8 Sets global dns setting 2 INIT_IPV4_CIDR10.8.0.0/24 Sets IPv4 cidr 3 INIT_IPV6_CIDR2001:0DB8::/32 Sets IPv6 cidr 3
\u00a0Variables have to be used together
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
Security
The initial username and password is not checked for complexity. Make sure to set a long enough username and a secure password. Otherwise, the user won't be able to log in.
Its recommended to remove the variables after the setup is done to prevent the password from being exposed.
When refactoring, writing or altering files, adhere to these rules:
Adjust your style of coding to the style that is already present! Even if you do not like it, this is due to consistency. There was a lot of work involved in making all files consistent.
Use pnpm lint to check your scripts! Your contributions are checked by GitHub Actions too, so you will need to do this.
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. Run
pnpm docs:serve\n
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.
"},{"location":"contributing/issues-and-pull-requests/","title":"Issues and Pull Requests","text":"
This project is Open Source. That means that you can contribute on enhancements, bug fixing or improving the documentation.
"},{"location":"contributing/issues-and-pull-requests/#opening-an-issue","title":"Opening an Issue","text":"
Attention
Before opening an issue, read the README carefully, study the docs for your version (maybe 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
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.
Maintainers take the time to improve on this project and help by solving issues together. It is therefore expected from others to make an effort and comply with the rules.
"},{"location":"contributing/issues-and-pull-requests/#filing-a-bug-report","title":"Filing a Bug Report","text":"
Thank you for participating in this project and reporting a bug. wg-easy is a community-driven project, and each contribution counts!
Maintainers and moderators are volunteers. We greatly appreciate reports that take the time to provide detailed information via the template, enabling us to help you in the best and quickest way. Ignoring the template provided may seem easier, but discourages receiving any support (via assignment of the label meta/no template - no support).
Markdown formatting can be used in almost all text fields (unless stated otherwise in the description).
Be as precise as possible, and if in doubt, it's best to add more information that too few.
When an option is marked with \"not officially supported\" / \"unsupported\", then support is dependent on availability from specific maintainers.
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.
"},{"location":"contributing/issues-and-pull-requests/#submit-a-pull-request","title":"Submit a Pull-Request","text":"
The development workflow is the following:
Fork the project
Write the code that is needed :D
Document your improvements if necessary
Commit (and sign your commit), 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.
Create a file /etc/containers/systemd/wg-easy/wg-easy.container with the following content:
[Container]\nContainerName=wg-easy\nImage=ghcr.io/wg-easy/wg-easy:15\nAutoUpdate=registry\n\nVolume=/etc/containers/volumes/wg-easy:/etc/wireguard:Z\nNetwork=wg-easy.network\nPublishPort=51820:51820/udp\nPublishPort=51821:51821/tcp\n\n# this is used to allow access over HTTP\n# remove this when using a reverse proxy\nEnvironment=INSECURE=true\n\nAddCapability=NET_ADMIN\nAddCapability=SYS_MODULE\nAddCapability=NET_RAW\nSysctl=net.ipv4.ip_forward=1\nSysctl=net.ipv4.conf.all.src_valid_mark=1\nSysctl=net.ipv6.conf.all.disable_ipv6=0\nSysctl=net.ipv6.conf.all.forwarding=1\nSysctl=net.ipv6.conf.default.forwarding=1\n\n[Install]\n# this is used to start the container on boot\nWantedBy=default.target\n
Create a file /etc/containers/systemd/wg-easy/wg-easy.network with the following content: