diff --git a/docker/Dockerfile b/docker/Dockerfile index c07d7b5..97a1481 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -2,12 +2,15 @@ FROM golang:1.24 AS compiler WORKDIR /go RUN apt-get update && apt-get install -y --no-install-recommends \ - git make bash build-essential \ - && apt-get clean && rm -rf /var/lib/apt/lists/* + git make bash build-essential \ + && apt-get clean \ + && rm -rf /var/lib/apt/lists/* -RUN git clone --depth=1 https://github.com/amnezia-vpn/amneziawg-tools.git && \ - git clone --depth=1 https://github.com/amnezia-vpn/amneziawg-go.git -RUN cd /go/amneziawg-tools/src && make +RUN git clone --depth=1 https://github.com/amnezia-vpn/amneziawg-tools.git \ + && git clone --depth=1 https://github.com/amnezia-vpn/amneziawg-go.git + +RUN cd /go/amneziawg-tools/src \ + && make RUN cd /go/amneziawg-go && \ go get -u ./... && \ @@ -31,21 +34,20 @@ COPY --from=bins /awg /usr/bin/awg COPY --from=bins /awg-quick /usr/bin/awg-quick # Declaring environment variables, change Peernet to an address you like, standard is a 24 bit subnet. -ARG wg_net="10.0.0.1" -ARG wg_port="51820" +ARG wg_net="10.0.0.1" \ + wg_port="51820" # Following ENV variables are changable on container runtime because /entrypoint.sh handles that. See compose.yaml for more info. -ENV TZ="Europe/Amsterdam" -ENV global_dns="1.1.1.1" -ENV isolate="none" -ENV public_ip="" -ENV wgd_port="10086" +ENV TZ="Europe/Amsterdam" \ + global_dns="9.9.9.9" \ + wgd_port="10086" \ + public_ip="" # Doing package management operations, such as upgrading RUN apk update \ && apk add --no-cache bash git tzdata \ - iptables ip6tables openrc curl wireguard-tools \ - sudo py3-psutil py3-bcrypt \ + iptables ip6tables openrc curl wireguard-tools \ + sudo py3-psutil py3-bcrypt \ && apk upgrade # Using WGDASH -- like wg_net functionally as a ARG command. But it is needed in entrypoint.sh so it needs to be exported as environment variable. @@ -87,4 +89,4 @@ COPY ./docker/entrypoint.sh /entrypoint.sh EXPOSE 10086 WORKDIR $WGDASH -ENTRYPOINT ["/bin/bash", "/entrypoint.sh"] +ENTRYPOINT ["/bin/bash", "/entrypoint.sh"] \ No newline at end of file diff --git a/docker/README.md b/docker/README.md index ee484e0..80d2297 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,39 +1,59 @@ # WGDashboard Docker Explanation: -Author: DaanSelen
+Author: @DaanSelen
This document delves into how the WGDashboard Docker container has been built.
-Of course there are two stages, one before run-time and one at/after run-time.
+Of course there are two stages (simply said), one before run-time and one at/after run-time.
The `Dockerfile` describes how the container image is made, and the `entrypoint.sh` is executed after running the container.
-In this example, WireGuard is integrated into the container itself, so it should be a run-and-go/out-of-the-box.
+In this example, WireGuard is integrated into the container itself, so it should be a run-and-go(/out-of-the-box).
For more details on the source-code specific to this Docker image, refer to the source files, they have lots of comments. -I have tried to embed some new features such as `isolate` and interface startup on container-start (through `enable`). I hope you enjoy! +
+WG-Dashboard Logo +
-WG-Dashboard Logo - -## Getting the container running: - -To get the container running you either pull the image from the repository, `donaldzou/wgdashboard:latest`.
+To get the container running you either pull the image from the repository, (docker.io)`donaldzou/wgdashboard:latest`.
From there either use the environment variables describe below as parameters or use the Docker Compose file: `compose.yaml`.
Be careful, the default generated WireGuard configuration file uses port 51820/udp. So use this port if you want to use it out of the box.
Otherwise edit the configuration file in `/etc/wireguard/wg0.conf`. -An example of a simple command to get the container running is show below:
+# WGDashboard: 🐳 Docker Deployment Guide -```shell +To run the container, you can either pull the image from Docker Hub or build it yourself. The image is available at: + +``` +docker.io/donaldzou/wgdashboard:latest +``` + +> `docker.io` is in most cases automatically resolved by the Docker application. + +### πŸ”§ Quick Docker Run Command + +Here's an example to get it up and running quickly: + +```bash docker run -d \ --name wgdashboard \ --restart unless-stopped \ - -e enable=wg0 \ - -e isolate=wg0 \ -p 10086:10086/tcp \ -p 51820:51820/udp \ --cap-add NET_ADMIN \ donaldzou/wgdashboard:latest ``` -
-If you want to use Compose instead of a raw Docker command, refer to the example in the `compose.yaml` or the one pasted below: -

+ +> ⚠️ The default WireGuard port is `51820/udp`. If you change this, update the `/etc/wireguard/wg0.conf` accordingly. + +--- + +### πŸ“¦ Docker Compose Alternative + +You can also use Docker Compose for easier configuration: ```yaml services: @@ -42,11 +62,9 @@ services: restart: unless-stopped container_name: wgdashboard environment: - #- tz= - #- global_dns= - #- enable= - #- isolate= - #- public_ip= + # - tz=Europe/Amsterdam + # - global_dns=1.1.1.1 + # - public_ip=YOUR_PUBLIC_IP ports: - 10086:10086/tcp - 51820:51820/udp @@ -59,51 +77,121 @@ services: volumes: conf: data: - ``` -If you want to customize the yaml, make sure the core stays the same, but for example volume PATHs (ON THE HOST) can be freely changed.
-This setup is just generic and will use the Docker volumes. +> πŸ“ You can customize the **volume paths** on the host to fit your needs. The example above uses Docker volumes. -## Updating the container: +--- -Updating is right now in Alpha stage. I have got it to work, testing methods. +## πŸ”„ Updating the Container -## Working with the container and environment variables: +Updating WGDashboard is currently in **alpha** stage. While the update process may work, it's still under testing. -Once the container is running, the installation process is essentially the same as running it on bare-metal.
-So go to the assign TCP port in this case HTTP, like the default 10086 one in the example and log into the WEB-GUI.
+--- -| Environment variable | Accepted arguments | Default value | Example value | Verbose | -| -------------- | ------- | ------- | ------- | ------- | -| tz | Europe/Amsterdam or any confirming timezone notation. | `Europe/Amsterdam` | `America/New_York` | Sets the timezone of the Docker container. This is to timesync the container to any other processes which would need it. | -| global_dns | Any IPv4 address, such as my personal recommendation: 9.9.9.9 (QUAD9). | `1.1.1.1` | `8.8.8.8` or any IP-Address that resolves DNS-names, and of course is reachable | Set the default DNS given to clients once they connect to the WireGuard tunnel, and for new peers, set to Cloudflare DNS for reliability. -| enable | Anything, preferably an existing WireGuard interface name. | `none` | `wg0,wg2,wg13` | Enables or disables the starting of the WireGuard interface on container 'boot-up'. -| isolate | Anything, preferably an existing WireGuard interface name. | `none` | `wg1,wg0` | The Wireguard interface itself IS able to reach the peers (Done through the `iptables` package). -| public_ip | Any IPv4 (public recommended) address, such as the one returned by default | Default uses the return of `curl ifconfig.me` | `89.20.83.118` | To reach your VPN from outside your own network, you need WG-Dashboard to know what your public IP-address is, otherwise it will generate faulty config files for clients. This happends because it is inside a Docker/Kubernetes container. In or outside of NAT is not relevant as long as the given IP-address is reachable from the internet or the target network. +## βš™οΈ Environment Variables -## Be careful with: +| Variable | Accepted Values | Default | Example | Description | +|---------------|------------------------------------------|-------------------------|------------------------|-----------------------------------------------------------------------------| +| `tz` | Timezone | `Europe/Amsterdam` | `America/New_York` | Sets the container's timezone. Useful for accurate logs and scheduling. | +| `global_dns` | IPv4 and IPv6 addresses | `9.9.9.9` | `8.8.8.8`, `1.1.1.1` | Default DNS for WireGuard clients. | +| `public_ip` | Public IP address | Retrieved automatically | `253.162.134.73` | Used to generate accurate client configs. Needed if container is NAT’d. | +| `wgd_port` | Any port that is allowed for the process | `10086` | `443` | This port is used to set the WGDashboard web port. | -When you are going to work with multiple WireGuard interfaces, you need to also open them up to the Docker host. This done by either adding the port mappings like: `51821:51821/udp` in the Docker Compose file, or to open a range like: `51820-51830:51820-51830/udp`
-The latter opens up UDP ports from 51820 to 51830, so all ports in between as well! Be careful, it is good security practise to open only needed ports! +--- -## Building the image yourself: +## πŸ” Port Forwarding Note -To build the image yourself, you need to do a couple things:
-1. Clone the Github repository containing the source code of WGDashboard including the docker directory. For example do: `git clone https://github.com/donaldzou/WGDashboard.git` -1. Navigate into the cloned repository. -1. (Make sure you have Docker correctly installed, if not: [Click here](https://docs.docker.com/engine/install/)) and run: `docker build . -t :` as an example: `docker build . -t dselen/wgdashboard:latest`.
+When using multiple WireGuard interfaces, remember to **open their respective ports** on the host. -This will make Docker compile the image from the resources in the directory you mention, in this case the source/root one. Let it compile, it takes only a couple seconds with a minute at most. +Examples: +```yaml +# Individual mapping +- 51821:51821/udp -1. If all went well, see your image with `docker images`. Example below: +# Or port range +- 51820-51830:51820-51830/udp +``` +> 🚨 **Security Tip:** Only expose ports you actually use. + +--- + +## πŸ› οΈ Building the Image Yourself + +To build from source: + +```bash +git clone https://github.com/donaldzou/WGDashboard.git +cd WGDashboard +docker build . -f docker/Dockerfile -t yourname/wgdashboard:latest +``` + +Example output: ```shell -dselen@dev-mach:~/development/WGDashboard/docker$ docker images +docker images + REPOSITORY TAG IMAGE ID CREATED SIZE -dselen/wgdashboard latest c96fd96ee3b3 42 minutes ago 314MB +yourname/wgdashboard latest c96fd96ee3b3 42 minutes ago 314MB ``` +--- + +## 🧱 Dockerfile Overview + +Here's a brief overview of the Dockerfile stages used in the image build: + +### 1. **Build Tools & Go Compilation** + +```Dockerfile +FROM golang:1.24 AS compiler +WORKDIR /go + +RUN apt-get update && apt-get install -y ... +RUN git clone ... && make +... +``` + +### 2. **Binary Copy to Scratch** + +```Dockerfile +FROM scratch AS bins +COPY --from=compiler /go/amneziawg-go/amneziawg-go /amneziawg-go +... +``` + +### 3. **Final Alpine Container Setup** + +```Dockerfile +FROM alpine:latest +COPY --from=bins ... +RUN apk update && apk add --no-cache ... +COPY ./src ${WGDASH}/src +COPY ./docker/entrypoint.sh /entrypoint.sh +... +EXPOSE 10086 +ENTRYPOINT ["/bin/bash", "/entrypoint.sh"] +``` + +--- + +## πŸš€ Entrypoint Overview + +### Major Functions: + +- **`ensure_installation`**: Sets up the app, database, and Python environment. +- **`set_envvars`**: Writes `wg-dashboard.ini` and applies environment variables. +- **`start_core`**: Starts the main WGDashboard service. +- **`ensure_blocking`**: Tails the error log to keep the container process alive. + +--- + +## βœ… Final Notes + +- Use `docker logs wgdashboard` for troubleshooting. +- Access the web interface via `http://your-ip:10086` (or whichever port you specified in the compose). +- The first time run will auto-generate WireGuard keys and configs (configs are generated from the template). + ## Closing remarks: -For feedback please submit an issue to the repository. Or message dselen@nerthus.nl. +For feedback please submit an issue to the repository. Or message dselen@nerthus.nl. \ No newline at end of file diff --git a/docker/compose.yaml b/docker/compose.yaml index 8ebef6b..6d96665 100644 --- a/docker/compose.yaml +++ b/docker/compose.yaml @@ -5,8 +5,6 @@ services: container_name: wgdashboard #environment: #- tz= # <--- Set container timezone, default: Europe/Amsterdam. - #- global_dns= # <--- Set global DNS address, default: 1.1.1.1. - #- isolate= # <--- Set the interfaces that will disallow peer communication, default: 'none'. #- public_ip= # <--- Set public IP to ensure the correct one is chosen, defaulting to the IP give by ifconfig.me. #- wgd_port= # <--- Set the port WGDashboard will use for its web-server. ports: