apps/wg-easy
1
0
Fork 0
mirror of https://github.com/wg-easy/wg-easy.git synced 2025-09-26 19:51:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

improve docs, add version script

Browse Source
This commit is contained in:
Bernd Storath
2025-03-07 12:00:45 +01:00
parent e5fb6ff3a6
commit 9a029eeb23
15 changed files with 236 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

102
README.md
View File

@@ -42,8 +42,21 @@ You have found the easiest way to install & manage WireGuard on any Linux host!
> [!NOTE]
> To better manage documentation for this project, it has its own site here: [https://wg-easy.github.io/wg-easy/latest](https://wg-easy.github.io/wg-easy/latest)
<!-- TODO: remove after release -->
> [!WARNING]
> As the Docs are still in Pre-release, you can access them here [https://wg-easy.github.io/wg-easy/Pre-release](https://wg-easy.github.io/wg-easy/Pre-release)
- [Getting Started](https://wg-easy.github.io/wg-easy/latest/getting-started/)
- [Basic Installation](https://wg-easy.github.io/wg-easy/latest/examples/tutorials/basic-installation/)
- [Caddy](https://wg-easy.github.io/wg-easy/latest/examples/tutorials/caddy/)
- [Nginx](https://wg-easy.github.io/wg-easy/latest/examples/tutorials/nginx/)
- [Traefik](https://wg-easy.github.io/wg-easy/latest/examples/tutorials/traefik/)
- [Podman](https://wg-easy.github.io/wg-easy/latest/examples/tutorials/podman/)
- [AdGuard Home](https://wg-easy.github.io/wg-easy/latest/examples/tutorials/adguard/)
> [!NOTE]
> If you want to migrate from the old version to the new version, you can find the migration guide here: [Migration Guide](https://wg-easy.github.io/wg-easy/latest/advanced/migrate/)
## Requirements
@@ -89,51 +102,6 @@ Now setup a reverse proxy to be able to access the Web UI from the internet.
If you want to access the Web UI over HTTP, change the env var `INSECURE` to `true`. This is not recommended. Only use this for testing
<!-- TOOD: add to docs: Grafana dashboard [21733](https://grafana.com/grafana/dashboards/21733-wireguard/) -->
<!-- TOOD: add to docs
To setup the IPv6 Network, simply run once:
```bash
docker network create \
-d bridge --ipv6 \
-d default \
--subnet 10.42.42.0/24 \
--subnet fdcc:ad94:bacf:61a3::/64 wg \
```
To automatically install & run wg-easy, simply run:
```bash
docker run -d \
--net wg \
-e PORT=51821 \
--name wg-easy \
--ip6 fdcc:ad94:bacf:61a3::2a \
--ip 10.42.42.42 \
-v ~/.wg-easy:/etc/wireguard \
-v /lib/modules:/lib/modules:ro \
-p 51820:51820/udp \
-p 51821:51821/tcp \
--cap-add NET_ADMIN \
--cap-add SYS_MODULE \
--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 \
--restart unless-stopped \
ghcr.io/wg-easy/wg-easy
```
The Web UI will now be available on `http://0.0.0.0:51821`.
The Prometheus metrics will now be available on `http://0.0.0.0:51821/api/metrics`. Grafana dashboard [21733](https://grafana.com/grafana/dashboards/21733-wireguard/)
> 💡 Your configuration files will be saved in `~/.wg-easy`
-->
### 3. Sponsor
Are you enjoying this project? Consider donating.
@@ -142,46 +110,30 @@ Founder: [Buy Emile a beer!](https://github.com/sponsors/WeeJeWel) 🍻
Maintainer: [Buy kaaax0815 a coffee!](https://github.com/sponsors/kaaax0815) ☕
<!-- TOOD: add to docs
## Development
## Options
### Prerequisites
These options can be configured by setting environment variables using `-e KEY="VALUE"` in the `docker run` command.
- Docker
- Node LTS & corepack enabled
- Visual Studio Code
| Env | Default | Example | Description |
| ---------- | --------- | ----------- | ------------------------------ |
| `PORT`. | `51821` | `6789` | TCP port for Web UI. |
| `HOST` | `0.0.0.0` | `localhost` | IP address web UI binds to. |
| `INSECURE` | `false` | `true` | If access over http is allowed |
### Dev Server
## Updating
To update to the latest version, simply run:
This starts the development server with docker
```shell
docker stop wg-easy
docker rm wg-easy
docker pull ghcr.io/wg-easy/wg-easy
pnpm dev
```
And then run the `docker run -d \ ...` command above again.
### Update Auto Imports
With Docker Compose WireGuard Easy can be updated with a single command:
`docker compose up --detach --pull always` (if an image tag is specified in the
Compose file and it is not `latest`, make sure that it is changed to the desired
one; by default it is omitted and
[defaults to `latest`](https://docs.docker.com/engine/reference/run/#image-references)). \
The WireGuard Easy container will be automatically recreated if a newer image
was pulled.
If you add something that should be auto-importable and VSCode complains, run:
## Common Use Cases
- [Using WireGuard-Easy with Pi-Hole](https://github.com/wg-easy/wg-easy/wiki/Using-WireGuard-Easy-with-Pi-Hole)
- [Using WireGuard-Easy with nginx/SSL](https://github.com/wg-easy/wg-easy/wiki/Using-WireGuard-Easy-with-nginx-SSL)
For less common or specific edge-case scenarios, please refer to the detailed information provided in the [Wiki](https://github.com/wg-easy/wg-easy/wiki).
-->
```shell
cd src
pnpm install
```
## License

4
docker-compose.yml
View File

@@ -9,7 +9,7 @@ services:
# - HOST=0.0.0.0
# - INSECURE=false
image: ghcr.io/wg-easy/wg-easy
image: ghcr.io/wg-easy/wg-easy:15
container_name: wg-easy
networks:
wg:
@@ -25,7 +25,7 @@ services:
cap_add:
- NET_ADMIN
- SYS_MODULE
# - NET_RAW # ⚠️ Uncomment if using Podman
# - NET_RAW # ⚠️ Uncomment if using Podman Compose
sysctls:
- net.ipv4.ip_forward=1
- net.ipv4.conf.all.src_valid_mark=1

6
docs/content/advanced/config/optional-config.md
View File

@@ -3,3 +3,9 @@ title: Optional Configuration
---
TODO
| Env | Default | Example | Description |
| ---------- | --------- | ----------- | ------------------------------ |
| `PORT` | `51821` | `6789` | TCP port for Web UI. |
| `HOST` | `0.0.0.0` | `localhost` | IP address web UI binds to. |
| `INSECURE` | `false` | `true` | If access over http is allowed |

7
docs/content/advanced/metrics/prometheus.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Prometheus
---
TODO
<!-- TOOD: add to docs: Grafana dashboard [21733](https://grafana.com/grafana/dashboards/21733-wireguard/) -->

7
docs/content/advanced/migrate/index.md Normal file
View File

@@ -0,0 +1,7 @@
---
title: Migrate
---
If you want to migrate from an older version of `wg-easy` to the new version, you can find the migration guides listed below.
- [Migrate from v14 to v15](./from-14-to-15.md) : This guide should also work for any version before `v14`.

5
docs/content/examples/tutorials/adguard.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: AdGuard Home
---
TODO

34
docs/content/examples/tutorials/auto-updates.md Normal file
View File

@@ -0,0 +1,34 @@
---
title: Auto Updates
---
## Docker Compose
With Docker Compose WireGuard Easy can be updated with a single command:
Replace `$DIR` with the directory where your `docker-compose.yml` is located.
```shell
cd $DIR
sudo docker compose -f up -d --pull always
```
## Docker Run
```shell
sudo docker stop wg-easy
sudo docker rm wg-easy
sudo docker pull ghcr.io/wg-easy/wg-easy
```
And then run the `docker run -d \ ...` command from [Docker Run][docker-run] again.
[docker-run]: ./docker-run.md
## Podman
To update `wg-easy` (and every container that has auto updates enabled), you can run the following commands:
```shell
sudo podman auto-update
```

17
docs/content/examples/tutorials/basic-installation.md
View File

@@ -27,7 +27,7 @@ Follow the Docs here: <https://docs.docker.com/engine/install/> and install Dock
2. Download docker compose file
```shell
sudo curl -o $URL/docker-compose.yml https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml
sudo curl -o $DIR/docker-compose.yml https://raw.githubusercontent.com/wg-easy/wg-easy/master/docker-compose.yml
```
3. Start `wg-easy`
@@ -54,3 +54,18 @@ TODO
Open your browser and navigate to `https://<your-domain>:51821` or `https://<your-ip>:51821`.
Follow the instructions to set up your WireGuard VPN.
## Update `wg-easy`
To update `wg-easy` to the latest version, run:
```shell
sudo docker-compose -f $DIR/docker-compose.yml pull
sudo docker-compose -f $DIR/docker-compose.yml up -d
```
## Auto Update
If you want to enable auto-updates, follow the instructions here: [Auto Updates][auto-updates]
[auto-updates]: ./auto-updates.md

5
docs/content/examples/tutorials/caddy.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: Caddy
---
TODO

43
docs/content/examples/tutorials/docker-run.md Normal file
View File

@@ -0,0 +1,43 @@
---
title: Docker Run
---
To setup the IPv6 Network, simply run once:
```bash
docker network create \
-d bridge --ipv6 \
-d default \
--subnet 10.42.42.0/24 \
--subnet fdcc:ad94:bacf:61a3::/64 wg \
```
<!-- ref: major version -->
To automatically install & run wg-easy, simply run:
```bash
docker run -d \
--net wg \
-e INSECURE=true \
--name wg-easy \
--ip6 fdcc:ad94:bacf:61a3::2a \
--ip 10.42.42.42 \
-v ~/.wg-easy:/etc/wireguard \
-v /lib/modules:/lib/modules:ro \
-p 51820:51820/udp \
-p 51821:51821/tcp \
--cap-add NET_ADMIN \
--cap-add SYS_MODULE \
--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 \
--restart unless-stopped \
ghcr.io/wg-easy/wg-easy:15
```
The Web UI will now be available on `http://0.0.0.0:51821`.
> 💡 Your configuration files will be saved in `~/.wg-easy`

5
docs/content/examples/tutorials/nginx.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: NGINX
---
TODO

19
docs/content/examples/tutorials/podman.md
View File

@@ -19,16 +19,23 @@ sudo mkdir -p /etc/containers/volumes/wg-easy
Create a file `/etc/containers/systemd/wg-easy/wg-easy.container` with the following content:
<!-- ref: major version -->
```ini
[Container]
ContainerName=wg-easy
Image=ghcr.io/wg-easy/wg-easy:latest
Image=ghcr.io/wg-easy/wg-easy:15
AutoUpdate=registry
Volume=/etc/containers/volumes/wg-easy:/etc/wireguard:Z
Network=wg-easy.network
PublishPort=51820:51820/udp
PublishPort=51821:51821/tcp
# this is used to allow access over HTTP
# remove this when using a reverse proxy
Environment=INSECURE=true
AddCapability=NET_ADMIN
AddCapability=SYS_MODULE
AddCapability=NET_RAW
@@ -90,6 +97,16 @@ In the Admin Panel of your WireGuard server, go to the `Hooks` tab and add the f
nft delete table inet wg_table
```
If you don't have iptables loaded on your server, you could see many errors in the logs or in the UI. You can ignore them.
## Restart the Container
Restart the container to apply the new hooks:
```shell
sudo systemctl restart wg-easy
```
<!--
TODO: improve docs after better nftables support
TODO: fix accept web ui port

5
docs/content/examples/tutorials/traefik.md Normal file
View File

@@ -0,0 +1,5 @@
---
title: Traefik
---
TODO

3
package.json
View File

@@ -4,7 +4,8 @@
"scripts": {
"dev": "docker compose -f docker-compose.dev.yml up --build",
"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 squidfunk/mkdocs-material serve -a 0.0.0.0:8080",
"scripts:version": "bash scripts/version.sh"
},
"packageManager": "pnpm@10.5.2"
}

54
scripts/version.sh Normal file
View File

@@ -0,0 +1,54 @@
#!/bin/bash
package_json="src/package.json"
# Function to update the version in package.json
update_version() {
local new_version=$1
jq --arg new_version "$new_version" '.version = $new_version' $package_json > tmp.json && mv tmp.json $package_json
}
# Get the current version from package.json
current_version=$(jq -r '.version' $package_json)
echo "Current version: $current_version"
# Prompt the user for the new version
read -p "Enter the new version (following SemVer): " new_version
# Official SemVer regex for validation
semver_regex="^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$"
# Validate the new version
if ! echo "$new_version" | grep -Eq "$semver_regex"; then
echo "Invalid version format. Please use SemVer format (e.g., 1.0.0 or 1.0.0-alpha)."
exit 1
fi
# Update the version in package.json
update_version $new_version
echo "Updated package.json to version $new_version"
echo "----"
echo "If you changed the major version, remember to update the docker-compose.yml file and docs (search for: ref: major version)"
echo "----"
echo "If you did everything press 'y' to commit the changes and create a new tag"
read -p "Do you want to continue? (y/n): " confirm
if [ "$confirm" != "y" ]; then
echo "Aborted."
exit 1
fi
# Commit the changes
git add $package_json
git commit -m "Bump version to $new_version"
echo "Committed the changes"
# Create a new Git tag
git tag -a "v$new_version" -m "Release version $new_version"
echo "Created Git tag v$new_version"
# Push the commit & tag to the remote repository
git push origin master --follow-tags
echo "Pushed Git commit and tag v$new_version to remote repository"