Merge pull request #906 from WGDashboard/docker-doc-refac

refac(docs): rewrite and check the docker documents

docker/Dockerfile

@@ -3,8 +3,10 @@
 # Base: Alpine
 #
 
+# Pull the current golang-alpine image.
 FROM golang:1.25-alpine AS awg-go
 
+# Install build-dependencies.
 RUN apk add --no-cache \
     git \
     gcc \
@@ -14,9 +16,12 @@ RUN apk add --no-cache \
 RUN mkdir -p /workspace && \
     git clone https://github.com/WGDashboard/amneziawg-go /workspace/awg
 
+# Enable CGO compilation for AmneziaWG
 ENV CGO_ENABLED=1
 
+# Change directory
 WORKDIR /workspace/awg
+# Compile the binaries
 RUN go mod download && \
     go mod verify && \
     go build -ldflags '-linkmode external -extldflags "-fno-PIC -static"' -v -o /usr/bin
@@ -26,6 +31,7 @@ RUN go mod download && \
 #
 FROM alpine:latest AS awg-tools
 
+# Install needed dependencies.
 RUN apk add --no-cache \
     make \
     git \
@@ -33,19 +39,24 @@ RUN apk add --no-cache \
     linux-headers \
     ca-certificates
 
+# Get the workspace ready
 RUN mkdir -p /workspace && \
     git clone https://github.com/WGDashboard/amneziawg-tools /workspace/awg-tools
 
-WORKDIR /workspace/awg-tools/src
+# Change directory
+WORKDIR /workspaceawg-tools/src
+# Compile and change permissions
 RUN make && chmod +x wg*
 
 #
 # PIP DEPENDENCY BUILDING
 # Base: Alpine
 #
+
+# Use the python-alpine image for building pip dependencies
 FROM python:3.13-alpine AS pip-builder
 
-
+# Add the build dependencies and create a Python virtual environment.
 RUN apk add --no-cache \
       build-base \
       pkgconfig \
@@ -57,7 +68,9 @@ RUN apk add --no-cache \
     && mkdir -p /opt/wgdashboard/src \
     && python3 -m venv /opt/wgdashboard/src/venv
 
+# Copy the requirements file into the build layer.
 COPY ./src/requirements.txt /opt/wgdashboard/src
+# Install the pip packages
 RUN . /opt/wgdashboard/src/venv/bin/activate && \
     pip3 install --upgrade pip && \
     pip3 install -r /opt/wgdashboard/src/requirements.txt
@@ -66,6 +79,8 @@ RUN . /opt/wgdashboard/src/venv/bin/activate && \
 # WGDashboard RUNNING STAGE
 # Base: Alpine
 #
+
+# Running with the python-alpine image.
 FROM python:3.13-alpine AS final
 LABEL maintainer="dselen@nerthus.nl"
 
@@ -78,7 +93,7 @@ RUN apk add --no-cache \
     tzdata wireguard-tools \
     openresolv openrc
 
-# Copy only the final binaries from the builders
+# Copy only the final binaries from the AWG builder stages
 COPY --from=awg-go /usr/bin/amneziawg-go /usr/bin/amneziawg-go
 COPY --from=awg-tools /workspace/awg-tools/src/wg /usr/bin/awg
 COPY --from=awg-tools /workspace/awg-tools/src/wg-quick/linux.bash /usr/bin/awg-quick
@@ -92,14 +107,14 @@ ENV TZ="Europe/Amsterdam" \
     public_ip="" \
     WGDASH=/opt/wgdashboard
 
-# Create directories
+# Create directories needed for operation
 RUN mkdir /data /configs -p ${WGDASH}/src /etc/amnezia/amneziawg
 
-# Copy app source and prebuilt venv only (no pip cache)
+# Copy the python virtual environment from the pip-builder stage
 COPY ./src ${WGDASH}/src
 COPY --from=pip-builder /opt/wgdashboard/src/venv /opt/wgdashboard/src/venv
 
-# WireGuard interface template
+# First WireGuard interface template
 SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 RUN out_adapt=$(ip -o -4 route show to default | awk '{print $NF}') \
   && echo -e "[Interface]\n\
@@ -114,11 +129,14 @@ SaveConfig = true\n\
 DNS = ${global_dns}" > /configs/wg0.conf.template \
   && chmod 600 /configs/wg0.conf.template
 
+# Set a healthcheck to determine the container its health
 HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
   CMD sh -c 'pgrep gunicorn > /dev/null && pgrep tail > /dev/null' || exit 1
 
+# Copy in the runtime script, essential.
 COPY ./docker/entrypoint.sh /entrypoint.sh
 
+#
 EXPOSE 10086
 WORKDIR $WGDASH/src
 

