diff --git a/webpage/docs/getting-started/configuration/authentication.md b/webpage/docs/getting-started/configuration/authentication.md index 43d95c00..bc6b45aa 100644 --- a/webpage/docs/getting-started/configuration/authentication.md +++ b/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 diff --git a/webpage/docs/getting-started/configuration/capture.md b/webpage/docs/getting-started/configuration/capture.md index 4edb54db..ec1fefa4 100644 --- a/webpage/docs/getting-started/configuration/capture.md +++ b/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'; diff --git a/webpage/docs/getting-started/configuration/desktop.md b/webpage/docs/getting-started/configuration/desktop.md index 017109aa..cf80889c 100644 --- a/webpage/docs/getting-started/configuration/desktop.md +++ b/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 diff --git a/webpage/docs/getting-started/configuration/index.md b/webpage/docs/getting-started/configuration/index.md index 421fa48f..c5e4c238 100644 --- a/webpage/docs/getting-started/configuration/index.md +++ b/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. -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. +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. -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 + +
+ Example merging order + +```bash +# Default Value: 127.0.0.1:8080 + +# Config File +cat config.yaml < + +## 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. + + +
+ Example configuration files + + + + + ```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 ] + ``` + + + + + + ```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" ] + } + ] + } + } + } + ``` + + + + + ```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" ] + ``` + + + + + + ```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" ] + } + } + } + ``` + + + + + + ```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"]}]" + ``` + + + + + + ```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 + ``` + + + + + +
+ +## 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: + 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' + +## Next Steps + +import DocCardList from '@theme/DocCardList'; + + diff --git a/webpage/docs/getting-started/configuration/webrtc.md b/webpage/docs/getting-started/configuration/webrtc.md index 33d302de..6de3b8cd 100644 --- a/webpage/docs/getting-started/configuration/webrtc.md +++ b/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