diff --git a/webpage/docusaurus.config.ts b/webpage/docusaurus.config.ts index 9e69b7e6..5bb25ecd 100644 --- a/webpage/docusaurus.config.ts +++ b/webpage/docusaurus.config.ts @@ -34,6 +34,13 @@ const config: Config = { docs: { sidebarPath: './sidebars.ts', editUrl: 'https://github.com/m1k1o/neko/tree/main/docs/', + lastVersion: 'current', + versions: { + current: { + label: 'v3', + path: 'v3', + }, + }, }, //blog: { // showReadingTime: true, @@ -84,6 +91,20 @@ const config: Config = { label: 'Changelog', position: 'left', }, + { + href: 'https://github.com/sponsors/m1k1o', + label: 'Donate', + position: 'left', + }, + { + type: 'docsVersionDropdown', + position: 'right', + }, + { + href: 'https://discord.gg/3U6hWpC', + label: 'Discord', + position: 'right', + }, { href: 'https://github.com/m1k1o/neko', label: 'GitHub', diff --git a/webpage/src/pages/index.tsx b/webpage/src/pages/index.tsx index 94e1b8d0..1e2d171c 100644 --- a/webpage/src/pages/index.tsx +++ b/webpage/src/pages/index.tsx @@ -1,3 +1,19 @@ +// This is handler for old links that were used in v2. +// They were used only as hash links, so we need to redirect them to the new links. +if (typeof window !== 'undefined' && window.location.hash) { + let hash = window.location.hash.substring(1); + hash = hash.replace('?id=', '#'); + if (/^[a-z0-9\-#\/]+$/.test(hash)) { + // if id starts with known path + if (hash.startsWith('/getting-started')) { + // remove /getting-started + hash = hash.replace('/getting-started', ''); + // add /docs/v2 + window.location.href = '/docs/v2' + hash; + } + } +} + import type {ReactNode} from 'react'; import clsx from 'clsx'; import Link from '@docusaurus/Link'; diff --git a/webpage/static/v2/brave.svg b/webpage/static/v2/brave.svg new file mode 100644 index 00000000..80d23c4b --- /dev/null +++ b/webpage/static/v2/brave.svg @@ -0,0 +1,4 @@ + + + + diff --git a/webpage/static/v2/chromium.svg b/webpage/static/v2/chromium.svg new file mode 100644 index 00000000..7f27f9a8 --- /dev/null +++ b/webpage/static/v2/chromium.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/webpage/static/v2/firefox.svg b/webpage/static/v2/firefox.svg new file mode 100644 index 00000000..13862742 --- /dev/null +++ b/webpage/static/v2/firefox.svg @@ -0,0 +1,111 @@ + + + +Firefox Browser logo + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/webpage/static/v2/google-chrome.svg b/webpage/static/v2/google-chrome.svg new file mode 100644 index 00000000..6f20e808 --- /dev/null +++ b/webpage/static/v2/google-chrome.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/webpage/static/v2/kde.svg b/webpage/static/v2/kde.svg new file mode 100644 index 00000000..5de2486d --- /dev/null +++ b/webpage/static/v2/kde.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/webpage/static/v2/microsoft-edge.svg b/webpage/static/v2/microsoft-edge.svg new file mode 100644 index 00000000..2fa37cef --- /dev/null +++ b/webpage/static/v2/microsoft-edge.svg @@ -0,0 +1,44 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/webpage/static/v2/opera.svg b/webpage/static/v2/opera.svg new file mode 100644 index 00000000..01e2b01b --- /dev/null +++ b/webpage/static/v2/opera.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/webpage/static/v2/remmina.png b/webpage/static/v2/remmina.png new file mode 100644 index 00000000..bf910688 Binary files /dev/null and b/webpage/static/v2/remmina.png differ diff --git a/webpage/static/v2/tor-browser.svg b/webpage/static/v2/tor-browser.svg new file mode 100644 index 00000000..f0ceb85e --- /dev/null +++ b/webpage/static/v2/tor-browser.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/webpage/static/v2/udp-ports-nc.png b/webpage/static/v2/udp-ports-nc.png new file mode 100644 index 00000000..c910b7c1 Binary files /dev/null and b/webpage/static/v2/udp-ports-nc.png differ diff --git a/webpage/static/v2/vivaldi.svg b/webpage/static/v2/vivaldi.svg new file mode 100644 index 00000000..cd38f150 --- /dev/null +++ b/webpage/static/v2/vivaldi.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/webpage/static/v2/vlc.svg b/webpage/static/v2/vlc.svg new file mode 100644 index 00000000..09385930 --- /dev/null +++ b/webpage/static/v2/vlc.svg @@ -0,0 +1,107 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/webpage/static/v2/xfce.svg b/webpage/static/v2/xfce.svg new file mode 100644 index 00000000..10d087af --- /dev/null +++ b/webpage/static/v2/xfce.svg @@ -0,0 +1,95 @@ + + + XFCE 4 Logo + + + + image/svg+xml + + XFCE 4 Logo + + + Savvas Radevic + + + http://www.xfce.org/about/artwork + + XFCE logo +* Based on xfce_logo.svg from http://www.xfce.org/about/artwork +* Optimized colours +* Added "X" and "XFCE" text. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/webpage/versioned_docs/version-v2/README.md b/webpage/versioned_docs/version-v2/README.md new file mode 100644 index 00000000..f0789d0b --- /dev/null +++ b/webpage/versioned_docs/version-v2/README.md @@ -0,0 +1,369 @@ +--- +sidebar_position: 2 +title: Getting started +--- + +# Getting started & FAQ + +
+ + + + + + + + + + + + +
+ +Use the following docker images from [Docker Hub](https://hub.docker.com/r/m1k1o/neko) for x86_64: +- `m1k1o/neko:latest` or `m1k1o/neko:firefox` - for Firefox. +- `m1k1o/neko:chromium` - for Chromium (needs `--cap-add=SYS_ADMIN`, see the [security implications](https://www.redhat.com/en/blog/container-tidbits-adding-capabilities-container)). +- `m1k1o/neko:google-chrome` - for Google Chrome (needs `--cap-add=SYS_ADMIN`, see the [security implications](https://www.redhat.com/en/blog/container-tidbits-adding-capabilities-container)). +- `m1k1o/neko:ungoogled-chromium` - for [Ungoogled Chromium](https://github.com/Eloston/ungoogled-chromium) (needs `--cap-add=SYS_ADMIN`, see the [security implications](https://www.redhat.com/en/blog/container-tidbits-adding-capabilities-container)) (by @whalehub). +- `m1k1o/neko:microsoft-edge` - for Microsoft Edge (needs `--cap-add=SYS_ADMIN`, see the [security implications](https://www.redhat.com/en/blog/container-tidbits-adding-capabilities-container)). +- `m1k1o/neko:brave` - for [Brave Browser](https://brave.com) (needs `--cap-add=SYS_ADMIN`, see the [security implications](https://www.redhat.com/en/blog/container-tidbits-adding-capabilities-container)). +- `m1k1o/neko:vivaldi` - for [Vivaldi Browser](https://vivaldi.com) (needs `--cap-add=SYS_ADMIN`, see the [security implications](https://www.redhat.com/en/blog/container-tidbits-adding-capabilities-container)) (by @Xeddius). +- `m1k1o/neko:opera` for [Opera Browser](https://opera.com) (requires extra steps to enable DRM, see instructions [here](https://www.reddit.com/r/operabrowser/wiki/opera/linux_widevine_config/). libffmpeg is already configured.) (by @prophetofxenu) +- `m1k1o/neko:tor-browser` - for Tor Browser. +- `m1k1o/neko:remmina` - for remote desktop connection (by @lowne). + - Pass env var `REMMINA_URL=://[[:]@]server[:port]` (proto being `vnc`, `rdp` or `spice`). + - Or create your custom configuration with remmina locally (it's saved in `~/.local/share/remmina/path_to_profile.remmina`) and bind-mount it, then pass env var `REMMINA_PROFILE=`. +- `m1k1o/neko:vlc` - for VLC Video player (needs volume mounted to `/media` with local video files, or setting `VLC_MEDIA=/media` path). +- `m1k1o/neko:xfce` or `m1k1o/neko:kde` - for a shared desktop / installing shared software. +- `m1k1o/neko:base` - for custom base. + +Dockerhub images are built using GitHub actions on every push and on weekly basis to keep all browsers up-to-date. + +All images are also available on [GitHub Container Registry](https://github.com/m1k1o?tab=packages&repo_name=neko) for faster pulls: + +- `ghcr.io/m1k1o/neko/firefox:latest` +- `ghcr.io/m1k1o/neko/chromium:latest` +- `ghcr.io/m1k1o/neko/google-chrome:latest` +- `ghcr.io/m1k1o/neko/ungoogled-chromium:latest` +- `ghcr.io/m1k1o/neko/microsoft-edge:latest` +- `ghcr.io/m1k1o/neko/brave:latest` +- `ghcr.io/m1k1o/neko/vivaldi:latest` +- `ghcr.io/m1k1o/neko/opera:latest` +- `ghcr.io/m1k1o/neko/tor-browser:latest` +- `ghcr.io/m1k1o/neko/remmina:latest` +- `ghcr.io/m1k1o/neko/vlc:latest` +- `ghcr.io/m1k1o/neko/xfce:latest` +- `ghcr.io/m1k1o/neko/kde:latest` + +For ARM-based images (like Raspberry Pi - with GPU hardware acceleration, Oracle Cloud ARM tier). Currently, not all images are available for ARM, because not all applications are available for ARM. + +:::danger IMPORTANT +`m1k1o/neko:arm-*` images from dockerhub are currently not maintained and they can contain outdated software. +::: + +Please use images below: + +- `ghcr.io/m1k1o/neko/arm-firefox:latest` +- `ghcr.io/m1k1o/neko/arm-chromium:latest` +- `ghcr.io/m1k1o/neko/arm-ungoogled-chromium:latest` +- `ghcr.io/m1k1o/neko/arm-vlc:latest` +- `ghcr.io/m1k1o/neko/arm-xfce:latest` + +For images with VAAPI GPU hardware acceleration using intel drivers use: + +- `ghcr.io/m1k1o/neko/intel-firefox:latest` +- `ghcr.io/m1k1o/neko/intel-chromium:latest` +- `ghcr.io/m1k1o/neko/intel-google-chrome:latest` +- `ghcr.io/m1k1o/neko/intel-ungoogled-chromium:latest` +- `ghcr.io/m1k1o/neko/intel-microsoft-edge:latest` +- `ghcr.io/m1k1o/neko/intel-brave:latest` +- `ghcr.io/m1k1o/neko/intel-vivaldi:latest` +- `ghcr.io/m1k1o/neko/intel-opera:latest` +- `ghcr.io/m1k1o/neko/intel-tor-browser:latest` +- `ghcr.io/m1k1o/neko/intel-remmina:latest` +- `ghcr.io/m1k1o/neko/intel-vlc:latest` +- `ghcr.io/m1k1o/neko/intel-xfce:latest` +- `ghcr.io/m1k1o/neko/intel-kde:latest` + +For images with Nvidia GPU hardware acceleration using EGL (see example below) use (please note, there is a known issue with EGL and Chromium-based browsers, see [here](https://github.com/m1k1o/neko/issues/279)): + +- `ghcr.io/m1k1o/neko/nvidia-firefox:latest` +- `ghcr.io/m1k1o/neko/nvidia-chromium:latest` +- `ghcr.io/m1k1o/neko/nvidia-google-chrome:latest` +- `ghcr.io/m1k1o/neko/nvidia-microsoft-edge:latest` +- `ghcr.io/m1k1o/neko/nvidia-brave:latest` + +GHCR images are built using GitHub actions for every tag. + +:::tip +For more applications, check out [m1k1o/neko-apps](https://github.com/m1k1o/neko-apps). +::: + +### Networking: +- If you want to use n.eko in **external** network, you can omit `NEKO_NAT1TO1`. It will automatically get your Public IP. +- If you want to use n.eko in **internal** network, set `NEKO_NAT1TO1` to your local IP address (e.g. `NEKO_NAT1TO1: 192.168.1.20`)- + +Currently, it is not supported to supply multiple NAT addresses directly to neko (see https://github.com/m1k1o/neko/issues/47). + +But it can be acheived by deploying own turn server alongside neko that is accessible from your LAN: + +```yaml +version: "3.4" + +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_SCREEN: 1920x1080@30 + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + # highlight-start + NEKO_ICESERVERS: | + [{ + "urls": [ "turn::3478" ], + "username": "neko", + "credential": "neko" + },{ + "urls": [ "stun:stun.nextcloud.com:3478" ] + }] + # highlight-end + coturn: + image: 'coturn/coturn:latest' + network_mode: "host" + command: | + -n + --realm=localhost + --fingerprint + --listening-ip=0.0.0.0 + --external-ip= + --listening-port=3478 + --min-port=49160 + --max-port=49200 + --log-file=stdout + --user=neko:neko + --lt-cred-mech +``` + +- Replace `` with your LAN IP address, and allow ports `49160-49200/udp` and `3478/tcp` in your LAN. +- Make sure you don't use `NEKO_ICELITE: true` because ICE LITE does not support TURN servers. + +This setup adds local turn server to neko. It won't be reachable by your remote clients and your own IP won't be reachable from your lan. So it effectively just adds local candidate and allows connections from LAN. + +### Why so many ports? +- WebRTC needs UDP ports in order to transfer Audio/Video towards user and Mouse/Keyboard events to the server in real time. +- If you don't set `NEKO_ICELITE=true`, every user will need 2 UDP ports. +- If you set `NEKO_ICELITE=true`, every user will need only 1 UDP port. It is **recommended** to use *ice-lite*. +- Do not forget, they are **UDP** ports, that configuration must be correct in your firewall/router/docker. +- You can freely limit number of UDP ports. But you can't map them to different ports. + - This **WON'T** work: `32000-32100:52000-52100/udp` +- You can change API port (8080). + - This **WILL** work: `3000:8080` + +### Using mux instead of epr + +When using a mux, not so many ports are needed. + +```yaml +version: "3.4" +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + # highlight-start + - "8081:8081/tcp" + - "8082:8082/udp" + # highlight-end + environment: + NEKO_SCREEN: 1920x1080@30 + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + # highlight-start + NEKO_TCPMUX: 8081 + NEKO_UDPMUX: 8082 + # highlight-end + NEKO_ICELITE: 1 +``` + + +- When using mux, `NEKO_EPR` is ignored. +- Mux accepts only one port, not a range. +- You only need to expose maximum two ports for WebRTC on your router/firewall and have many users connected. +- It can even be the same port number, so e.g. `NEKO_TCPMUX: 8081` and `NEKO_UDPMUX: 8081`. +- The same port must be exposed from docker container, you can't map them to different ports. So `8082:8082` is OK, but `"5454:8082` will not work. +- You can use them alone (either TCP or UDP) when needed. + - UDP is generally better for latency. But some networks block UDP so it is good to have TCP available as fallback. +- Still, using `NEKO_ICELITE=true` is recommended. + +### Using turn servers instead of port forwarding + +- If you don't want to use port forwarding, you can use turn servers. +- But you need to have your own turn server (e.g. [cotrun](https://github.com/coturn/coturn)) or have access to one. +- They are generally not free, because they require a lot of bandwidth. +- Please make sure that you correctly escape your turn server credentials in the environment variable or use aphostrophes. + +```yaml +NEKO_ICESERVERS: '[{"urls": ["turn::443?transport=udp", "turn::443?transport=tcp", "turns::443?transport=udp", "turns::443?transport=tcp"], "credential": "` will prefill password. + - Adding `?usr=` will prefill username. + - Adding `?cast=1` will hide all control and show only video. + - Adding `?embed=1` will hide most additional components and show only video. + - Adding `?volume=<0-1>` will set volume to given value. + - Adding `?lang=` will set language to given value. + - Adding `?show_side=1` will show the sidebar on startup. + - Adding `?mute_chat=1` will mute the chat on startup. + - e.g. `http(s):///?pwd=neko&usr=guest&cast=1` + +### Screen size +- Only admins can change screen size. +- You can set a default screen size, but this size **MUST** be one from the list, that your server supports. +- You will get this list in frontend, where you can choose from. + +### Clipboard sharing +- Browsers have certain requirements to allow clipboard sharing. + - Your instance must be HTTPS. + - Firefox does not support clipboard sharing. + - Use Chrome for the best experience. +- If your browser does not support clipboard sharing: + - Clipboard icon in the bottom right corner will be displayed for host. + - It opens text area that can share clipboard content bi-directionally. + - Only plain-text is supported. diff --git a/webpage/versioned_docs/version-v2/configuration.md b/webpage/versioned_docs/version-v2/configuration.md new file mode 100644 index 00000000..07470ae9 --- /dev/null +++ b/webpage/versioned_docs/version-v2/configuration.md @@ -0,0 +1,247 @@ +--- +sidebar_position: 5 +--- + +# Configuration + +Config values can be set using three methods, sorted on this page by priority. + +Example, setting `nat1to1` variable: +- As env variable: `NEKO_NAT1TO1=` +- As argument: `--nat1to1=` +- In YAML config file: +```yaml +nat1to1: +``` + +## Environment variables + +#### `NEKO_SCREEN`: + - Resolution after startup. Only Admins can change this later. + - e.g. `1920x1080@30` +#### `NEKO_PASSWORD`: + - Password for the user login. + - e.g. `user_password` +#### `NEKO_PASSWORD_ADMIN`: + - Password for the admin login. + - e.g. `admin_password` +#### `NEKO_CONTROL_PROTECTION`: + - Control protection means, users can gain control only if at least one admin is in the room. + - e.g. `false` +#### `NEKO_IMPLICIT_CONTROL`: + - If enabled members can gain control implicitly, they don't need to request control. + - e.g. `false` +#### `NEKO_LOCKS`: + - Resources, that will be locked when starting, separated by whitespace. + - Currently supported: + - `control` + - `login` + - `file_transfer` + - e.g. `control` + +### WebRTC + +#### `NEKO_EPR`: + - For WebRTC needed range of UDP ports. + - e.g. `52000-52099` +#### `NEKO_UDPMUX`: + - Alternative to epr with only one UDP port. + - e.g. `52100` +#### `NEKO_TCPMUX`: + - Use TCP connection, meant as fallback for UDP. + - e.g. `52100` +#### `NEKO_NAT1TO1`: + - IP of the server that will be sent to client, if not specified, public IP is automatically resolved. + - e.g. `10.0.0.1` +#### `NEKO_IPFETCH`: + - Automatically fetch IP address from given URL when `nat1to1` is not specified. + - e.g. `http://checkip.amazonaws.com` +#### `NEKO_ICELITE`: + - Use the ice lite protocol. + - e.g. `false` +#### `NEKO_ICESERVER`: + - Describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer (simple usage for server without authentication). + - e.g. `stun:stun.l.google.com:19302` +#### `NEKO_ICESERVERS`: + - Describes multiple STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer. + - e.g. `[{"urls": ["turn:turn.example.com:19302", "stun:stun.example.com:19302"], "username": "name", "credential": "password"}, {"urls": ["stun:stun.example2.com:19302"]}]` + - [More information](https://developer.mozilla.org/en-US/docs/Web/API/RTCIceServer) + +### Video + +#### `NEKO_VIDEO_CODEC`: + - vp8 *(default encoder)* + - vp9 *(parameter not optimized yet)* + - h264 *(second best option)* +#### `NEKO_VIDEO_BITRATE`: + - Bitrate of the video stream in kb/s. + - e.g. 3500 +#### `NEKO_VIDEO`: + - Makes it possible to create custom gstreamer video pipeline. With this you could find the best quality for your CPU. + - Installed are + - `gstreamer1.0-plugins-base` + - `gstreamer1.0-plugins-good` + - `gstreamer1.0-plugins-bad` + - `gstreamer1.0-plugins-ugly` + - e.g. `ximagesrc display-name=%s show-pointer=true use-damage=false ! video/x-raw,framerate=30/1 ! videoconvert ! queue ! video/x-raw,format=NV12 ! x264enc threads=4 bitrate=3500 key-int-max=60 vbv-buf-capacity=4000 byte-stream=true tune=zerolatency speed-preset=veryfast ! video/x-h264,stream-format=byte-stream,profile=constrained-baseline` +#### `NEKO_MAX_FPS`: + - The resulting stream frames per seconds should be capped *(0 for uncapped)*. + - e.g. `0` +#### `NEKO_HWENC`: + - none *(default CPU encoding)* + - vaapi + - nvenc + +### Audio + +#### `NEKO_AUDIO_CODEC`: + - opus *(default encoder)* + - g722 + - pcmu + - pcma +#### `NEKO_AUDIO_BITRATE`: + - Bitrate of the audio stream in kb/s. + - e.g. `196` +#### `NEKO_AUDIO`: + - Makes it possible to create custom gstreamer audio pipeline, same as for video. + e.g. `pulsesrc device=%s ! audio/x-raw,channels=2 ! audioconvert ! opusenc bitrate=128000` + +### Broadcast + +#### `NEKO_BROADCAST_PIPELINE`: + - Makes it possible to create custom gstreamer pipeline used for broadcasting, strings `{url}`, `{device}` and `{display}` will be replaced. +#### `NEKO_BROADCAST_URL`: + - Set a default URL for broadcast streams. It can be disabled/changed later by admins in the GUI. + - e.g. `rtmp://:1935/ingest/` +#### `NEKO_BROADCAST_AUTOSTART`: + - Automatically start broadcasting when neko starts and broadcast_url is set. + - e.g. `true` +### Server + +#### `NEKO_BIND`: + - Address/port/socket where neko binds to *(default 127.0.0.1:8080)*. + - e.g. `:8080` +#### `NEKO_CERT`: + - Path to the SSL-Certificate. + - e.g. `/certs/cert.pem` +#### `NEKO_KEY`: + - Path to the SSL-Certificate private key. + - e.g. `/certs/key.pem` +#### `NEKO_PROXY`: + - Enable reverse proxy mode, so that neko trusts `X-Forwarded-For` headers. + - e.g. `false` +#### `NEKO_PATH_PREFIX`: + - Path prefix for HTTP requests. + - e.g. `/neko/` +#### `NEKO_CORS`: + - Cross origin request sharing, whitespace separated list of allowed hosts, `*` for all. + - e.g. `127.0.0.1 neko.example.com` + +### File Transfer + +#### `NEKO_FILE_TRANSFER_ENABLED`: + - Enable file transfer feature. + - e.g. `true` +#### `NEKO_FILE_TRANSFER_PATH`: + - Path where files will be transferred between the host and users. By default, this is + `/home/neko/Downloads`. If the path doesn't exist, it will be created. + - e.g. `/home/neko/Desktop` + +### Expert settings + +#### `NEKO_DISPLAY`: + - XDisplay to capture. +#### `NEKO_DEVICE`: + - Audio device be to captured. +#### `NEKO_STATIC`: + - Path to neko client files to serve. + +## Arguments + +You can execute `neko serve --help` to see available arguments. + +``` +Usage: + neko serve [flags] + +Flags: + --audio string audio codec parameters to use for streaming + --audio_bitrate int audio bitrate in kbit/s (default 128) + --audio_codec string audio codec to be used (default "opus") + --bind string address/port/socket to serve neko (default "127.0.0.1:8080") + --broadcast_pipeline string custom gst pipeline used for broadcasting, strings {url} {device} {display} will be replaced + --broadcast_url string URL for broadcasting, setting this value will automatically enable broadcasting + --cert string path to the SSL cert used to secure the neko server + --control_protection control protection means, users can gain control only if at least one admin is in the room + --cors strings list of allowed origins for CORS (default [*]) + --device string audio device to capture (default "audio_output.monitor") + --display string XDisplay to capture (default ":99.0") + --epr string limits the pool of ephemeral ports that ICE UDP connections can allocate from (default "59000-59100") + --file_transfer_enabled enable file transfer feature (default false) + --file_transfer_path string path to use for file transfer (default "/home/neko/Downloads") + --g722 DEPRECATED: use audio_codec + --h264 DEPRECATED: use video_codec + -h, --help help for serve + --hwenc string use hardware accelerated encoding + --icelite configures whether or not the ice agent should be a lite agent + --iceserver strings describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer (default [stun:stun.l.google.com:19302]) + --iceservers string describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer + --implicit_control if enabled members can gain control implicitly + --ipfetch string automatically fetch IP address from given URL when nat1to1 is not present (default "http://checkip.amazonaws.com") + --key string path to the SSL key used to secure the neko server + --locks strings resources, that will be locked when starting (control, login) + --max_fps int maximum fps delivered via WebRTC, 0 is for no maximum (default 25) + --nat1to1 strings sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP address is used + --opus DEPRECATED: use audio_codec + --password string password for connecting to stream (default "neko") + --password_admin string admin password for connecting to stream (default "admin") + --path_prefix string path prefix for HTTP requests (default "/") + --pcma DEPRECATED: use audio_codec + --pcmu DEPRECATED: use audio_codec + --proxy enable reverse proxy mode + --screen string default screen resolution and framerate (default "1280x720@30") + --static string path to neko client files to serve (default "./www") + --tcpmux int single TCP mux port for all peers + --udpmux int single UDP mux port for all peers + --video string video codec parameters to use for streaming + --video_bitrate int video bitrate in kbit/s (default 3072) + --video_codec string video codec to be used (default "vp8") + --vp8 DEPRECATED: use video_codec + --vp9 DEPRECATED: use video_codec + +Global Flags: + --config string configuration file path + -d, --debug enable debug mode + -l, --logs save logs to file +``` + +## Config file + +You can mount YAML config file to docker container on this path `/etc/neko/neko.yaml` and store your configuration there. + +Config uses the keys from arguments, that can be viewed in program's help output. + +Example (with just some of the available arguments): + +```yaml +# audio bitrate in kbit/s +audio_bitrate: 128 + +# video bitrate in kbit/s +video_bitrate: 3072 + +# maximum fps delivered via WebRTC, 0 is for no maximum +max_fps: 25 + +# password for connecting to stream +password: "neko" + +# admin password for connecting to stream +password_admin: "admin" + +# default screen resolution and framerate +screen: "1280x720@30" + +# limits the pool of ephemeral ports that ICE UDP connections can allocate from +epr: "59000-59100" +``` diff --git a/webpage/versioned_docs/version-v2/examples.md b/webpage/versioned_docs/version-v2/examples.md new file mode 100644 index 00000000..b73dc8ee --- /dev/null +++ b/webpage/versioned_docs/version-v2/examples.md @@ -0,0 +1,113 @@ +--- +sidebar_position: 3 +--- + +# Examples + +## Firefox + +```yaml +version: "3.4" +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + volumes: + - :/home/neko/.mozilla/firefox # persist firexfox settings + environment: + NEKO_SCREEN: '1920x1080@30' + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + NEKO_NAT1TO1: +``` + +## Chromium + +```yaml +version: "3.4" +services: + neko: + image: "m1k1o/neko:chromium" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + cap_add: + - SYS_ADMIN + environment: + NEKO_SCREEN: '1920x1080@30' + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + NEKO_NAT1TO1: +``` + +## VLC + +```yaml +version: "3.4" +services: + neko: + image: "m1k1o/neko:vlc" + restart: "unless-stopped" + shm_size: "2gb" + volumes: + - ":/video" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + cap_add: + - SYS_ADMIN + environment: + NEKO_SCREEN: '1920x1080@30' + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + NEKO_NAT1TO1: +``` + +## Raspberry Pi + +```yaml +version: "3.4" +services: + neko: + # see docs for more variants + image: "ghcr.io/m1k1o/neko/arm-chromium:latest" + restart: "unless-stopped" + # increase on rpi's with more then 1gb ram. + shm_size: "520mb" + ports: + - "8088:8080" + - "52000-52100:52000-52100/udp" + # note: this is important since we need a GPU for hardware acceleration alternatively + # mount the devices into the docker. + privileged: true + environment: + NEKO_SCREEN: '1280x720@30' + NEKO_PASSWORD: 'neko' + NEKO_PASSWORD_ADMIN: 'admin' + NEKO_EPR: 52000-52100 + # note: when setting NEKO_VIDEO, then variables NEKO_MAX_FPS and NEKO_VIDEO_BITRATE + # are not being used, you can adjust them in this variable. + NEKO_VIDEO: | + ximagesrc display-name=%s use-damage=0 show-pointer=true use-damage=false + ! video/x-raw,framerate=30/1 + ! videoconvert + ! queue + ! video/x-raw,framerate=30/1,format=NV12 + ! v4l2h264enc extra-controls="controls,h264_profile=1,video_bitrate=1250000;" + ! h264parse config-interval=3 + ! video/x-h264,stream-format=byte-stream,profile=constrained-baseline + NEKO_VIDEO_CODEC: h264 +``` + +## Not using docker? + +You can execute `neko --help` to see available arguments. In [Dockerfile](https://github.com/m1k1o/neko/blob/master/.docker/base/Dockerfile) you can find required dependencies and install them manually. diff --git a/webpage/versioned_docs/version-v2/faq.md b/webpage/versioned_docs/version-v2/faq.md new file mode 100644 index 00000000..17cd732a --- /dev/null +++ b/webpage/versioned_docs/version-v2/faq.md @@ -0,0 +1,78 @@ +--- +sidebar_position: 7 +--- + +# Frequently Asked Questions + +## How to enable debug mode? + +To see verbose information from n.eko server, you can enable debug mode using `NEKO_DEBUG`. + +```yaml title="docker-compose.yml" +version: "3.4" +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_SCREEN: 1920x1080@30 + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + # highlight-start + NEKO_DEBUG: 1 + # highlight-end +``` + +Ensure, that you have enabled debug mode in javascript console too, in order to see verbose information from client. + +## Chinese input method is not working + +There exists an extension [Google Input Tools](https://chrome.google.com/webstore/detail/mclkkofklkfljcocdinagocijmpgbhab) for Chrome that allows you to use Chinese input method. + +## Only black screen is displayed but remote cursor is moving for Chromium-based browsers (Chrome, Edge, etc.) + +Check if you did not forget to add cap_add to your docker-compose file. + +```yaml title="docker-compose.yml" +version: "3.4" +services: + neko: + image: "m1k1o/neko:chromium" + # highlight-start + cap_add: + - SYS_ADMIN + # highlight-end + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_SCREEN: '1920x1080@30' + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 +``` + +## How can I embed the Neko desktop into web page without login prompt coming up for viewers? + +You can use the following URL to embed the Neko desktop into a web page without login prompt coming up for viewers: + +``` +http://:8080/?usr=neko&pwd=neko +``` + +https://stackoverflow.com/questions/15276929/how-to-make-a-video-fullscreen-when-it-is-placed-inside-an-iframe + +Your iframe needs an attribute: `allowfullscreen="true" webkitallowfullscreen="true" mozallowfullscreen="true"` or more modern `allow="fullscreen *"`. For the second you can remove the star if your iframe has the same origin or replace it with your iframe origin. + +## Can I use neko without docker? + +It is strongly recommended to use Neko with Docker, as it is the easiest way to run it. But you should be able to install Neko "natively" on your host system. Neko is based on Debian and uses Xorg and Pulseaudio. You would just need to follow steps that are in Dockerfile, install all dependencies on your host system and then just run it. + +However, it is recommend to start with existing system that has GUI with desktop manager, is based on Xorg and uses Pulseaudio (e.g. Ubuntu Desktop 22.04). For that matter you only need to install gstreamer dependencies, configure pulseaudio properly and run neko binary (you don't need to build it from scratch, you can copy it from docker image). diff --git a/webpage/versioned_docs/version-v2/quick-start.md b/webpage/versioned_docs/version-v2/quick-start.md new file mode 100644 index 00000000..ec8b9497 --- /dev/null +++ b/webpage/versioned_docs/version-v2/quick-start.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 1 +--- + +# Quick Start + +Neko is easy to use and requires no technical expertise to get started. All you need to do is download the Docker image and you're ready to go: + +1. Deploy a server or VPS. + + **Recommended Specs:** + + | Resolution | Cores | Ram | Recommendation | + |-------------|-------|-------|------------------| + | 1024×576@30 | 2 | 2gb | Not Recommended | + | 1280x720@30 | 4 | 3gb | Good Performance | + | 1280x720@30 | 6 | 4gb | Recommended | + | 1280x720@30 | 8 | 4gb+ | Best Performance | + + + :::danger[Why are the specs so high?] + If you think about it, you have to run a full desktop, a browser (a resource hog on its own) *and* encode/transmit the desktop, there's a lot going on and so it demands some power. + ::: + + :::note + Admin can change the resolution in the GUI. + ::: + +2. [Login via SSH](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/). + +3. Install [Docker](https://docs.docker.com/get-docker/): + ```shell + curl -sSL https://get.docker.com/ | CHANNEL=stable bash + ``` + +4. Install [Docker Compose](https://docs.docker.com/compose/install/): + ```shell + sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose + sudo chmod +x /usr/local/bin/docker-compose + ``` + +5. Download docker compose file and start it: + ```shell + wget https://raw.githubusercontent.com/m1k1o/neko/master/docker-compose.yaml + sudo docker-compose up -d + ``` + +6. Visit the IP address server in your browser and login, the default password is `neko`. + +:::tip +Run `nano docker-compose.yaml` to edit the settings, then press `ctrl+x` to exit and save the file. +::: + +## Well known cloud providers +* [Hetzner Cloud](https://www.hetzner.com/cloud) +* [Digital Ocean](https://www.digitalocean.com/) +* [Contabo](https://contabo.com/) +* [Linode](https://www.linode.com/) +* [Vultr](https://www.vultr.com/) diff --git a/webpage/versioned_docs/version-v2/reverse-proxy.md b/webpage/versioned_docs/version-v2/reverse-proxy.md new file mode 100644 index 00000000..ebf36f3e --- /dev/null +++ b/webpage/versioned_docs/version-v2/reverse-proxy.md @@ -0,0 +1,177 @@ +--- +sidebar_position: 4 +--- + +# Behind reverse proxy? + +## Traefik2 + +```yaml +labels: + - "traefik.enable=true" + - "traefik.http.services.neko-frontend.loadbalancer.server.port=8080" + - "traefik.http.routers.neko.rule=${TRAEFIK_RULE}" + - "traefik.http.routers.neko.entrypoints=${TRAEFIK_ENTRYPOINTS}" + - "traefik.http.routers.neko.tls.certresolver=${TRAEFIK_CERTRESOLVER}" +``` + +(by [@m1k1o](https://github.com/m1k1o), [example](https://github.com/m1k1o/neko-vpn/blob/a1b934515dcf597992a515d61d307c2450a11002/docker-compose.yml#L38-L43)) + +## Nginx + +```conf +server { + listen 443 ssl http2; + server_name example.com; + + location / { + proxy_pass http://127.0.0.1:8080; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_read_timeout 86400; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $remote_addr; + proxy_set_header X-Forwarded-Host $host; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-Protocol $scheme; + } +} +``` + +(by [@GigaFyde](https://github.com/GigaFyde), [source](https://github.com/nurdism/neko/issues/111#issuecomment-742656957)) + +## Apache + +After successfully installing and running neko, you might want to get rid of the port in the url, use DNS instead of IP address and also having SSL. +This will remove the port from the URL and also enables HTTPS. + +To do this, you have to get running Apache server. Now you can go into the `/etc/apache2/sites-available` folder and create new config file for example `neko.conf` +After creating new config file, you can use this example config and paste it in. Some things may vary on your machine so read through and modify if needed. +Bear in mind that your neko server doesn't have to run on the same computer as Apache. They just have to be on the same network, and then you replace localhost with correct internal IP. + +```xml + + # The ServerName directive sets the request scheme, hostname and port that + # the server uses to identify itself. This is used when creating + # redirection URLs. In the context of virtual hosts, the ServerName + # specifies what hostname must appear in the request's Host: header to + # match this virtual host. For the default virtual host (this file) this + # value is not decisive as it is used as a last resort host regardless. + # However, you must set it for any further virtual host explicitly. + + # Paths of those modules might vary across different distros. + LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so + LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so + LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so + + ServerName example.com + ServerAlias www.example.com + + ProxyRequests Off + ProxyPass / http://localhost:8080/ + ProxyPassReverse / http://localhost:8080/ + + RewriteEngine on + RewriteCond %{HTTP:Upgrade} websocket [NC] + RewriteCond %{HTTP:Connection} upgrade [NC] + RewriteRule /ws(.*) "ws://localhost:8080/ws$1" [P,L] + + # Available loglevels: trace8, ..., trace1, debug, info, notice, warn, + # error, crit, alert, emerg. + # It is also possible to configure the loglevel for particular + # modules, e.g. + #LogLevel info ssl:warn + + ErrorLog ${APACHE_LOG_DIR}/error.log + CustomLog ${APACHE_LOG_DIR}/access.log combined + + # For most configuration files from conf-available/, which are + # enabled or disabled at a global level, it is possible to + # include a line for only one particular virtual host. For example the + # following line enables the CGI configuration for this host only + # after it has been globally disabled with "a2disconf". + #Include conf-available/serve-cgi-bin.conf + +``` + +(by [@DarkReaper231](https://github.com/DarkReaper231), [source](https://github.com/nurdism/neko/blob/cad98a62a5bd7f1daf2c11980631bb14ba81a1f6/docs/apache-proxypass-config.md#example-apache-config)) + +After creating your new config file, just use `sudo a2ensite neko.conf` and then `sudo systemctl reload apache2` + +### Enabling SSL + +If you want to use SSL for your apache configuration, you can install certbot and use it with `sudo certbot` +Then you can just select both `example.com` and `www.example.com` and apply. This will copy your `neko.conf` file and creates one for SSL. + +## Caddy + +```conf +https://example.com { + reverse_proxy localhost:8080 { + header_up Host {host} + header_up X-Real-IP {remote_host} + header_up X-Forwarded-For {remote_host} + header_up X-Forwarded-Proto {scheme} + } +} +``` + +(by [@ccallahan](https://github.com/ccallahan), [source](https://github.com/nurdism/neko/pull/125/commits/eb4ceda75423b0d960c8aea0240acf6d7a10fef4)) + +## HAProxy + +Using your frontend section *(mine is called http-in)*, add the ACL to redirect correctly to your n.eko instance. + +```sh +frontend http-in + #/******** + #* NEKO * + acl neko_rule_http hdr(host) neko.domain.com # Adapt the domain + use_backend neko_srv if neko_rule_http + #********/ + +backend neko_srv + mode http + option httpchk + server neko 172.16.0.0:8080 # Adapt the IP +``` + +Then, restart the haproxy service. +```sh +service haproxy restart +``` + +### Having trouble reaching your HAProxy ? + +Try the following steps: + +- Verify the logs / what HAProxy is telling you : + ```sh + service haproxy status + ``` + +- If the service is UP and the ACL rule + backend is OK then tail the log and keep them to verify : + ```sh + tail -f /var/log/haproxy.log + # after that, go to your neko.instance.com and look for the logs in the shell + ``` + +- Ensure you set the timeout to 60 seconds before the request fail. + ```sh + global + stats timeout 60s + ``` + +- Ensure you set the forwardfor and the timeout aswell in the defaults section. + ```sh + defaults + option forwardfor + timeout connect 30000 + timeout client 65000 + timeout server 65000 + ``` +*(Don't forget to restart the service each time you modify the `.cfg` file !)* + +(by [@RisedSky](https://github.com/RisedSky)) diff --git a/webpage/versioned_docs/version-v2/troubleshooting.md b/webpage/versioned_docs/version-v2/troubleshooting.md new file mode 100644 index 00000000..5a447bfc --- /dev/null +++ b/webpage/versioned_docs/version-v2/troubleshooting.md @@ -0,0 +1,252 @@ +--- +sidebar_position: 6 +--- + +# Troubleshooting + +Neko UI loads, but you don't see the screen, and it gives you `connection timeout` or `disconnected` error? + +## Test your client + +Some browsers may block WebRTC access by default. You can check if it is enabled by going to `about:webrtc` or `chrome://webrtc-internals` in your browser. + +Check if your extensions are not blocking WebRTC access. Following extensions are known to block or does not work properly with WebRTC: +- Privacy Badger +- Private Internet Access +- PIA VPN (even if disabled) + +Test whether your client [supports](https://www.webrtc-experiment.com/DetectRTC/) and can [connect to WebRTC](https://www.webcasts.com/webrtc/). + +## Networking + +If you are absolutely sure, that your client is working correctly, then most likely your networking is not set up correctly. + +### Check if your ports are correctly exposed using docker + +Check that your ephemeral port range `NEKO_EPR` is correctly exposed as `/udp` port range. + +In following example, specified range `52000-52100` must be also exposed using docker. + +```yaml title="docker-compose.yml" +version: "3.4" +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + # highlight-start + - "52000-52100:52000-52100/udp" + # highlight-end + environment: + NEKO_SCREEN: 1920x1080@30 + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + # highlight-start + NEKO_EPR: 52000-52100 + # highlight-end + NEKO_ICELITE: 1 +``` + +### Validate UDP ports reachability + +Ensure, that your ports are reachable through your external IP. + +To validate UDP connection the simplest way, run this on your server: + +```shell +nc -ul 52101 +``` + +And this on your local client: + +```shell +nc -u [server ip] 52101 +``` +Then try to type on one end, you should see characters on the other side. + +![nc command example](/v2/udp-ports-nc.png) + +If it does not work for you, then most likely your port forwarding is not working correctly. Or your ISP is blocking traffic. + + +If you get [`Command 'nc' not found.`](https://command-not-found.com/nc) error, you can install `netcat` package using: + +```shell +sudo apt-get install netcat +``` + +### Check if your external IP was determined correctly + +One of the first logs, when the server starts, writes down your external IP that will be sent to your clients to connect to. + +```shell +docker-compose logs neko | grep nat_ips +``` + +Note: Some newer versions of docker-compose use `docker compose` instead of `docker-compose`. + +You should see this: + +``` +11:11AM INF webrtc starting ephemeral_port_range=52000-52100 ice_lite=true ice_servers="[{URLs:[stun:stun.l.google.com:19302] Username: Credential: CredentialType:password}]" module=webrtc nat_ips= +``` + +If your IP is not correct, you can specify own IP resolver using `NEKO_IPFETCH`. It needs to return IP address that will be used. + +```yaml title="docker-compose.yml" +version: "3.4" +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_SCREEN: 1920x1080@30 + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + NEKO_ICELITE: 1 + # highlight-start + NEKO_IPFETCH: https://ifconfig.co/ip + # highlight-end +``` + +Or you can specify your IP address manually using `NEKO_NAT1TO1`: (It's read as NAT 1 to 1, so it's capital letter 'O', not zero '0', in NAT1`TO`1) + +```yaml title="docker-compose.yml" +version: "3.4" +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_SCREEN: 1920x1080@30 + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + NEKO_ICELITE: 1 + # highlight-start + NEKO_NAT1TO1: + # highlight-end +``` + +If you want to use n.eko only locally, you must put here your local IP address, otherwise public address will be used. + +### Neko works externally, but not locally + +You are probably missing NAT Loopback (NAT Hairpinning) setting on your router. + +Example for pfsense with truecharts docker container: +- First, port forward the relevant ports `8080` and `52000-52100/udp` for the container. +- Then turn on `Pure NAT` pfsense (under system > advanced > firewall and nat). + - Make sure to check the two boxes so it works. +- Make sure `NEKO_NAT1TO1` is blank and `NEKO_IPFETCH` address is working correctly (if unset default value is chosen). +- Test externally to confirm it works. +- Internally you have to access it using `:port` + +If your router does not support NAT Loopback (NAT Hairpinning), you can use turn servers to overcome this issue. See [more details here](https://neko.m1k1o.net/#/getting-started/?id=networking) on how to setup local coturn instance. + +### Neko works locally, but not externally + +Make sure, that you are exposing your ports correctly. + +If you put local ip as `NEKO_NAT1TO1`, external clients try to connect to that ip. But it is unreachable for them, because it is your local IP. You must use your public IP address with port forwarding. + +## Debug mode + +To see verbose information from n.eko server, you can enable debug mode using `NEKO_DEBUG`. + +```yaml title="docker-compose.yml" +version: "3.4" +services: + neko: + image: "m1k1o/neko:firefox" + restart: "unless-stopped" + shm_size: "2gb" + ports: + - "8080:8080" + - "52000-52100:52000-52100/udp" + environment: + NEKO_SCREEN: 1920x1080@30 + NEKO_PASSWORD: neko + NEKO_PASSWORD_ADMIN: admin + NEKO_EPR: 52000-52100 + # highlight-start + NEKO_DEBUG: 1 + # highlight-end +``` + +Ensure, that you have enabled debug mode in javascript console too, in order to see verbose information from client. + +## Frequently Encountered Errors + +### Common server errors + +``` +WRN session created with and error error="invalid 1:1 NAT IP mapping" +``` + +Check your `NEKO_NAT1TO1` or ensure, that `NEKO_IPFETCH` returns correct IP. + +--- + +``` +WRN could not get server reflexive address udp6 stun:stun.l.google.com:19302: write udp6 [::]:52042->[2607:f8b0:4001:c1a::7f]:19302: sendto: cannot assign requested address +``` + +Check if your DNS is set up correctly, and if your IPv6 connectivity is working properly, or is disabled. + +--- + +``` +WRN undeclaredMediaProcessor failed to open SrtcpSession: the DTLS transport has not started yet module=webrtc subsystem= +``` + +Check if your UDP ports are exposed correctly and reachable. + +### Common client errors + +``` +Firefox can’t establish a connection to the server at ws:///ws?password=neko. +``` + +Check if your TCP port is exposed correctly and your reverse proxy is correctly proxying websocket connections. And if your browser has not disabled websocket connections. + +--- + +``` +Getting black screen with a cursor, but no browser. +``` + +Most likely you forgot to add `-cap-add=SYS_ADMIN` when using chromium-based browsers. + +### Unrelated server errors + +``` +[ERROR:bus.cc(393)] Failed to connect to the bus: Could not parse server address: Unknown address type (examples of valid types are "tcp" and on UNIX "unix") +``` + +This error originates from browser, that it could not connect to dbus. This does not affect us and can be ignored. + +### Broadcast pipeline not working with some ingest servers + +See [related issue](https://github.com/m1k1o/neko/issues/276). + +``` +Could not connect to RTMP stream "'rtmp:///live/ live=1'" for writing +``` + +Some ingest servers require `live=1` parameter in the URL (e.g. nginx-rtmp-module). Some do not and do not accept aphostrophes (e.g. owncast). You can try to change the pipeline to: + +```yaml +NEKO_BROADCAST_PIPELINE: "flvmux name=mux ! rtmpsink location={url} pulsesrc device={device} ! audio/x-raw,channels=2 ! audioconvert ! voaacenc ! mux. ximagesrc display-name={display} show-pointer=false use-damage=false ! video/x-raw,framerate=28/1 ! videoconvert ! queue ! x264enc bframes=0 key-int-max=0 byte-stream=true tune=zerolatency speed-preset=veryfast ! mux." +``` diff --git a/webpage/versioned_sidebars/version-v2-sidebars.json b/webpage/versioned_sidebars/version-v2-sidebars.json new file mode 100644 index 00000000..caea0c03 --- /dev/null +++ b/webpage/versioned_sidebars/version-v2-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/webpage/versions.json b/webpage/versions.json new file mode 100644 index 00000000..97b1ae88 --- /dev/null +++ b/webpage/versions.json @@ -0,0 +1,3 @@ +[ + "v2" +]