Improve documentation on password hash (#1901)

* Improve documentation on password hash

* Change branch name

* Add single quote docker run info

* Tag versions, docker run version

* separate docker run and compose

---------

Co-authored-by: Bernd Storath <32197462+kaaax0815@users.noreply.github.com>

.github/CODEOWNERS

@@ -1,4 +1,5 @@
 # Copyright (c) Emile Nijssen (WeeJeWel)
 # Founder and Codeowner of WireGuard Easy (wg-easy)
-# Maintained by Philip Heiduck (pheiduck)
-* @pheiduck
+# Maintained by Bernd Storath (kaaax0815)
+* @WeeJeWel
+* @kaaax0815

.github/workflows/codeql.yml

@@ -1,41 +0,0 @@
-name: "CodeQL"
-
-on:
-  push:
-    branches: [ "master" ]
-  pull_request:
-    branches: [ "master" ]
-  schedule:
-    - cron: "15 0 * * *"
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'wg-easy'
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [ 'javascript-typescript' ]
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v3
-      with:
-        languages: ${{ matrix.language }}
-
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v3
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
-      with:
-        category: "/language:${{matrix.language}}"

.github/workflows/deploy-development.yml

@@ -1,37 +0,0 @@
-name: Build & Publish Development
-
-on:
-  workflow_dispatch:
-
-jobs:
-  deploy:
-    name: Build & Deploy
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'wg-easy'
-    permissions:
-      packages: write
-      contents: read
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        ref: production
-
-    - name: Set up QEMU
-      uses: docker/setup-qemu-action@v3
-
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v3
-
-    - name: Login to GitHub Container Registry
-      uses: docker/login-action@v3
-      with:
-        registry: ghcr.io
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Build & Publish Docker Image
-      uses: docker/build-push-action@v6
-      with:
-        push: true
-        platforms: linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64/v8
-        tags: ghcr.io/wg-easy/wg-easy:development

.github/workflows/deploy-nightly.yml

@@ -1,39 +0,0 @@
-name: Build & Publish Nightly
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: "0 0 * * *"
-
-jobs:
-  deploy:
-    name: Build & Deploy
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'wg-easy'
-    permissions:
-      packages: write
-      contents: read
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        ref: production
-
-    - name: Set up QEMU
-      uses: docker/setup-qemu-action@v3
-
-    - name: Set up Docker Buildx
-      uses: docker/setup-buildx-action@v3
-
-    - name: Login to GitHub Container Registry
-      uses: docker/login-action@v3
-      with:
-        registry: ghcr.io
-        username: ${{ github.actor }}
-        password: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Build & Publish Docker Image
-      uses: docker/build-push-action@v6
-      with:
-        push: true
-        platforms: linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64/v8
-        tags: ghcr.io/wg-easy/wg-easy:nightly

.github/workflows/deploy-pr.yml

@@ -1,7 +1,6 @@
 name: Build Pull Request
 
 on:
-  workflow_dispatch:
   pull_request:
 
 jobs:
@@ -14,8 +13,6 @@ jobs:
       contents: read
     steps:
     - uses: actions/checkout@v4
-      with:
-        ref: production
 
     - name: Set up QEMU
       uses: docker/setup-qemu-action@v3

.github/workflows/deploy.yml

@@ -1,23 +1,24 @@
 name: Build & Publish Latest
 
 on:
-  workflow_dispatch:
   push:
     branches:
-      - production
+      - v14
 
 jobs:
   deploy:
     name: Build & Deploy
     runs-on: ubuntu-latest
-    if: github.repository_owner == 'wg-easy'
+    if: |
+      github.repository_owner == 'wg-easy' &&
+      !contains(github.event.head_commit.message, '!skipci')
     permissions:
       packages: write
       contents: read
     steps:
     - uses: actions/checkout@v4
       with:
-        ref: production
+        ref: v14
 
     - name: Set up QEMU
       uses: docker/setup-qemu-action@v3
@@ -32,12 +33,9 @@ jobs:
         username: ${{ github.actor }}
         password: ${{ secrets.GITHUB_TOKEN }}
 
-    - name: Set environment variables
-      run: echo RELEASE=$(cat ./src/package.json | jq -r .release | jq -r .version) >> $GITHUB_ENV
-
     - name: Build & Publish Docker Image
       uses: docker/build-push-action@v6
       with:
         push: true
         platforms: linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64/v8
-        tags: ghcr.io/wg-easy/wg-easy:latest, ghcr.io/wg-easy/wg-easy:${{ env.RELEASE }}
+        tags: ghcr.io/wg-easy/wg-easy:latest, ghcr.io/wg-easy/wg-easy:14

.github/workflows/lint.yml

@@ -3,8 +3,7 @@ name: Lint
 on:
   push:
     branches:
-      - master
-      - production
+      - v14
   pull_request:
 
 jobs:

.github/workflows/npm-update-bot.yml

@@ -1,40 +0,0 @@
-name: NPM Update Bot 🤖
-
-on:
-  push:
-    branches: [ "master" ]
-  schedule:
-    - cron: "0 0 * * 1"
-
-jobs:
-  npmupbot:
-    name: NPM Update Bot 🤖
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'wg-easy'
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          repository: wg-easy/wg-easy
-          ref: master
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          check-latest: true
-          cache: 'npm'
-
-      - name: Bot 🤖 "Updating NPM Packages..."
-        run: |
-          npm install -g --silent npm-check-updates
-          ncu -u
-          npm update
-          cd src
-          ncu -u
-          npm update
-          npm run buildcss
-          git config --global user.name 'NPM Update Bot'
-          git config --global user.email 'npmupbot@users.noreply.github.com'
-          git add .
-          git commit -am "npm: package updates" || true
-          git push

.github/workflows/stale.yml

@@ -1,35 +0,0 @@
-# This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time.
-#
-# You can adjust the behavior by modifying this file.
-# For more information, see:
-# https://github.com/actions/stale
-name: Mark stale issues and pull requests
-
-on:
-  workflow_dispatch:
-  schedule:
-  - cron: '*/5 * * * *'
-
-jobs:
-  stale:
-
-    runs-on: ubuntu-latest
-    if: github.repository_owner == 'wg-easy'
-    permissions:
-      issues: write
-      pull-requests: write
-
-    steps:
-    - uses: actions/stale@v9
-      with:
-          days-before-issue-stale: 30
-          days-before-issue-close: 14
-          stale-issue-label: "stale"
-          stale-issue-message: "This issue is stale because it has been open for 30 days with no activity."
-          close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale."
-          days-before-pr-stale: 30
-          days-before-pr-close: 14
-          stale-pr-message: "This PR is stale because it has been open for 30 days with no activity."
-          close-pr-message: "This PR was closed because it has been inactive for 14 days since being marked as stale."
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-          operations-per-run: 100

Dockerfile

@@ -1,6 +1,6 @@
 # As a workaround we have to build on nodejs 18
 # nodejs 20 hangs on build with armv6/armv7
-FROM docker.io/library/node:18-alpine AS build_node_modules
+FROM docker.io/library/node:lts-alpine AS build_node_modules
 
 # Update npm to latest
 RUN npm install -g npm@latest
@@ -13,7 +13,7 @@ RUN npm ci --omit=dev &&\
 
 # Copy build result to a new image.
 # This saves a lot of disk space.
-FROM docker.io/library/node:20-alpine
+FROM docker.io/library/node:lts-alpine
 HEALTHCHECK CMD /usr/bin/timeout 5s /bin/sh -c "/usr/bin/wg show | /bin/grep -q interface || exit 1" --interval=1m --timeout=5s --retries=3
 COPY --from=build_node_modules /app /app
 
@@ -39,7 +39,7 @@ RUN apk add --no-cache \
     wireguard-tools
 
 # Use iptables-legacy
-RUN update-alternatives --install /sbin/iptables iptables /sbin/iptables-legacy 10 --slave /sbin/iptables-restore iptables-restore /sbin/iptables-legacy-restore --slave /sbin/iptables-save iptables-save /sbin/iptables-legacy-save
+RUN update-alternatives --install /usr/sbin/iptables iptables /usr/sbin/iptables-legacy 10 --slave /usr/sbin/iptables-restore iptables-restore /usr/sbin/iptables-legacy-restore --slave /usr/sbin/iptables-save iptables-save /usr/sbin/iptables-legacy-save
 
 # Set Environment
 ENV DEBUG=Server,WireGuard

How_to_generate_an_bcrypt_hash.md

@@ -1,28 +1,45 @@
-# wg-password
+# Generating bcrypt-hashed password
 
-`wg-password` (wgpw) is a script that generates bcrypt password hashes for use with `wg-easy`, enhancing security by requiring passwords.
+With version 14 of wg-easy, a password hashed with bcrypt is needed instead of the plain-text password string. This doc explains how to generate the hash based on a plain-text password.
 
-## Features
+## Using Docker + node
 
-- Generate bcrypt password hashes.
-- Easily integrate with `wg-easy` to enforce password requirements.
+- You are using docker compose
 
-## Usage with Docker
+    The easiest way to generate a bcrypt password hash with wgpw is using docker and node:
 
-To generate a bcrypt password hash using docker, run the following command :
+    ```sh
+    docker run ghcr.io/wg-easy/wg-easy:14 node -e 'const bcrypt = require("bcryptjs"); const hash = bcrypt.hashSync("YOUR_PASSWORD", 10); console.log(hash.replace(/\$/g, "$$$$"));'
+    ```
+
+    The hashed password will get printed on your terminal. Copy it and use on the `PASSWORD_HASH` environment variable in your docker compose.
+
+- You are using `docker run`
+
+    If you are using `docker run` for running wg-easy, you must enclose the hash string in single quotes (`'...'`). You can use this command:
+
+    ```sh
+    docker run --rm ghcr.io/wg-easy/wg-easy:14 node -e "const bcrypt = require('bcryptjs'); const hash = bcrypt.hashSync('YOUR_PASSWORD', 10); console.log('\'' + hash + '\'');"
+    ```
+
+    The hashed password will get printed on your terminal. Copy it and use on the `PASSWORD_HASH` environment variable in your docker run command.
+
+## Using Docker + wgpw
+
+`wg-password` (wgpw) is a script that generates bcrypt password hashes. You can use it with docker:
 
 ```sh
-docker run ghcr.io/wg-easy/wg-easy wgpw YOUR_PASSWORD
-PASSWORD_HASH='$2b$12$coPqCsPtcFO.Ab99xylBNOW4.Iu7OOA2/ZIboHN6/oyxca3MWo7fW' // literally YOUR_PASSWORD
+docker run ghcr.io/wg-easy/wg-easy:14 wgpw YOUR_PASSWORD
 ```
 
-*Important* : make sure to enclose your password in single quotes when you run `docker run` command :
+You will see an output similar to this:
 
-```bash
-$ echo $2b$12$coPqCsPtcF
-b2
-$ echo "$2b$12$coPqCsPtcF"
-b2
-$ echo '$2b$12$coPqCsPtcF'
-$2b$12$coPqCsPtcF
+```sh
+PASSWORD_HASH='$2b$12$coPqCsPtcFO.Ab99xylBNOW4.Iu7OOA2/ZIboHN6/oyxca3MWo7fW'
+```
+
+In this example, the `$2b$12$coPqCsPtcFO.Ab99xylBNOW4.Iu7OOA2/ZIboHN6/oyxca3MWo7fW` string is your hashed password. For using it with docker-compose, you need to escape each `$` characters by adding another `$` before them, or they will get interpreted as variables. The final password you can use in docker-compose will look like this:
+
+```sh
+$$2b$$12$$coPqCsPtcFO.Ab99xylBNOW4.Iu7OOA2/ZIboHN6/oyxca3MWo7fW
 ```

README.md

@@ -32,15 +32,8 @@ You have found the easiest way to install & manage WireGuard on any Linux host!
 
 ## Versions
 
-We provide more then 1 docker image to get, this will help you decide which one is best for you. <br>
-For **stable** versions instead of nightly or development please read **README** from the **production** branch!
-
-| tag | Branch | Example | Description |
-| - | - | - | - |
-| `latest` | production | `ghcr.io/wg-easy/wg-easy:latest` or `ghcr.io/wg-easy/wg-easy` | stable as possbile get bug fixes quickly when needed, deployed against `production`. |
-| `13` | production | `ghcr.io/wg-easy/wg-easy:13` | same as latest, stick to a version tag. |
-| `nightly` | master | `ghcr.io/wg-easy/wg-easy:nightly` | mostly unstable gets frequent package and code updates, deployed against `master`. |
-| `development` | pull requests | `ghcr.io/wg-easy/wg-easy:development` | used for development, testing code from PRs before landing into `master`. |
+This branch is only for the v14 release of WireGuard Easy.
+For newer versions, please refer to the [master branch](https://github.com/wg-easy/wg-easy/tree/master).
 
 ## Installation
 
@@ -76,7 +69,7 @@ To automatically install & run wg-easy, simply run:
   --sysctl="net.ipv4.conf.all.src_valid_mark=1" \
   --sysctl="net.ipv4.ip_forward=1" \
   --restart unless-stopped \
-  ghcr.io/wg-easy/wg-easy
+  ghcr.io/wg-easy/wg-easy:14
 ```
 
 > 💡 Replace `YOUR_SERVER_IP` with your WAN IP, or a Dynamic DNS hostname.
@@ -130,7 +123,7 @@ To update to the latest version, simply run:
 ```bash
 docker stop wg-easy
 docker rm wg-easy
-docker pull ghcr.io/wg-easy/wg-easy
+docker pull ghcr.io/wg-easy/wg-easy:14
 ```
 
 And then run the `docker run -d \ ...` command above again.
@@ -140,12 +133,5 @@ With Docker Compose WireGuard Easy can be updated with a single command:
 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 WireGuared Easy container will be automatically recreated if a newer image
+The WireGuard Easy container will be automatically recreated if a newer image
 was pulled.
-
-## 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).

docker-compose.dev.yml

@@ -13,5 +13,5 @@ services:
       - NET_ADMIN
       - SYS_MODULE
     environment:
-      # - PASSWORD=p
+      # - PASSWORD_HASH=p
       - WG_HOST=192.168.1.233

docker-compose.yml

@@ -12,7 +12,7 @@ services:
       - WG_HOST=raspberrypi.local
 
       # Optional:
-      # - PASSWORD_HASH=$$2y$$10$$hBCoykrB95WSzuV4fafBzOHWKu9sbyVa34GJr8VV5R/pIelfEMYyG (needs double $$, hash of 'foobar123'; see "How_to_generate_an_bcrypt_hash.md" for generate the hash)
+      # - PASSWORD_HASH=$$2y$$10$$hBCoykrB95WSzuV4fafBzOHWKu9sbyVa34GJr8VV5R/pIelfEMYyG # (needs double $$, hash of 'foobar123'; see "How_to_generate_an_bcrypt_hash.md" for generate the hash)
       # - PORT=51821
       # - WG_PORT=51820
       # - WG_CONFIG_PORT=92820
@@ -28,7 +28,7 @@ services:
       # - UI_TRAFFIC_STATS=true
       # - UI_CHART_TYPE=0 # (0 Charts disabled, 1 # Line chart, 2 # Area chart, 3 # Bar chart)
 
-    image: ghcr.io/wg-easy/wg-easy
+    image: ghcr.io/wg-easy/wg-easy:14
     container_name: wg-easy
     volumes:
       - etc_wireguard:/etc/wireguard

src/config.js

@@ -5,6 +5,8 @@ const { release: { version } } = require('./package.json');
 module.exports.RELEASE = version;
 module.exports.PORT = process.env.PORT || '51821';
 module.exports.WEBUI_HOST = process.env.WEBUI_HOST || '0.0.0.0';
+/** This is only kept for migration purpose. DO NOT USE! */
+module.exports.PASSWORD = process.env.PASSWORD;
 module.exports.PASSWORD_HASH = process.env.PASSWORD_HASH;
 module.exports.WG_PATH = process.env.WG_PATH || '/etc/wireguard/';
 module.exports.WG_DEVICE = process.env.WG_DEVICE || 'eth0';

src/lib/Server.js

@@ -28,6 +28,7 @@ const {
   PORT,
   WEBUI_HOST,
   RELEASE,
+  PASSWORD,
   PASSWORD_HASH,
   LANG,
   UI_TRAFFIC_STATS,
@@ -306,6 +307,10 @@ module.exports = class Server {
       }),
     );
 
+    if (PASSWORD) {
+      throw new Error('DO NOT USE PASSWORD ENVIRONMENT VARIABLE. USE PASSWORD_HASH INSTEAD.\nSee https://github.com/wg-easy/wg-easy/blob/v14/How_to_generate_an_bcrypt_hash.md');
+    }
+
     createServer(toNodeListener(app)).listen(PORT, WEBUI_HOST);
     debug(`Listening on http://${WEBUI_HOST}:${PORT}`);
   }