From d66d6ed3fd4b87ce658cd2395208693600a569f3 Mon Sep 17 00:00:00 2001
From: Christoph Haas <christoph.h@sprinternet.at>
Date: Mon, 5 Jan 2026 23:18:24 +0100
Subject: [PATCH] docs: enhance binary usage guide and systemd setup (#577)

---
 .../documentation/getting-started/binaries.md | 67 ++++++++++++++++++-
 scripts/wg-portal.service                     |  2 +
 2 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/docs/documentation/getting-started/binaries.md b/docs/documentation/getting-started/binaries.md
index 5aed082..54eda62 100644
--- a/docs/documentation/getting-started/binaries.md
+++ b/docs/documentation/getting-started/binaries.md
@@ -9,6 +9,11 @@ Make sure that you download the correct binary for your architecture. The availa
 - `wg-portal_linux_arm64` - Linux ARM 64-bit
 - `wg-portal_linux_arm_v7` - Linux ARM 32-bit
 
+### Released versions
+
+To download a specific version, replace `${WG_PORTAL_VERSION}` with the desired version (or set an environment variable). 
+All official release versions can be found on the [GitHub Releases Page](https://github.com/h44z/wg-portal/releases).
+
 With `curl`:
 
 ```shell
@@ -27,16 +32,74 @@ with `gh cli`:
 gh release download ${WG_PORTAL_VERSION} --repo h44z/wg-portal --output wg-portal --pattern '*amd64'
 ```
 
+The downloaded file will be named `wg-portal` and can be moved to a directory of your choice, see [Install](#install) for more information.
+
+### Unreleased versions (master branch builds)
+
+Unreleased versions can be fetched directly from the artifacts section of the [GitHub Workflow](https://github.com/h44z/wg-portal/actions/workflows/docker-publish.yml?query=branch%3Amaster).
 
 
 ## Install
 
+The following command can be used to install the downloaded binary (`wg-portal`) to `/opt/wg-portal/wg-portal`. It ensures that the binary is executable.
+
 ```shell
 sudo mkdir -p /opt/wg-portal
 sudo install wg-portal /opt/wg-portal/
 ```
 
-## Unreleased versions (master branch builds)
+To handle tasks such as restarting the service or configuring automatic startup, it is recommended to use a process manager like [systemd](https://systemd.io/). 
+Refer to [Systemd Service Setup](#systemd-service-setup) for instructions.
 
-Unreleased versions can be fetched directly from the artifacts section of the [GitHub Workflow](https://github.com/h44z/wg-portal/actions/workflows/docker-publish.yml?query=branch%3Amaster).
+## Systemd Service Setup
 
+> **Note:** To run WireGuard Portal as systemd service, you need to download the binary for your architecture beforehand.
+> 
+> The following examples assume that you downloaded the binary to `/opt/wg-portal/wg-portal`. 
+> The configuration file is expected to be located at `/opt/wg-portal/config.yml`.
+
+To run WireGuard Portal as a systemd service, you can create a service unit file. The easiest way to do this is by using `systemctl edit`:
+
+```shell
+sudo systemctl edit --force --full wg-portal.service
+```
+
+Paste the following content into the editor and adjust the variables to your needs:
+
+```ini
+[Unit]
+Description=WireGuard Portal
+ConditionPathExists=/opt/wg-portal/wg-portal
+After=network.target
+
+[Service]
+Type=simple
+User=root
+Group=root
+AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW
+
+Restart=on-failure
+RestartSec=10
+
+WorkingDirectory=/opt/wg-portal
+Environment=WG_PORTAL_CONFIG=/opt/wg-portal/config.yml
+ExecStart=/opt/wg-portal/wg-portal
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Alternatively, you can create or modify the file manually in `/etc/systemd/system/wg-portal.service`. 
+For systemd to pick up the changes, you need to reload the daemon:
+
+```shell
+sudo systemctl daemon-reload
+```
+
+After creating the service file, you can enable and start the service:
+
+```shell
+sudo systemctl enable --now wg-portal.service
+```
+
+To check status and log output, use: `sudo systemctl status wg-portal.service` or `sudo journalctl -u wg-portal.service`.
diff --git a/scripts/wg-portal.service b/scripts/wg-portal.service
index 0007fa4..a9801e4 100644
--- a/scripts/wg-portal.service
+++ b/scripts/wg-portal.service
@@ -7,11 +7,13 @@ After=network.target
 Type=simple
 User=root
 Group=root
+AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW
 
 Restart=on-failure
 RestartSec=10
 
 WorkingDirectory=/opt/wg-portal
+Environment=WG_PORTAL_CONFIG=/opt/wg-portal/config.yml
 ExecStart=/opt/wg-portal/wg-portal-amd64
 
 [Install]