[docs] big bang update (#348)

* [docs] big bang update * Simplified polluted README.md by moving parts to the documentation * Removed duplicates with `pymdownx.snippets` extension * Enabled code copy * Extended "Getting Started" * Added "Monitoring" page * Separated "Upgrade" page * Added default config yaml to docs Signed-off-by: Dmytro Bondar <[email protected]> * Update sources.md Co-authored-by: h44z <[email protected]> --------- Signed-off-by: Dmytro Bondar <[email protected]> Co-authored-by: h44z <[email protected]>
h44z · Jan 23, 2025 · 043d25a · 043d25a
1 parent f6c8cd5
commit 043d25a
Show file tree

Hide file tree

Showing 14 changed files with 328 additions and 323 deletions.
diff --git a/README.md b/README.md
diff --git a/docs/assets/images/dashboard.png b/docs/assets/images/dashboard.png
diff --git a/docs/documentation/configuration/examples.md b/docs/documentation/configuration/examples.md
@@ -1,14 +1,15 @@
-Below are some sample YAML configurations demonstrating how to override some default values. 
+Below are some sample YAML configurations demonstrating how to override some default values.
+
+## Basic
 
-## Basic Configuration
 ```yaml
 core:
   admin_user: [email protected]
   admin_password: password
   import_existing: false
   create_default_peer: true
   self_provisioning_allowed: true
-  
+
 web:
   site_title: My WireGuard Server
   site_company_name: My Company
@@ -31,13 +32,13 @@ database:
   dsn: data/sqlite.db
 ```
 
-## LDAP Authentication and Synchronization Configuration
+## LDAP Authentication and Synchronization
+
 ```yaml
 # ... (basic configuration)
 
 auth:
   ldap:
-
     # a sample LDAP provider with user sync enabled
     - id: ldap
       provider_name: Active Directory
@@ -63,14 +64,26 @@ auth:
       log_user_info: true
 ```
 
-## OpenID Connect (OIDC) Authentication Configuration
+## OpenID Connect (OIDC) Authentication
+
 ```yaml
 # ... (basic configuration)
 
 auth:
   oidc:
-
-    # a sample provider where users with the attribute `wg_admin` set to `true` are considered as admins   
+    # a sample Entra ID provider with environment variable substitution
+    - id: azure
+      provider_name: azure
+      display_name: Login with</br>Entra ID
+      registration_enabled: true
+      base_url: "https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0"
+      client_id: "${AZURE_CLIENT_ID}"
+      client_secret: "${AZURE_CLIENT_SECRET}"
+      extra_scopes:
+        - profile
+        - email
+
+    # a sample provider where users with the attribute `wg_admin` set to `true` are considered as admins
     - id: oidc-with-admin-attribute
       provider_name: google
       display_name: Login with</br>Google
@@ -93,7 +106,7 @@ auth:
       registration_enabled: true
       log_user_info: true
 
-    # a sample provider where users in the group `the-admin-group` are considered as admins    
+    # a sample provider where users in the group `the-admin-group` are considered as admins
     - id: oidc-with-admin-group
       provider_name: google2
       display_name: Login with</br>Google2
@@ -117,15 +130,15 @@ auth:
       log_user_info: true
 ```
 
-## Plain OAuth2 Authentication Configuration
+## Plain OAuth2 Authentication
+
 ```yaml
 # ... (basic configuration)
 
 auth:
   oauth:
-
     # a sample provider where users with the attribute `this-attribute-must-be-true` set to `true` or `True`
-    # are considered as admins    
+    # are considered as admins
     - id: google_plain_oauth-with-admin-attribute
       provider_name: google3
       display_name: Login with</br>Google3
@@ -148,7 +161,7 @@ auth:
       registration_enabled: true
 
     # a sample provider where either users with the attribute `this-attribute-must-be-true` set to `true` or 
-    # users in the group `admin-group-name` are considered as admins    
+    # users in the group `admin-group-name` are considered as admins
     - id: google_plain_oauth_with_groups
       provider_name: google4
       display_name: Login with</br>Google4
@@ -173,4 +186,4 @@ auth:
         admin_group_regex: ^admin-group-name$
       registration_enabled: true
       log_user_info: true
-```
+```
diff --git a/docs/documentation/configuration/overview.md b/docs/documentation/configuration/overview.md
@@ -1,17 +1,106 @@
-# WireGuard Portal Configuration
+This page provides an overview of **all available configuration options** for WireGuard Portal.
 
-This page provides an overview of **all available configuration options** for WireGuard Portal. 
 You can supply these configurations in a **YAML** file (e.g. `config.yaml`) when starting the Portal.
-Complete configuration examples are available in the [Configuration Examples](./examples.md) page.
-
-Below you will find sections like `core`, `advanced`, `statistics`, `mail`, `auth`, `database`, and `web`.  
+The path of the configuration file defaults to **config/config.yml** in the working directory of the executable.  
+It is possible to override configuration filepath using the environment variable `WG_PORTAL_CONFIG`.
+For example: `WG_PORTAL_CONFIG=/etc/wg-portal/config.yaml ./wg-portal`.  
+Also, environment variable substitution in config file is supported. Refer to [syntax](https://github.com/a8m/envsubst?tab=readme-ov-file#docs).
+
+Configuration examples are available on the [Examples](./examples.md) page.
+
+<details>
+<summary>Default configuration</summary>
+
+```yaml
+core:
+  admin_user: [email protected]
+  admin_password: wgportal
+  editable_keys: true
+  create_default_peer: false
+  create_default_peer_on_creation: false
+  re_enable_peer_after_user_enable: true
+  delete_peer_after_user_deleted: false
+  self_provisioning_allowed: false
+  import_existing: true
+  restore_state: true
+
+advanced:
+  log_level: info
+  log_pretty: false
+  log_json: false
+  start_listen_port: 51820
+  start_cidr_v4: 10.11.12.0/24
+  start_cidr_v6: fdfd:d3ad:c0de:1234::0/64
+  use_ip_v6: true
+  config_storage_path: ""
+  expiry_check_interval: 15m
+  rule_prio_offset: 20000
+  api_admin_only: true
+
+database:
+  debug: false
+  slow_query_threshold: 0
+  type: sqlite
+  dsn: data/sqlite.db
+
+statistics:
+  use_ping_checks: true
+  ping_check_workers: 10
+  ping_unprivileged: false
+  ping_check_interval: 1m
+  data_collection_interval: 1m
+  collect_interface_data: true
+  collect_peer_data: true
+  collect_audit_data: true
+  listening_address: :8787
+
+mail:
+  host: 127.0.0.1
+  port: 25
+  encryption: none
+  cert_validation: false
+  username: ""
+  password: ""
+  auth_type: plain
+  from: Wireguard Portal <[email protected]>
+  link_only: false
+
+auth:
+  oidc: []
+  oauth: []
+  ldap: []
+
+web:
+  listening_address: :8888
+  external_url: http://localhost:8888
+  site_company_name: WireGuard Portal
+  site_title: WireGuard Portal
+  session_identifier: wgPortalSession
+  session_secret: very_secret
+  csrf_secret: extremely_secret
+  request_logging: false
+  cert_file: ""
+  key_File: ""
+```
+
+</details>
+
+
+Below you will find sections like
+[`core`](#core),
+[`advanced`](#advanced),
+[`database`](#database),
+[`statistics`](#statistics),
+[`mail`](#mail),
+[`auth`](#auth) and
+[`web`](#web).  
 Each section describes the individual configuration keys, their default values, and a brief explanation of their purpose.
 
 ---
 
 ## Core
 
-These are the primary configuration options that control fundamental WireGuard Portal behavior. 
+These are the primary configuration options that control fundamental WireGuard Portal behavior.
 More advanced options are found in the subsequent `Advanced` section.
 
 ### `admin_user`
@@ -108,7 +197,6 @@ Additional or more specialized configuration options for logging and interface c
 - **Default:** `true`
 - **Description:** If `true`, the public REST API is accessible only to admin users. The API docs live at [`/api/v1/doc.html`](../rest-api/api-doc.md).
 
-
 ---
 
 ## Database
@@ -224,12 +312,12 @@ Options for configuring email notifications or sending peer configurations via e
 
 ## Auth
 
-WireGuard Portal supports multiple authentication strategies, including **OpenID Connect** (`oidc`), **OAuth** (`oauth`), and **LDAP** (`ldap`). 
+WireGuard Portal supports multiple authentication strategies, including **OpenID Connect** (`oidc`), **OAuth** (`oauth`), and **LDAP** (`ldap`).
 Each can have multiple providers configured. Below are the relevant keys.
 
 ---
 
-### OIDC Provider Properties
+### OIDC
 
 The `oidc` array contains a list of OpenID Connect providers. 
 Below are the properties for each OIDC provider entry inside `auth.oidc`:
@@ -264,7 +352,7 @@ Below are the properties for each OIDC provider entry inside `auth.oidc`:
   - Available fields: `user_identifier`, `email`, `firstname`, `lastname`, `phone`, `department`, `is_admin`, `user_groups`.
 
     | **Field**         | **Typical OIDC Claim**            | **Explanation**                                                                                                                                                                                         |
-    |-------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+    | ----------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `user_identifier` | `sub` or `preferred_username`     | A unique identifier for the user. Often the OIDC `sub` claim is used because it’s guaranteed to be unique for the user within the IdP. Some providers also support `preferred_username` if it’s unique. |
     | `email`           | `email`                           | The user’s email address as provided by the IdP. Not always verified, depending on IdP settings.                                                                                                        |
     | `firstname`       | `given_name`                      | The user’s first name, typically provided by the IdP in the `given_name` claim.                                                                                                                         |
@@ -290,7 +378,7 @@ Below are the properties for each OIDC provider entry inside `auth.oidc`:
 
 ---
 
-### OAuth Provider Properties
+### OAuth
 
 The `oauth` array contains a list of plain OAuth2 providers.
 Below are the properties for each OAuth provider entry inside `auth.oauth`:
@@ -333,7 +421,7 @@ Below are the properties for each OAuth provider entry inside `auth.oauth`:
   - Available fields: `user_identifier`, `email`, `firstname`, `lastname`, `phone`, `department`, `is_admin`, `user_groups`.
 
     | **Field**         | **Typical Claim**                 | **Explanation**                                                                                                                                                                                         |
-    |-------------------|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+    | ----------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `user_identifier` | `sub` or `preferred_username`     | A unique identifier for the user. Often the OIDC `sub` claim is used because it’s guaranteed to be unique for the user within the IdP. Some providers also support `preferred_username` if it’s unique. |
     | `email`           | `email`                           | The user’s email address as provided by the IdP. Not always verified, depending on IdP settings.                                                                                                        |
     | `firstname`       | `given_name`                      | The user’s first name, typically provided by the IdP in the `given_name` claim.                                                                                                                         |
@@ -359,7 +447,7 @@ Below are the properties for each OAuth provider entry inside `auth.oauth`:
 
 ---
 
-### LDAP Provider Properties
+### LDAP
 
 The `ldap` array contains a list of LDAP authentication providers.
 Below are the properties for each LDAP provider entry inside `auth.ldap`:
@@ -402,7 +490,7 @@ Below are the properties for each LDAP provider entry inside `auth.ldap`:
     - Available fields: `user_identifier`, `email`, `firstname`, `lastname`, `phone`, `department`, `memberof`.
 
       | **WireGuard Portal Field** | **Typical LDAP Attribute** | **Short Description**                                        |
-      |----------------------------|----------------------------|--------------------------------------------------------------|
+      | -------------------------- | -------------------------- | ------------------------------------------------------------ |
       | user_identifier            | sAMAccountName / uid       | Uniquely identifies the user within the LDAP directory.      |
       | email                      | mail / userPrincipalName   | Stores the user's primary email address.                     |
       | firstname                  | givenName                  | Contains the user's first (given) name.                      |
@@ -455,3 +543,47 @@ Below are the properties for each LDAP provider entry inside `auth.ldap`:
 #### `log_user_info`
 - **Default:** *(empty)*
 - **Description:** If `true`, logs LDAP user data at the trace level upon login.
+
+---
+
+## Web
+
+### `listening_address`
+- **Default:** `:8888`
+- **Description:** The listening port of the web server.
+
+### `external_url`
+- **Default:** `http://localhost:8888`
+- **Description:** The URL where a client can access WireGuard Portal.
+
+### `site_company_name`
+- **Default:** `WireGuard Portal`
+- **Description:** The company name that is shown at the bottom of the web frontend.
+
+### `site_title`
+- **Default:** `WireGuard Portal`
+- **Description:** The title that is shown in the web frontend.
+
+### `session_identifier`
+- **Default:** `wgPortalSession`
+- **Description:** The session identifier for the web frontend.
+
+### `session_secret`
+- **Default:** `very_secret`
+- **Description:** The session secret for the web frontend.
+
+### `csrf_secret`
+- **Default:** `extremely_secret`
+- **Description:** The CSRF secret.
+
+### `request_logging`
+- **Default:** `false`
+- **Description:** Log all HTTP requests.
+
+### `cert_file`
+- **Default:** *(empty)*
+- **Description:** (Optional) Path to the TLS certificate file.
+
+### `key_file`
+- **Default:** *(empty)*
+- **Description:** (Optional) Path to the TLS certificate key file.
diff --git a/docs/documentation/getting-started/binaries.md b/docs/documentation/getting-started/binaries.md
@@ -0,0 +1,34 @@
+Starting from v2, each [release](https://github.com/h44z/wg-portal/releases) includes compiled binaries for supported platforms.
+These binary versions can be manually downloaded and installed.
+
+## Download
+
+With `curl`:
+
+  ```shell
+  curl -L -o wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64 
+  ```
+
+With `wget`:
+
+  ```shell
+  wget -O wg-portal https://github.com/h44z/wg-portal/releases/download/${WG_PORTAL_VERSION}/wg-portal_linux_amd64
+  ```
+
+with `gh cli`:
+
+  ```shell
+  gh release download ${WG_PORTAL_VERSION} --repo h44z/wg-portal --output wg-portal --pattern '*amd64'
+  ```
+
+## Install
+
+```shell
+sudo mkdir -p /opt/wg-portal
+sudo install wg-portal /opt/wg-portal/
+```
+
+## Unreleased
+
+Unreleased versions could be downloaded from
+[GitHub Workflow](https://github.com/h44z/wg-portal/actions/workflows/docker-publish.yml?query=branch%3Amaster) artifacs also.
diff --git a/docs/documentation/getting-started/building.md b/docs/documentation/getting-started/building.md