docker/README.md

@@ -3,8 +3,8 @@ Author: @DaanSelen<br>
 
 This document delves into how the WGDashboard Docker container has been built.<br>
 Of course there are two stages (simply said), one before run-time and one at/after run-time.<br>
-The `Dockerfile` describes how the container image is made, and the `entrypoint.sh` is executed after running the container. <br>
+The `Dockerfile` describes how the container image is made, and the `entrypoint.sh` is executed after the container is started. <br>
-In this example, WireGuard is integrated into the container itself, so it should be a run-and-go(/out-of-the-box).<br>
+In this example, [WireGuard](https://www.wireguard.com/) is integrated into the container itself, so it should be a run-and-go(/out-of-the-box) experience.<br>
 For more details on the source-code specific to this Docker image, refer to the source files, they have lots of comments.
 
 <br>
@@ -18,20 +18,24 @@ For more details on the source-code specific to this Docker image, refer to the
 />
 <br>
 
-To get the container running you either pull the image from the repository, (docker.io)`donaldzou/wgdashboard:latest`.<br>
+To get the container running you either pull the pre-made image from a remote repository, there are 2 official options.<br>
-From there either use the environment variables describe below as parameters or use the Docker Compose file: `compose.yaml`.<br>
+
-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.<br>
+- ghcr.io/wgdashboard/wgdashboard:<tag>
-Otherwise edit the configuration file in `/etc/wireguard/wg0.conf`.
+- docker.io/donaldzou/wgdashboard:<tag>
+
+> tags should be either: latest, main, <version> or <commit-sha>.
+
+From there either use the environment variables described below as parameters or use the Docker Compose file: `compose.yaml`.<br>
+Be careful, the default generated WireGuard configuration file uses port 51820/udp. So make sure to use this port if you want to use it out of the box.<br>
+Otherwise edit the configuration file in WGDashboard under `Configuration Settings` -> `Edit Raw Configuration File`.
+
+> Otherwise you need to enter the container and edit: `/etc/wireguard/wg0.conf`.
 
 # WGDashboard: 🐳 Docker Deployment Guide
 
-To run the container, you can either pull the image from Docker Hub or build it yourself. The image is available at:
+To run the container, you can either pull the image from the Github Container Registry (ghcr.io), Docker Hub (docker.io) or build it yourself. The image is available at:
 
-```
+> `docker.io` is in most cases automatically resolved by the Docker application. Therefor you can ofter specify: `donaldzou/wgdashboard:latest`
-docker.io/donaldzou/wgdashboard:latest
-```
-
-> `docker.io` is in most cases automatically resolved by the Docker application.
 
 ### 🔧 Quick Docker Run Command
 
@@ -44,7 +48,7 @@ docker run -d \
   -p 10086:10086/tcp \
   -p 51820:51820/udp \
   --cap-add NET_ADMIN \
-  donaldzou/wgdashboard:latest
+  ghcr.io/wgdashboard/wgdashboard:latest
 ```
 
 > ⚠️ The default WireGuard port is `51820/udp`. If you change this, update the `/etc/wireguard/wg0.conf` accordingly.
@@ -58,23 +62,24 @@ You can also use Docker Compose for easier configuration:
 ```yaml
 services:
   wgdashboard:
-    image: donaldzou/wgdashboard:latest
+    image: ghcr.io/wgdashboard/wgdashboard:latest
     restart: unless-stopped
     container_name: wgdashboard
-    environment:
+
-      # - tz=Europe/Amsterdam
-      # - global_dns=1.1.1.1
-      # - public_ip=YOUR_PUBLIC_IP
     ports:
       - 10086:10086/tcp
       - 51820:51820/udp
+
     volumes:
+      - aconf:/etc/amnezia/amneziawg
       - conf:/etc/wireguard
       - data:/data
+
     cap_add:
       - NET_ADMIN
 
 volumes:
+  aconf:
   conf:
   data:
 ```
@@ -85,7 +90,7 @@ volumes:
 
 ## 🔄 Updating the Container
 
-Updating WGDashboard is currently in **alpha** stage. While the update process may work, it's still under testing.
+Updating the WGDashboard container should be through 'The Docker Way' - by pulling the newest/newer image and replacing this old one.
 
 ---
 
@@ -205,4 +210,4 @@ ENTRYPOINT ["/bin/bash", "/entrypoint.sh"]
 
 ## 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.

docker/compose.yaml

@@ -1,5 +1,5 @@
 services:
-  wireguard-dashboard:
+  wgdashboard:
     # Since the github organisation we recommend the ghcr.io.
     # Alternatively we also still push to docker.io under donaldzou/wgdashboard.
     # Both share the exact same tags. So they should be interchangable.