diff --git a/docker/Docker-explain.md b/docker/Docker-explain.md new file mode 100644 index 0000000..dd7bfe8 --- /dev/null +++ b/docker/Docker-explain.md @@ -0,0 +1,82 @@ +# WG-Dashboard Docker Explanation: + +Author: DaanSelen
+ +This document delves into how the WG-Dashboard 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.
+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 `isolated_peers` and interface startup on container-start (through `enable_wg0`). + +WG-Dashboard Logo + +## Getting the container running: + +To get the container running you either pull the image from the repository, at the moment: `repo.nerthus.nl/app/wireguard-dashboard:latest`.
+From there either use the environment variables describe below as parameters or use the Docker Compose file: `compose.yaml`. + +An example of a simple command to get the container running is show below:
+ +```shell +docker run -d \ + --name wireguard-dashboard \ + --restart unless-stopped \ + -e enable_wg0=true \ + -e isolated_peers=true \ + -p 10086:10086/tcp \ + -p 51820:51820/udp \ + --cap-add NET_ADMIN \ + repo.nerthus.nl/app/wireguard-dashboard: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: + wireguard-dashboard: + image: repo.nerthus.nl/app/wireguard-dashboard:latest + restart: unless-stopped + container_name: wire-dash + environment: + #- tz= + #- global_dns= + - enable_wg0=true + - isolated_peers=false + #- public_ip= + ports: + - 10086:10086/tcp + - 51820:51820/udp + volumes: + - conf:/etc/wireguard + - app:/opt/wireguarddashboard/app + cap_add: + - NET_ADMIN + +volumes: + conf: + app: + +``` + +If you want to customize the yaml, make sure the core stays the same, but for example volume PATHs can be freely changed.
+This setup is just generic and will use the Docker volumes. + +## 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 | Verbose | +| -------------- | ------- | ------- | ------- | +| tz | Europe/Amsterdam or any confirming timezone notation. | Europe/Amsterdam | 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 | Set the default DNS given to clients once they connect to the WireGuard tunnel (VPN). +| enable_wg0 | `true` or `false` | `false` | Enables or disables the starting of the WireGuard interface on container 'boot-up'. +| isolated_peers | `true` or `false` | `true` | For security the default is true, and it disables peers to ping or reach eachother, the WireGuard interface IS able to reach the peers (Done through `iptables`). +| public_ip | Any IPv4 (public recommended) address, such as the one returned by default | Default uses the return of `curl ifconfig.me` | 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. + +## Closing remarks: + +For feedback please submit an issue to the repository. Or message dselen@nerthus.nl. diff --git a/docker/Dockerfile b/docker/Dockerfile new file mode 100644 index 0000000..fb373d2 --- /dev/null +++ b/docker/Dockerfile @@ -0,0 +1,77 @@ +# Pull from small Debian stable image. +FROM debian:stable-slim +LABEL maintainer="dselen@nerthus.nl" + +# Declaring environment variables, change Peernet to an address you like, standard is a 24 bit subnet. +ENV wg_net="10.0.0.1" +# wg_net is used functionally as an ARG for its environment variable nature, do not change unless you know what you are doing. + +# 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 enable_wg0="false" +ENV isolated_peers="true" +ENV public_ip="0.0.0.0" + +# Doing basic system maintenance. Change the timezone to the desired timezone. +RUN ln -sf /usr/share/zoneinfo/${tz} /etc/localtime + +# Doing package management operations, such as upgrading +RUN apt-get update && apt-get upgrade -y \ + && apt-get install -y --no-install-recommends curl \ + git \ + iproute2 \ + iptables \ + iputils-ping \ + openresolv \ + procps \ + python3 \ + python3-pip \ + python3-venv \ + traceroute \ + wireguard \ + wireguard-tools \ + && apt-get remove linux-image-* --autoremove -y \ + && apt-get clean \ + && rm -rf /var/lib/apt/lists/* +# Removing the Linux Image package to preserve space on the image, for this reason also deleting apt lists, to be able to install packages: run apt update. + +# 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. +ENV WGDASH=/opt/wireguarddashboard +RUN python3 -m venv ${WGDASH}/venv + +# Doing WireGuard Dashboard installation measures. Modify the git clone command to get the preferred version, with a specific branch for example. +RUN . ${WGDASH}/venv/bin/activate \ + && git clone https://github.com/donaldzou/WGDashboard.git ${WGDASH}/app \ + && pip3 install -r ${WGDASH}/app/src/requirements.txt \ + && chmod +x ${WGDASH}/app/src/wgd.sh \ + && .${WGDASH}/app/src/wgd.sh install + +# Set the volume to be used for persistency. +VOLUME /etc/wireguard + +# Generate basic WireGuard interface. Echoing the WireGuard interface config for readability, adjust if you want it for efficiency. +# Also setting the pipefail option, verbose: https://github.com/hadolint/hadolint/wiki/DL4006. +SHELL ["/bin/bash", "-o", "pipefail", "-c"] +RUN wg genkey | tee /etc/wireguard/wg0_privatekey \ + && echo "[Interface]" > /wg0.conf \ + && echo "SaveConfig = true" >> /wg0.conf \ + && echo "Address = ${wg_net}/24" >> /wg0.conf \ + && echo "PrivateKey = $(cat /etc/wireguard/wg0_privatekey)" >> /wg0.conf \ + && echo "PostUp = iptables -t nat -I POSTROUTING 1 -s ${wg_net}/24 -o $(ip -o -4 route show to default | awk '{print $NF}') -j MASQUERADE" >> /wg0.conf \ + && echo "PostUp = iptables -I FORWARD -i wg0 -o wg0 -j DROP" >> /wg0.conf \ + && echo "PreDown = iptables -t nat -D POSTROUTING 1" >> /wg0.conf \ + && echo "PreDown = iptables -D FORWARD -i wg0 -o wg0 -j DROP" >> /wg0.conf \ + && echo "ListenPort = 51820" >> /wg0.conf \ + #&& echo "DNS = ${global_dns}" >> /wg0.conf \ + && rm /etc/wireguard/wg0_privatekey + +# Defining a way for Docker to check the health of the container. In this case: checking the login URL. +HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 CMD curl -f http://localhost:10086/signin || exit 1 + +# Copy the basic entrypoint.sh script. +COPY entrypoint.sh /entrypoint.sh + +# Exposing the default WireGuard Dashboard port for web access. +EXPOSE 10086 +ENTRYPOINT ["/bin/bash", "/entrypoint.sh"] \ No newline at end of file diff --git a/docker/compose.yaml b/docker/compose.yaml new file mode 100644 index 0000000..9d7509f --- /dev/null +++ b/docker/compose.yaml @@ -0,0 +1,23 @@ +services: + wireguard-dashboard: + image: repo.nerthus.nl/app/wireguard-dashboard:latest + restart: unless-stopped + container_name: wire-dash + environment: + #- tz= # <--- Set container timezone, default: Europe/Amsterdam. + #- global_dns= # <--- Set global DNS address, default: 1.1.1.1. + - enable_wg0=true # <--- If true, wg0 will be started on container startup. default: false. + - isolated_peers=false # <--- When set to true, it disallows peers to talk to eachother, setting to false, allows it, default: true. + #- public_ip= # <--- Set public IP to ensure the correct one is chosen, defaulting to the IP give by ifconfig.me. + ports: + - 10086:10086/tcp + - 51820:51820/udp + volumes: + - conf:/etc/wireguard + - app:/opt/wireguarddashboard/app + cap_add: + - NET_ADMIN + +volumes: + conf: + app: diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh new file mode 100644 index 0000000..118e9ef --- /dev/null +++ b/docker/entrypoint.sh @@ -0,0 +1,109 @@ +#!/bin/bash +echo "Starting the WireGuard Dashboard Docker container." + +clean_up() { + # Cleaning out previous data such as the .pid file and starting the WireGuard Dashboard. Making sure to use the python venv. + echo "Looking for remains of previous instances..." + if [ -f "/opt/wireguarddashboard/app/src/gunicorn.pid" ]; then + echo "Found old .pid file, removing." + rm /opt/wireguarddashboard/app/src/gunicorn.pid + else + echo "No remains found, continuing." + fi +} + +start_core() { + # This first step is to ensure the wg0.conf file exists, and if not, then its copied over from the ephemeral container storage. + if [ ! -f "/etc/wireguard/wg0.conf" ]; then + cp "/wg0.conf" "/etc/wireguard/wg0.conf" + echo "WireGuard interface file copied over." + else + echo "WireGuard interface file looks to already be existing." + fi + + echo "Activating Python venv and executing the WireGuard Dashboard service." + + . "${WGDASH}"/venv/bin/activate + cd "${WGDASH}"/app/src || return # If changing the directory fails (permission or presence error), then bash will exist this function, causing the WireGuard Dashboard to not be succesfully launched. + bash wgd.sh start + + # The following section takes care of the firewall rules regarding the 'isolated_peers' feature, which allows or drops packets destined from the wg0 to the wg0 interface. + if [ "${isolated_peers,,}" = "false" ]; then + echo "Isolated peers disabled, adjusting." + + sed -i '/PostUp = iptables -I FORWARD -i wg0 -o wg0 -j DROP/d' /etc/wireguard/wg0.conf + sed -i '/PreDown = iptables -D FORWARD -i wg0 -o wg0 -j DROP/d' /etc/wireguard/wg0.conf + elif [ "${isolated_peers,,}" = "true" ]; then + upblocking=$(grep -c "PostUp = iptables -I FORWARD -i wg0 -o wg0 -j DROP" /etc/wireguard/wg0.conf) + downblocking=$(grep -c "PreDown = iptables -D FORWARD -i wg0 -o wg0 -j DROP" /etc/wireguard/wg0.conf) + if [ "$upblocking" -lt 1 ] && [ "$downblocking" -lt 1 ]; then + echo "Isolated peers enabled, adjusting." + + sed -i '/PostUp = iptables -t nat -I POSTROUTING 1 -s/a PostUp = iptables -I FORWARD -i wg0 -o wg0 -j DROP' /etc/wireguard/wg0.conf + sed -i '/PreDown = iptables -t nat -D POSTROUTING 1 -s/a PreDown = iptables -D FORWARD -i wg0 -o wg0 -j DROP' /etc/wireguard/wg0.conf + fi + + fi + + # The following section takes care of + if [ "${enable_wg0,,}" = "true" ]; then + echo "Preference for wg0 to be turned on found." + + wg-quick up wg0 + else + echo "Preference for wg0 to be turned off found." + fi +} + +set_envvars() { + echo "Setting relevant variables for operation." + + # If the timezone is different, for example in North-America or Asia. + if [ "${tz}" != "$(cat /etc/timezone)" ]; then + echo "Changing timezone." + + ln -sf /usr/share/zoneinfo/"${tz}" /etc/localtime + echo "${tz}" > /etc/timezone + fi + + # Changing the DNS used for clients and the dashboard itself. + if [ "${global_dns}" != "$(grep "peer_global_dns = " /opt/wireguarddashboard/app/src/wg-dashboard.ini | awk '{print $NF}')" ]; then + echo "Changing default dns." + + #sed -i "s/^DNS = .*/DNS = ${global_dns}/" /etc/wireguard/wg0.conf # Uncomment if you want to have DNS on server-level. + sed -i "s/^peer_global_dns = .*/peer_global_dns = ${global_dns}/" /opt/wireguarddashboard/app/src/wg-dashboard.ini + fi + + # Setting the public IP of the WireGuard Dashboard container host. If not defined, it will trying fetching it using a curl to ifconfig.me. + if [ "${public_ip}" = "0.0.0.0" ]; then + default_ip=$(curl -s ifconfig.me) + echo "Trying to fetch the Public-IP using ifconfig.me: ${default_ip}" + + sed -i "s/^remote_endpoint = .*/remote_endpoint = ${default_ip}/" /opt/wireguarddashboard/app/src/wg-dashboard.ini + elif [ "${public_ip}" != "$(grep "remote_endpoint = " /opt/wireguarddashboard/app/src/wg-dashboard.ini | awk '{print $NF}')" ]; then + echo "Setting the Public-IP using given variable: ${public_ip}" + + sed -i "s/^remote_endpoint = .*/remote_endpoint = ${public_ip}/" /opt/wireguarddashboard/app/src/wg-dashboard.ini + fi +} + +ensure_blocking() { + sleep 1s + echo "Ensuring container continuation." + + # This function checks if the latest error log is created and tails it for docker logs uses. + if find "/opt/wireguarddashboard/app/src/log" -mindepth 1 -maxdepth 1 -type f | read -r; then + latestErrLog=$(find /opt/wireguarddashboard/app/src/log -name "error_*.log" | head -n 1) + latestAccLog=$(find /opt/wireguarddashboard/app/src/log -name "access_*.log" | head -n 1) + tail -f "${latestErrLog}" "${latestAccLog}" + fi + + # Blocking command in case of erroring. So the container does not quit. + sleep infinity +} + +# Execute functions for the WireGuard Dashboard services, then set the environment variables +clean_up +start_core +set_envvars +ensure_blocking \ No newline at end of file