diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000..19953c4 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,107 @@ +# WGDashboard Docker Explanation: +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.
+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.
+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 + +## Getting the container running: + +To get the container running you either pull the image from the repository, `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:
+ +```shell +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: +

+ +```yaml +services: + wgdashboard: + image: donaldzou/wgdashboard:latest + restart: unless-stopped + container_name: wgdashboard + environment: + #- tz= + #- global_dns= + #- enable= + #- isolate= + #- public_ip= + ports: + - 10086:10086/tcp + - 51820:51820/udp + volumes: + - conf:/etc/wireguard + - data:/data + cap_add: + - NET_ADMIN + +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. + +## Updating the container: + +Updating is right now in Alpha stage. I have got it to work, testing methods. + +## Working with the container and environment variables: + +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. + +## Be careful with: + +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: + +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`.
+ 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. +1. If all went well, see your image with `docker images`. Example below: + +```shell +dselen@dev-mach:~/development/WGDashboard/docker$ docker images +REPOSITORY TAG IMAGE ID CREATED SIZE +dselen/wgdashboard latest c96fd96ee3b3 42 minutes ago 314MB +``` + +## Closing remarks: + +For feedback please submit an issue to the repository. Or message dselen@nerthus.nl. diff --git a/docker/alpine/builder.sh b/docker/alpine/builder.sh deleted file mode 100644 index 5511413..0000000 --- a/docker/alpine/builder.sh +++ /dev/null @@ -1,43 +0,0 @@ -venv_python="./venv/bin/python3" -venv_gunicorn="./venv/bin/gunicorn" -pythonExecutable="python3" - - -_check_and_set_venv(){ - VIRTUAL_ENV="./venv" - if [ ! -d $VIRTUAL_ENV ]; then - printf "[WGDashboard] Creating Python Virtual Environment under ./venv\n" - { $pythonExecutable -m venv $VIRTUAL_ENV; } >> ./log/install.txt - fi - - if ! $venv_python --version > /dev/null 2>&1 - then - printf "[WGDashboard] %s Python Virtual Environment under ./venv failed to create. Halting now.\n" "$heavy_crossmark" - kill $TOP_PID - fi - - source ${VIRTUAL_ENV}/bin/activate - -} - -build_core () { - if [ ! -d "log" ] - then - printf "[WGDashboard] Creating ./log folder\n" - mkdir "log" - fi - - - apk add --no-cache python3 net-tools python3-dev py3-virtualenv - _check_and_set_venv - printf "[WGDashboard] Upgrading Python Package Manage (PIP)\n" - { date; python3 -m pip install --upgrade pip; printf "\n\n"; } >> ./log/install.txt - printf "[WGDashboard] Building Bcrypt & Psutil\n" - { date; python3 -m pip install -r requirements.txt ; printf "\n\n"; } >> ./log/install.txt - printf "[WGDashboard] Build Successfull!\n" - printf "[WGDashboard] Clean Up Pip!\n" - { date; rm -rf /opt/wireguarddashboard/src/venv/lib/python3.12/site-packages/pip* ; printf "\n\n"; } >> ./log/install.txt - -} - -build_core diff --git a/docker/alpine/requirements.txt b/docker/alpine/requirements.txt deleted file mode 100644 index 074ed2f..0000000 --- a/docker/alpine/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -bcrypt -psutil