expand configuration index.

webpage/docs/getting-started/configuration/authentication.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 1
+description: Configuration related to the Authentication and Sessions in Neko.
 ---
 
 # Authentication

webpage/docs/getting-started/configuration/capture.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 2
+description: Configuration related to Gstreamer capture in Neko.
 ---
 
 import Tabs from '@theme/Tabs';

webpage/docs/getting-started/configuration/desktop.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 3
+description: Configuration related to the Desktop Environment in Neko.
 ---
 
 # Desktop Environment

webpage/docs/getting-started/configuration/index.md

@@ -1,16 +1,383 @@
 ---
 sidebar_position: 5
+title: Configuration
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Configuration
 
-Configuration options can be set using Environment Variables, as an argument to the CLI, or in a configuration file.
+Neko uses the [Viper](https://github.com/spf13/viper) library to manage configuration. The configuration file is optional and is not required for Neko to run. If a configuration file is present, it will be read in and merged with the default configuration values.
-We use the [Viper](https://github.com/spf13/viper) library to manage configuration. Viper supports JSON, TOML, YAML, HCL, and Java properties files.
-The configuration file is optional and is not required for Neko to run.
-If a configuration file is present, it will be read in and merged with the default configuration values.
 
-Highest priority is given to the Environment Variables, followed by CLI arguments, and then the configuration file.
+The merge order is as follows:
+
+- Default configuration values
+- Configuration file
+- Environment variables
+- Command-line arguments
+
+<details>
+  <summary>Example merging order</summary>
+
+```bash
+# Default Value: 127.0.0.1:8080
+
+# Config File
+cat config.yaml <<EOF
+server:
+  bind: "127.0.0.1:8081"
+EOF
+
+# Environment Variable
+export NEKO_SERVER_BIND=127.0.0.1:8082
+
+# Command-line Argument
+./neko -config=config.yaml -server.bind=127.0.0.1:8083
+```
+
+The final value of `server.bind` will be `127.0.0.1:8083`.
+
+</details>
+
+## Configuration File
+
+You have multiple ways to specify the configuration file for the neko server:
+
+- Command-line argument: `-config=/path/to/config.yaml`
+- Environment variable: `NEKO_CONFIG=/path/to/config.yaml`
+- Place the `neko.yaml` file in the same directory as the neko binary.
+- Place the `neko.yaml` file to `/etc/neko/neko.yaml` *(ideal for Docker containers)*.
+
+The configuration file can be specified in YAML, JSON, TOML, HCL, envfile, and Java properties format. Throughout the documentation, we will use the YAML format.
+
+
+<details>
+  <summary>Example configuration files</summary>
+
+<Tabs>
+  <TabItem value="yaml" label="YAML">
+
+    ```yaml title="config.yaml"
+    capture:
+      screencast:
+        enabled: false
+
+    server:
+      pprof: true
+
+    desktop:
+      screen: "1920x1080@60"
+
+    member:
+      provider: "multiuser"
+      multiuser:
+      admin_password: "admin"
+      user_password: "neko"
+
+    session:
+      merciful_reconnect: true
+      implicit_hosting: false
+      inactive_cursors: true
+      cookie:
+        enabled: false
+
+    webrtc:
+      icelite: true
+      iceservers:
+        # Backend servers are ignored if icelite is true.
+        backend:
+          - urls: [ stun:stun.l.google.com:19302 ]
+        frontend:
+          - urls: [ stun:stun.l.google.com:19305 ]
+    ```
+  
+  </TabItem>
+
+  <TabItem value="json" label="JSON">
+
+    ```json title="config.json"
+    {
+      "capture": {
+        "screencast": {
+          "enabled": false
+        }
+      },
+      "server": {
+        "pprof": true
+      },
+      "desktop": {
+        "screen": "1920x1080@60"
+      },
+      "member": {
+        "provider": "multiuser",
+        "multiuser": {
+          "admin_password": "admin",
+          "user_password": "neko"
+        }
+      },
+      "session": {
+        "merciful_reconnect": true,
+        "implicit_hosting": false,
+        "inactive_cursors": true,
+        "cookie": {
+          "enabled": false
+        }
+      },
+      "webrtc": {
+        "icelite": true,
+        "iceservers": {
+          "backend": [
+            {
+              "urls": [ "stun:stun.l.google.com:19302" ]
+            }
+          ],
+          "frontend": [
+            {
+              "urls": [ "stun:stun.l.google.com:19305" ]
+            }
+          ]
+        }
+      }
+    }
+    ```
+
+  </TabItem>
+  <TabItem value="toml" label="TOML">
+
+    ```toml title="config.toml"
+    [capture.screencast]
+    enabled = false
+
+    [server]
+    pprof = true
+
+    [desktop]
+    screen = "1920x1080@60"
+
+    [member]
+    provider = "multiuser"
+
+    [member.multiuser]
+    admin_password = "admin"
+    user_password = "neko"
+
+    [session]
+    merciful_reconnect = true
+    implicit_hosting = false
+    inactive_cursors = true
+
+    [session.cookie]
+    enabled = false
+
+    [webrtc]
+    icelite = true
+
+    [[webrtc.iceservers.backend]]
+    urls = [ "stun:stun.l.google.com:19302" ]
+
+    [[webrtc.iceservers.frontend]]
+    urls = [ "stun:stun.l.google.com:19305" ]
+    ```
+
+  </TabItem>
+
+  <TabItem value="hcl" label="HCL">
+
+    ```hcl title="config.hcl"
+    capture {
+      screencast {
+        enabled = false
+      }
+    }
+
+    server {
+      pprof = true
+    }
+
+    desktop {
+      screen = "1920x1080@60"
+    }
+
+    member {
+      provider = "multiuser"
+
+      multiuser {
+        admin_password = "admin"
+        user_password = "neko"
+      }
+    }
+
+    session {
+      merciful_reconnect = true
+      implicit_hosting = false
+      inactive_cursors = true
+
+      cookie {
+        enabled = false
+      }
+    }
+
+    webrtc {
+      icelite = true
+
+      iceservers {
+        backend {
+          urls = [ "stun:stun.l.google.com:19302" ]
+        }
+
+        frontend {
+          urls = [ "stun:stun.l.google.com:19305" ]
+        }
+      }
+    }
+    ```
+
+  </TabItem>
+
+  <TabItem value="envfile" label="Envfile">
+
+    ```env title=".env"
+    CAPTURE_SCREENCAST_ENABLED=false
+
+    SERVER_PPROF=true
+
+    DESKTOP_SCREEN=1920x1080@60
+
+    MEMBER_PROVIDER=multiuser
+    MEMBER_MULTIUSER_ADMIN_PASSWORD=admin
+    MEMBER_MULTIUSER_USER_PASSWORD=neko
+
+    SESSION_MERCIFUL_RECONNECT=true
+    SESSION_IMPLICIT_HOSTING=false
+    SESSION_INACTIVE_CURSORS=true
+    SESSION_COOKIE_ENABLED=false
+
+    WEBRTC_ICELITE=true
+
+    WEBRTC_ICESERVERS_BACKEND="[{"urls":["stun:stun.l.google.com:19302"]}]"
+    WEBRTC_ICESERVERS_FRONTEND="[{"urls":["stun:stun.l.google.com:19305"]}]"
+    ```
+
+  </TabItem>
+
+  <TabItem value="properties" label="Java Properties">
+
+    ```properties title="config.properties"
+    capture.screencast.enabled = false
+
+    server.pprof = true
+
+    desktop.screen = 1920x1080@60
+
+    member.provider = multiuser
+    member.multiuser.admin_password = admin
+    member.multiuser.user_password = neko
+
+    session.merciful_reconnect = true
+    session.implicit_hosting = false
+    session.inactive_cursors = true
+    session.cookie.enabled = false
+
+    webrtc.icelite = true
+
+    webrtc.iceservers.backend[0].urls[0] = stun:stun.l.google.com:19302
+    webrtc.iceservers.frontend[0].urls[0] = stun:stun.l.google.com:19305
+    ```
+
+  </TabItem>
+
+</Tabs>
+
+</details>
+
+## Room Configuration
+
+This is the initial configuration of the room that can be modified by an admin in real-time.
+
+```yaml title="config.yaml"
+session:
+  private_mode: false
+  locked_logins: false
+  locked_controls: false
+  control_protection: false
+  implicit_hosting: true
+  inactive_cursors: false
+  merciful_reconnect: true
+  heartbeat_interval: 120
+```
+
+- `private_mode` whether private mode is enabled, users do not receive the room video or audio.
+- `locked_logins` whether logins are locked for users, admins can still login.
+- `locked_controls` whether controls are locked for users, admins can still control.
+- `control_protection` users can gain control only if at least one admin is in the room.
+- `implicit_hosting` allows switching control implicitly without the need for explicit control request before
+- `inactive_cursors` whether to show inactive cursors server-wide (only for users that have it enabled in their profile)
+- `merciful_reconnect` whether to allow reconnecting to the websocket even if the previous connection was not closed. This means that a new login can kick out the previous one.
+- `heartbeat_interval` interval in seconds for sending a heartbeat message to the server. This is used to keep the connection alive and to detect when the connection is lost.
+
+## Server Configuration
+
+This is the configuration of the neko server.
+
+```yaml title="config.yaml"
+server:
+  bind: "127.0.0.1:8080"
+  cert: "/path/to/cert.pem"
+  key: "/path/to/key.pem"
+  cors: [ "*" ]
+  metrics: true
+  path_prefix: "/neko"
+  pprof: true
+  proxy: true
+  static: "/var/www/neko"
+```
+
+- `bind` address/port/socket to serve neko. For docker you might want to bind to `0.0.0.0` to allow connections from outside the container.
+- `cert` and `key` paths to the SSL cert and key used to secure the neko server. If both are empty, the server will run in plain HTTP.
+- `cors` is a list of allowed origins for CORS.
+  - If empty, CORS is disabled, and only same-origin requests are allowed.
+  - If `*` is present, all origins are allowed. Neko will respond always with the requested origin, not with `*` since [credentials are not allowed with wildcard](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSNotSupportingCredentials).
+  - If a list of origins is present, only those origins are allowed for CORS.
+- `metrics` when true, [prometheus](https://prometheus.io/docs/prometheus/latest/getting_started/) metrics are available at `/metrics`.
+- `path_prefix` is the prefix for all HTTP requests. This is useful when running neko behind a reverse proxy and you want to serve neko under a subpath, e.g. `/neko`.
+- `pprof` when true, the [pprof](https://golang.org/pkg/net/http/pprof/) endpoint is available at `/debug/pprof` for debugging and profiling. This should be disabled in production.
+- `proxy` when true, neko will trust the `X-Forwarded-For` and `X-Real-IP` headers from the reverse proxy. Make sure your reverse proxy is configured to set these headers and never trust them when not behind a reverse proxy.
+- `static` path to the directory containing the neko client files to serve. This is useful if you want to serve the client files on the same domain as the server.
+
+## Logging Configuration
+
+This is the configuration of the logging system.
+
+```yaml title="config.yaml"
+log:
+  dir: <string>
+  json: true
+  level: "info"
+  nocolor: true
+  time: "unix"
+```
+
+- `dir` directory to store logs. If empty, logs are written to stdout. This is useful when running neko in a container.
+- `json` when true, logs are written in JSON format.
+- `level` log level to set. Available levels are `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`, and `disabled`.
+- `nocolor` when true, ANSI colors are disabled in non-JSON output. Accepts as well [`NO_COLOR` environment variable](https://no-color.org/).
+- `time` time format used in logs. Available formats are `unix`, `unixms`, and `unixmicro`.
+
+:::tip
+Shortcut environment variable to enable DEBUG mode: `NEKO_DEBUG=true`
+:::
+
+## Full Configuration Reference
+
+Here is a full configuration with default values as shown in the help command. Please refer to the sub-sections for more details.
 
 import Configuration from './help.tsx'
 
 <Configuration />
+
+## Next Steps
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />

webpage/docs/getting-started/configuration/webrtc.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 4
+description: Configuration related to the WebRTC and Networking in Neko.
 ---
 
 # WebRTC Configuration