iridium/neko
2
2
Fork 0
mirror of https://github.com/m1k1o/neko.git synced 2024-07-24 14:40:50 +12:00
Code Issues Packages Projects Releases Wiki Activity

update docs #95.

Browse Source
This commit is contained in:
Miroslav Šedivý 2021-10-23 15:54:58 +02:00
parent b516da2e97
commit 3889a761df
28 changed files with 748 additions and 598 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

442
README.md
View File

@ -21,431 +21,47 @@
<br/>
</div>
# n.eko (m1k1o fork)
This app uses Web-RTC to stream a desktop inside a docker container. This is a fork of https://github.com/nurdism/neko.
# n.eko
For n.eko room management software, visit https://github.com/m1k1o/neko-rooms.
This app uses Web RTC to stream a desktop inside of a docker container, original author made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and his internet could not handle streaming and discord kept crashing when his friend attempted to. He just wanted to watch anime with his friends ლ(ಠ益ಠლ) so he started digging throughout the internet and found a few *kinda* clones, but none of them had the virtual browser, then he found [Turtus](https://github.com/Khauri/Turtus) and he was able to figure out the rest.
## Differences to original repository.
Then I found [this](https://github.com/nurdism/neko) project and started to dig into it. I really liked the idea of having collaborative browser browsing together with mutliple people, so I created a fork. Initially, I wanted to merge my changes to the upstream repository, but the original author did not have time for this project anymore and it got eventually archived.
### New Features
- Clipboard button with text area - for browsers, that don't support clipboard syncing (Firefox, what a shame...) or for HTTP.
- Keyboard modifier state synchronization (Num-Lock, Caps-Lock, Scroll-Lock) for each hosting.
- Added chromium ungoogled (with h265 support) an kept up to date (by @whalehub).
- Added Picture in Picture button (only for watching screen, controlling not possible).
- Added RTMP broadcast. Enables broadcasting n.eko screen to local RTMP server, YouTube or Twitch. Example: `rtmp://a.rtmp.youtube.com/live2/<your-streaming-key>`.
- Stereo sound (works properly only in Firefox host).
- Added limited support for some mobile browsers with `playsinline` attribute.
- Added `VIDEO_BITRATE` and `AUDIO_BITRATE` in kbit/s to control stream quality (in collaboration with @mbattista).
- Added `MAX_FPS`, where you can specify max WebRTC frame rate. When set to `0`, frame rate won't be capped, and you can enjoy your real `60fps` experience. Originally, it was constant at `25fps`.
- Invite links. You can invite people, and they don't need to enter passwords by themselves (and get confused about user accounts that do not exist). You can put your password in URL using `?pwd=<your-password>` and it will be automatically used when logging in.
- Added `/stats?pwd=<admin>` endpoint to get total active connections, host and members.
- Added `m1k1o/neko:vlc` tag, use VLC to watch local files together (by @mbattista).
- Added `m1k1o/neko:xfce` tag, as a non-video related showcase (by @mbattista).
- Added ARM-based images, for Raspberry Pi support (by @mbattista).
- Added simple language picker.
- Added `?usr=<display-name>` that will prefill username. This allows creating auto-join links.
- Added `?cast=1` that will hide all control and show only video.
- Shake keyboard icon if someone attempted to control when is nobody hosting.
- Support for password protected `NEKO_ICESERVERS` (by @mbattista).
- Added bunch of translations (🇸🇰, 🇪🇸, 🇸🇪, 🇳🇴, 🇫🇷) by various people.
- Added `m1k1o/neko:google-chrome` tag.
- Show red dot badge on sidebar toggle if there are new messages, and user can't see them.
- Added `m1k1o/neko:brave` tag.
### Features
### Bugs
- Fixed minor gst pipeline bug.
- Locked screen only for users, admins can still join.
- Fixed h264 pipelines bugs (by @mbattista).
- Fixed sessions manager thread safety by adding mutexes (caused panic in rare edge cases).
- Now when user gets kicked, he won't join as a ghost user again but will be logged out.
- **iOS compatibility!** Fixed a really strange CSS bug, which prevented iOS from loading the video.
- Proper disconnect only once with unsubscribing events. When Web-RTC fails, user won't be logged in without username again.
- Upgraded and fixed emojis to a new major version.
- Fixed bad `keymap -> keysym` translation to respect active modifiers (#45, with @mbattista).
- Respecting `NEKO_DEBUG` env variable.
- Full-screen support for iOS devices.
- Added `chrome-sandbox` to fix weird bug when chromium didn't start.
- Fixed keyboard mapping on macOS, when CMD could not be used for copy & paste.
- Fixed stop signal sent by supervisor to gracefully shut down neko server.
* Text Chat (With basic markdown support, discord flavor)
* Admin users (Kick, Ban & Force Give/Release Controls)
* Clipboard synchronization (on [supported browsers](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/readText))
* Emote overlay
* Ignore user (chat and emotes)
* Persistent settings
### Misc
- Custom docker workflow.
- Based on Debian buster instead of stretch.
- Versions bumped: Go 16, Node.js 14 (by @mbattista).
- Custom avatars without any 3rd party dependency.
- Ignore duplicate notify bars.
- No pointer events for notify bars.
- Disable debug mode by default.
- Remove HTML tags from username.
- Upgraded `pion/webrtc` to v3 (by @mbattista).
- Added `requestFullscreen` compatibility for older browsers and iOS devices.
- Fixed small lags in video and improved video UX (by @mbattista).
- Added `m1k1o/neko:vncviewer` tag, use `NEKO_VNC_URL` to specify VNC target and use n.eko as a bridge.
- Ability to include n.eko as a component in another Vue.Js project (by @gbrian).
- Added HEALTHCHECK to Dockerfile.
- Arguments in broadcast pipeline are optional, not positional and can be repeated `{url} {device} {display}`.
- Chat messages are dense, when repeated, they are joined together.
- While IP address fetching is now proxy ignored.
- Start unmuted on reconnects.
- Switched to the latest Firefox version instead of esr.
- Fixed very fast scroll speed on macOS.
- Broadcast pipeline errors are reported to the user.
- On stopping server all websocket connections are going to be gracefully disconnected.
- ARM-based images not bound to Raspberry Pi only.
### Why n.eko?
# Getting started & FAQ
I like cats 🐱 (`Neko` is the Japanese word for cat), I'm a weeb/nerd.
Use the following docker images:
- `m1k1o/neko:latest` - for Firefox.
- `m1k1o/neko:chromium` - for Chromium (needs `--cap-add=SYS_ADMIN`).
- `m1k1o/neko:google-chrome` - for Google Chrome (needs `--cap-add=SYS_ADMIN`).
- `m1k1o/neko:ungoogled-chromium` - for [Ungoogled Chromium](https://github.com/Eloston/ungoogled-chromium) (needs `--cap-add=SYS_ADMIN`) (by @whalehub).
- `m1k1o/neko:brave` - for [Brave Browser](https://brave.com) (needs `--cap-add=SYS_ADMIN`).
- `m1k1o/neko:tor-browser` - for Tor Browser.
- `m1k1o/neko:vncviewer` - for simple VNC viewer (specify `NEKO_VNC_URL` to your VNC target).
- `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` - for a shared desktop / installing shared software.
- `m1k1o/neko:base` - for custom base.
***But why the cat butt?*** Because cats are *assholes*, but you love them anyways.
For ARM-based devices (like Raspberry Pi, with GPU hardware acceleration):
- `m1k1o/neko:arm-firefox` - for Firefox.
- `m1k1o/neko:arm-chromium` - for Chromium.
- `m1k1o/neko:arm-base` - for custom arm based.
# Multiple rooms
Images (except `arm-`) are built using GitHub actions on every push and on weekly basis to keep all browsers up-to-date,
For n.eko room management software, visit [neko-rooms](https://github.com/m1k1o/neko-rooms).
### 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 (see https://github.com/m1k1o/neko/issues/47).
It also offers zero-knowledge [installation script](https://github.com/m1k1o/neko-rooms/#zero-knowledge-installation).
### 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`
# Documentation
### Behind reverse proxy?
<details>
<summary>Traefik2 configuration</summary>
```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, [example](https://github.com/m1k1o/neko-vpn/blob/a1b934515dcf597992a515d61d307c2450a11002/docker-compose.yml#L38-L43))
</details>
<details>
<summary>Nginx configuration</summary>
```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, [source](https://github.com/nurdism/neko/issues/111#issuecomment-742656957))
</details>
<details>
<summary>Apache configuration</summary>
```xml
<VirtualHost *:80>
# 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
</VirtualHost>
```
(by @DarkReaper231, [source](https://github.com/nurdism/neko/blob/cad98a62a5bd7f1daf2c11980631bb14ba81a1f6/docs/apache-proxypass-config.md#example-apache-config))
</details>
<details>
<summary>Caddy configuration</summary>
```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, [source](https://github.com/nurdism/neko/pull/125/commits/eb4ceda75423b0d960c8aea0240acf6d7a10fef4))
</details>
### Want to customize and install own add-ons, set custom bookmarks?
- You would need to modify the existing policy file and mount it to your container.
- For Firefox, copy [this](https://github.com/m1k1o/neko/blob/master/.m1k1o/firefox/policies.json) file, modify and mount it as: ` -v '${PWD}/policies.json:/usr/share/firefox-esr/distribution/policies.json'`
- For Chromium, copy [this](https://github.com/m1k1o/neko/blob/master/.m1k1o/chromium/policies.json) file, modify and mount it as: ` -v '${PWD}/policies.json:/etc/chromium/policies/managed/policies.json'`
### Want to use VPN for your n.eko browsing?
- Check this out: https://github.com/m1k1o/neko-vpn
### Want to have multiple rooms on demand?
- Check this out: https://github.com/m1k1o/neko-rooms
### Want to use different Apps than Browser?
- Check this out: https://github.com/m1k1o/neko-apps
### Accounts:
- There are no accounts, display name (a.k.a. username) can be freely chosen. Only password needs to match. Depending on which password matches, the visitor gets its privilege:
- Anyone, who enters with `NEKO_PASSWORD` will be **user**.
- Anyone, who enters with `NEKO_PASSWORD_ADMIN` will be **admin**.
### 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.
## Firefox
```yaml
version: "3.4"
services:
neko:
image: "m1k1o/neko:latest"
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_NAT1TO1: <your-IP>
```
## 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: <your-IP>
```
## VLC
```yaml
version: "3.4"
services:
neko:
image: "m1k1o/neko:vlc"
restart: "unless-stopped"
shm_size: "2gb"
volumes:
- "<your-video-folder>:/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: <your-IP>
```
## Raspberry Pi
Note! Since HW accelerated pipeline is using H264, you are only able to connect from browsers supporting H264 for WebRTC. At the time of implementing, [Firefox does not support this](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/WebRTC_codecs#supported-foot-1). When omitting `NEKO_VIDEO` and `NEKO_H264` parameters, you get default CPU encoding with VP8.
```yaml
version: "3.4"
services:
neko:
image: "m1k1o/neko:arm-chromium"
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=0,video_bitrate=1250000;"
! h264parse config-interval=3
! video/x-h264,profile=baseline,stream-format=byte-stream
NEKO_H264: 1
```
## Not using docker?
You can execute `neko --help` to see available arguments. In [Dockerfile](https://github.com/m1k1o/neko/blob/master/.m1k1o/base/Dockerfile) you can find required dependencies and install them manually.
## Mobile support
N.eko is now working on iOS and Android! Also, the UI screens have been fixed for small screens.
![mobile-screens](https://i.imgur.com/K9gfscU.png)
## Docker-Compose Environment Options
```code
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_EPR:
- For WebRTC needed range of ports
- e.g. 52000-52100
NEKO_VP8:
- If vp8 should be used as video encoder for the stream (default encoder)
- e.g. 'true'
NEKO_VP9:
- If vp9 should be used as video encoder for the stream (Parameter not optimized yet)
- e.g. 'false'
NEKO_H264:
- If h264 should be used as video encoder for the stream (second best option)
- e.g. 'false'
NEKO_VIDEO_BITRATE:
- Bitrate of the video stream in kb/s
- e.g. 3500
NEKO_VIDEO:
- Makes it possible to create custom gstreamer pipelines. 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 '
NEKO_MAX_FPS:
- The resulting stream frames per seconds should be capped (0 for uncapped)
- e.g. 0
NEKO_OPUS:
- If opus should be used as audio encoder for the stream (default encoder)
- e.g. 'true'
NEKO_G722:
- If g722 should be used as audio encoder for the stream
- e.g. 'false'
NEKO_PCMU:
- If pcmu should be used as audio encoder for the stream
- e.g. 'false'
NEKO_PCMA:
- If pcma should be used as audio encoder for the stream
- e.g. 'false'
NEKO_AUDIO_BITRATE:
- Bitrate of the audio stream in kb/s
- e.g. 196
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_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)
```
* [Getting Started](https://neko.m1k1o.net/#/getting-started/)
* [Quick Start](https://neko.m1k1o.net/#/getting-started/quick-start)
* [Examples](https://neko.m1k1o.net/#/getting-started/examples)
* [Reverse Proxy](https://neko.m1k1o.net/#/getting-started/reverse-proxy)
* [Configuration](https://neko.m1k1o.net/#/getting-started/configuration)
* [Troubleshooting](https://neko.m1k1o.net/#/getting-started/troubleshooting)
* [Mobile Support](https://neko.m1k1o.net/#/mobile-support)
* [Contributing](https://neko.m1k1o.net/#/contributing)
* [Non Goals](https://neko.m1k1o.net/#/non-goals)
* [Technologies](https://neko.m1k1o.net/#/technologies)
* [Changelog](https://neko.m1k1o.net/#/changelog)
# How to contribute? How to build?
Navigate to [.m1k1o/README.md](.m1k1o/README.md) for further information.
Navigate to [.m1k1o](.m1k1o) folder for further information.

20
docker-compose.dev.yaml
View File

@ -1,20 +0,0 @@
version: "3.4"
services:
neko:
build: .m1k1o/chromium
container_name: neko_chromium
restart: always
shm_size: "3gb"
ports:
- "3005:8080"
- "52000-52010:52000-52010/udp"
cap_add:
- SYS_ADMIN
environment:
DISPLAY: :99.0
NEKO_SCREEN: '1920x1080@30'
NEKO_PASSWORD: neko
NEKO_PASSWORD_ADMIN: admin
NEKO_BIND: :8080
NEKO_EPR: 52000-52010
NEKO_NAT1TO1: 192.168.1.20

15
docker-compose.yaml Normal file
View File

@ -0,0 +1,15 @@
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

9
docs/README.md
View File

@ -8,9 +8,13 @@
</div>
# n.eko
This app uses Web RTC to stream a desktop inside of a docker container, I made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and my internet can't handle streaming and discord keeps crashing when my friend attempts to. I just want to watch anime with my friends ლ(ಠ益ಠლ) so I started digging throughout the internet and found a few *kinda* clones, but none of them had the virtual browser, then I found [Turtus](https://github.com/Khauri/Turtus) and I was able to figure out the rest. This is by no means a fully featured clone of rabbit, it hs only *one* room. It's stateless, so no saved user names or passwords.
This app uses Web RTC to stream a desktop inside of a docker container, original author made this because [rabb.it](https://en.wikipedia.org/wiki/Rabb.it) went under and his internet could not handle streaming and discord kept crashing when his friend attempted to. He just wanted to watch anime with his friends ლ(ಠ益ಠლ) so he started digging throughout the internet and found a few *kinda* clones, but none of them had the virtual browser, then he found [Turtus](https://github.com/Khauri/Turtus) and he was able to figure out the rest.
Then I found [this](https://github.com/nurdism/neko) project and started to dig into it. I really liked the idea of having collaborative browser browsing together with mutliple people, so I created a fork. Initially, I wanted to merge my changes to the upstream repository, but the original author did not have time for this project anymore and it got eventually archived.
### Features
* Text Chat (With basic markdown support, discord flavor)
* Admin users (Kick, Ban & Force Give/Release Controls)
* Clipboard synchronization (on [supported browsers](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/readText))
@ -19,6 +23,7 @@
* Persistent settings
### Why n.eko?
I like cats 🐱 (`Neko` is the Japanese word for cat), I'm a weeb/nerd
I like cats 🐱 (`Neko` is the Japanese word for cat), I'm a weeb/nerd.
***But why the cat butt?*** Because cats are *assholes*, but you love them anyways.

2
docs/_coverpage.md
View File

@ -9,4 +9,4 @@
<!-- background color -->
![color](#e2e2e2)
![color](#e2e2e2)

BIN
docs/_media/mobile-support.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 631 KiB

21
docs/_sidebar.md
View File

@ -1,14 +1,13 @@
<!-- _navbar.md -->
* [Getting Started](/getting-started)
* [Quick Start](/quick-start)
* [Configuration](/configuration)
* [Development](/development)
* [Client](/client)
* [Server](/server)
* [Docker](/docker)
* [Getting Started](/getting-started/)
* [Quick Start](/getting-started/quick-start)
* [Examples](/getting-started/examples)
* [Reverse Proxy](/getting-started/reverse-proxy)
* [Configuration](/getting-started/configuration)
* [Troubleshooting](/getting-started/troubleshooting)
* [Mobile Support](/mobile-support)
* [Contributing](/contributing)
* [Non Goals](/non-goals)
* [Contributing](/contributing)
* [Change logs](/change-logs/)
* [Technologies](/technologies)
* [Glossary](/glossary)
* [Technologies](/technologies)
* [Changelog](/changelog)

1
docs/change-logs/README.md
View File

@ -1 +0,0 @@
# Change logs (WIP)

111
docs/changelog.md Normal file
View File

@ -0,0 +1,111 @@
# Changelog
## master branch
### Misc
- ARM-based images not bound to Raspberry Pi only.
## [n.eko v2.4](https://github.com/m1k1o/neko/releases/tag/v2.4)
### New Features
- Show red dot badge on sidebar toggle if there are new messages, and user can't see them.
- Added `m1k1o/neko:brave` tag.
### Bugs
- Fixed keyboard mapping on macOS, when CMD could not be used for copy & paste.
- Fixed stop signal sent by supervisor to gracefully shut down neko server.
### Misc
- Switched to the latest Firefox version instead of esr.
- Fixed very fast scroll speed on macOS.
- Broadcast pipeline errors are reported to the user.
- On stopping server all websocket connections are going to be gracefully disconnected.
### Other changes
- Upgraded dependencies (server, client),
- Don't kill webrtc on temporary network issues #48.
- Custom ipfetch #63.
- Build images using github actions #70.
- Refactored RTMP broadcast design #88.
- Based on Debian 11 #91.
## [n.eko v2.3](https://github.com/m1k1o/neko/releases/tag/v2.3)
### New Features
- Added simple language picker.
- Added `?usr=<display-name>` that will prefill username. This allows creating auto-join links.
- Added `?cast=1` that will hide all control and show only video.
- Shake keyboard icon if someone attempted to control when is nobody hosting.
- Support for password protected `NEKO_ICESERVERS` (by @mbattista).
- Added bunch of translations (🇸🇰, 🇪🇸, 🇸🇪, 🇳🇴, 🇫🇷) by various people.
- Added `m1k1o/neko:google-chrome` tag.
### Bugs
- Upgraded and fixed emojis to a new major version.
- Fixed bad `keymap -> keysym` translation to respect active modifiers (#45, with @mbattista).
- Respecting `NEKO_DEBUG` env variable.
- Fullscreen support for iOS devices.
- Added `chrome-sandbox` to fix weird bug when chromium didn't start.
### Misc
- Arguments in broadcast pipeline are optional, not positional and can be repeated `{url} {device} {display}`.
- Chat messages are dense, when repeated, they are joined together.
- While IP address fetching is now proxy ignored.
- Start unmuted on reconnects and auto unmute on any control attempt.
## [n.eko v2.2](https://github.com/m1k1o/neko/releases/tag/v2.2)
### New Features
- Added limited support for some mobile browsers with `playsinline` attribute.
- Added `VIDEO_BITRATE` and `AUDIO_BITRATE` in kbit/s to control stream quality (in collaboration with @mbattista).
- Added `MAX_FPS`, where you can specify max WebRTC frame rate. When set to `0`, frame rate won't be capped and you can enjoy your real `60fps` experience. Originally, it was constant at `25fps`.
- Invite links. You can invite people and they don't need to enter passwords by themselves (and get confused about user accounts that do not exits). You can put your password in URL using `?pwd=<your-password>` and it will be automatically used when logging in.
- Added `/stats?pwd=<admin>` endpoint to get total active connections, host and members.
- Added `m1k1o/neko:vlc` tag, use VLC to watch local files together (by @mbattista).
- Added `m1k1o/neko:xfce` tag, as an non video related showcase (by @mbattista).
- Added ARM-based images, for Raspberry Pi support (by @mbattista).
### Bugs
- Fixed h264 pipelines bugs (by @mbattista).
- Fixed sessions manager thread safety by adding mutexes (caused panic in rare edge cases).
- Now when user gets kicked, he won't join as a ghost user again but will be logged out.
- **iOS compatibility!** Fixed really strange CSS bug, which prevented iOS from loading the video.
- Proper disconnect only once with unsubscribing events. When webrtc fails, user won't be logged in without username again.
### Misc
- Versions bumped: Go 16, Node.js 14 (by @mbattista).
- Remove HTML tags from user name.
- Upgraded `pion/webrtc` to v3 (by @mbattista).
- Added `requestFullscreen` compatibility for older browsers.
- Fixed small lags in video and improved video UX (by @mbattista).
- Added `m1k1o/neko:vncviewer` tag, use `NEKO_VNC_URL` to specify VNC target and use n.eko as a bridge.
- Abiltiy to include neko as a component in another Vue.Js project (by @gbrian).
- Added HEALTHCHECK to Dockerfile.
## [n.eko v2.1](https://github.com/m1k1o/neko/releases/tag/v2.1)
### New Features
- Clipboard button with text area - for browsers, that don't support clipboard syncing or for HTTP.
- Keyboard modifier state synchronization (Num Lock, Caps Lock, Scroll Lock) for each hosting.
- Added chromium ungoogled (with h265 support) an kept up to date by @whalehub.
- Added Picture in Picture button (only for watching screen, controlling not possible).
- Added RTMP broadcast. Enables broadcasting neko screen to local RTMP server, YouTube or Twitch.
- Stereo sound (works properly only in Firefox host).
### Bugs
- Fixed minor gst pipeline bug.
- Locked screen only for users, admins can still join.
### Misc
- Custom docker workflow.
- Based on debian buster instead of stretch.
- Custom avatars without any 3rd party depenency.
- Ignore duplicate notify bars.
- No pointer events for notify bars.
- Disable debug mode by default.
## [n.eko v2.0](https://github.com/nurdism/neko/releases/tag/2.0.0)
## [n.eko v1.1](https://github.com/nurdism/neko/releases/tag/1.1.0)
## [n.eko v1.0](https://github.com/nurdism/neko/releases/tag/1.0.0)

14
docs/client.md
View File

@ -1,14 +0,0 @@
# Client (WIP)
Web client for n.eko
## Environment
------
```
VUE_APP_SERVER_PORT // development server port
```
## Building
------
```
npm install && npm run build
```

10
docs/configuration.md
View File

@ -1,10 +0,0 @@
# Configuration (WIP)
## Docker Basic Configuration
```
NEKO_PASSWORD=neko // Password
NEKO_PASSWORD_ADMIN=admin // Admin Password
NEKO_BIND=0.0.0.0:8080 // Bind
NEKO_KEY= // (SSL) Key, needed for clipboard sync
NEKO_CERT= // (SSL) Cert, needed for clipboard sync
```

10
docs/contributing.md
View File

@ -1,5 +1,9 @@
# Contributing
* Fork the [project](https://github.com/m1k1o/neko).
* Edit files in your branch.
* Submit a pull request explaining the improvements.
1. Fork the [project](https://github.com/m1k1o/neko).
2. Navigate to [.m1k1o/README.md](https://github.com/m1k1o/neko/tree/master/.m1k1o) for further information.
3. Edit files in your branch.
4. Submit a pull request explaining the improvements.

12
docs/development.md
View File

@ -1,12 +0,0 @@
# Development (WIP)
*Highly* recommend you use a [dev container](https://code.visualstudio.com/docs/remote/containers) for [vscode](https://code.visualstudio.com/), I've included the `.devcontainer` I've used to develop this app. To build **n**.eko docker container run:
```
cd .docker && ./build docker
```
the `.docker` folder also contains `./test <browser>` bash script which will launch a desktop with a browser for testing out any changes with the server.
To run the client with hot loading (for development of new client features)
```
cd ./client && npm run serve
```

15
docs/docker.md
View File

@ -1,15 +0,0 @@
# Docker (WIP)
## Running:
### Chromium container:
```
sudo docker run -p 80:8080 -p 59000-59100:59000-59100/udp -e NEKO_PASSWORD='secret' -e NEKO_PASSWORD_ADMIN='secret' --cap-add SYS_ADMIN --shm-size=1gb m1k1o/neko:chromium
```
*Note:* `--cap-add SYS_ADMIN` & `--shm-size=1gb` is required for chromium to run properly
----
### Firefox container:
```
sudo docker run -p 8080:8080 -p 59000-59100:59000-59100/udp -e NEKO_PASSWORD='secret' -e NEKO_PASSWORD_ADMIN='secret' --shm-size=1gb m1k1o/neko:firefox
```
*Note:* `--shm-size=1gb` is required for firefox, tabs will crash otherwise

1
docs/getting-started.md
View File

@ -1 +0,0 @@
# Getting Started (WIP)

59
docs/getting-started/README.md Normal file
View File

@ -0,0 +1,59 @@
# Getting started & FAQ
Use the following docker images:
- `m1k1o/neko:latest` - for Firefox.
- `m1k1o/neko:chromium` - for Chromium (needs `--cap-add=SYS_ADMIN`).
- `m1k1o/neko:google-chrome` - for Google Chrome (needs `--cap-add=SYS_ADMIN`).
- `m1k1o/neko:ungoogled-chromium` - for [Ungoogled Chromium](https://github.com/Eloston/ungoogled-chromium) (needs `--cap-add=SYS_ADMIN`) (by @whalehub).
- `m1k1o/neko:brave` - for [Brave Browser](https://brave.com) (needs `--cap-add=SYS_ADMIN`).
- `m1k1o/neko:tor-browser` - for Tor Browser.
- `m1k1o/neko:vncviewer` - for simple VNC viewer (specify `NEKO_VNC_URL` to your VNC target).
- `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` - for a shared desktop / installing shared software.
- `m1k1o/neko:base` - for custom base.
For ARM-based devices (like Raspberry Pi, with GPU hardware acceleration):
- `m1k1o/neko:arm-firefox` - for Firefox.
- `m1k1o/neko:arm-chromium` - for Chromium.
- `m1k1o/neko:arm-base` - for custom arm based.
Images (except `arm-`) are built using GitHub actions on every push and on weekly basis to keep all browsers up-to-date,
### 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 (see https://github.com/m1k1o/neko/issues/47).
### 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`
### Want to customize and install own add-ons, set custom bookmarks?
- You would need to modify the existing policy file and mount it to your container.
- For Firefox, copy [this](https://github.com/m1k1o/neko/blob/master/.m1k1o/firefox/policies.json) file, modify and mount it as: ` -v '${PWD}/policies.json:/usr/share/firefox-esr/distribution/policies.json'`
- For Chromium, copy [this](https://github.com/m1k1o/neko/blob/master/.m1k1o/chromium/policies.json) file, modify and mount it as: ` -v '${PWD}/policies.json:/etc/chromium/policies/managed/policies.json'`
### Want to use VPN for your n.eko browsing?
- Check this out: https://github.com/m1k1o/neko-vpn
### Want to have multiple rooms on demand?
- Check this out: https://github.com/m1k1o/neko-rooms
### Want to use different Apps than Browser?
- Check this out: https://github.com/m1k1o/neko-apps
### Accounts:
- There are no accounts, display name (a.k.a. username) can be freely chosen. Only password needs to match. Depending on which password matches, the visitor gets its privilege:
- Anyone, who enters with `NEKO_PASSWORD` will be **user**.
- Anyone, who enters with `NEKO_PASSWORD_ADMIN` will be **admin**.
### 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.

118
docs/getting-started/configuration.md Normal file
View File

@ -0,0 +1,118 @@
# Configuration
## 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_EPR:
- For WebRTC needed range of ports
- e.g. 52000-52100
NEKO_VP8:
- If vp8 should be used as video encoder for the stream (default encoder)
- e.g. 'true'
NEKO_VP9:
- If vp9 should be used as video encoder for the stream (Parameter not optimized yet)
- e.g. 'false'
NEKO_H264:
- If h264 should be used as video encoder for the stream (second best option)
- e.g. 'false'
NEKO_VIDEO_BITRATE:
- Bitrate of the video stream in kb/s
- e.g. 3500
NEKO_VIDEO:
- Makes it possible to create custom gstreamer pipelines. 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 '
NEKO_MAX_FPS:
- The resulting stream frames per seconds should be capped (0 for uncapped)
- e.g. 0
NEKO_OPUS:
- If opus should be used as audio encoder for the stream (default encoder)
- e.g. 'true'
NEKO_G722:
- If g722 should be used as audio encoder for the stream
- e.g. 'false'
NEKO_PCMU:
- If pcmu should be used as audio encoder for the stream
- e.g. 'false'
NEKO_PCMA:
- If pcma should be used as audio encoder for the stream
- e.g. 'false'
NEKO_AUDIO_BITRATE:
- Bitrate of the audio stream in kb/s
- e.g. 196
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_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)
```
## Agruments
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)
--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
--cert string path to the SSL cert used to secure the neko server
--device string audio device to capture (default "auto_null.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")
--g722 use G722 audio codec
--h264 use H264 video codec
-h, --help help for serve
--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
--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
--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 use Opus audio codec
--password string password for connecting to stream (default "neko")
--password_admin string admin password for connecting to stream (default "admin")
--pcma use PCMA audio codec
--pcmu use PCMU 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")
--video string video codec parameters to use for streaming
--video_bitrate int video bitrate in kbit/s (default 3072)
--vp8 use VP8 video codec
--vp9 use VP9 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.

108
docs/getting-started/examples.md Normal file
View File

@ -0,0 +1,108 @@
# Examples
## Firefox
```yaml
version: "3.4"
services:
neko:
image: "m1k1o/neko:latest"
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_NAT1TO1: <your-IP>
```
## 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: <your-IP>
```
## VLC
```yaml
version: "3.4"
services:
neko:
image: "m1k1o/neko:vlc"
restart: "unless-stopped"
shm_size: "2gb"
volumes:
- "<your-video-folder>:/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: <your-IP>
```
## Raspberry Pi
Note! Since HW accelerated pipeline is using H264, you are only able to connect from browsers supporting H264 for WebRTC. At the time of implementing, [Firefox does not support this](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/WebRTC_codecs#supported-foot-1). When omitting `NEKO_VIDEO` and `NEKO_H264` parameters, you get default CPU encoding with VP8.
```yaml
version: "3.4"
services:
neko:
image: "m1k1o/neko:arm-chromium"
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=0,video_bitrate=1250000;"
! h264parse config-interval=3
! video/x-h264,profile=baseline,stream-format=byte-stream
NEKO_H264: 1
```
## Not using docker?
You can execute `neko --help` to see available arguments. In [Dockerfile](https://github.com/m1k1o/neko/blob/master/.m1k1o/base/Dockerfile) you can find required dependencies and install them manually.

30
docs/quick-start.md → docs/getting-started/quick-start.md
View File

@ -1,6 +1,6 @@
# Quick Start (WIP)
# Quick Start
1. Deploy a server or VPS
1. Deploy a server or VPS.
**Recommended Specs:**
@ -13,28 +13,34 @@
*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:* changing the resolution will require additional setup
*Note:* Admin can change the resolution in the GUI.
2. [Login via SSH](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/)
2. [Login via SSH](https://www.digitalocean.com/docs/droplets/how-to/connect-with-ssh/).
3. Install Docker
3. Install [Docker](https://docs.docker.com/get-docker/):
```shell
curl -sSL https://get.docker.com/ | CHANNEL=stable bash
```
4. Run these commands:
4. Install [Docker Compose](https://docs.docker.com/compose/install/):
```shell
sudo ufw allow 80/tcp # if you have ufw installed/enabled
sudo ufw allow 59000:59100/udp
wget https://raw.githubusercontent.com/m1k1o/neko/master/.examples/simple/docker-compose.yaml
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
```
5. Visit the IP address server in your browser and login, the default password is `neko`
6. Visit the IP address server in your browser and login, the default password is `neko`.
> 💡 **Protip**: 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)
* [Scaleway](https://www.scaleway.com/)
* [Digital Ocean](https://www.digitalocean.com/)
* [Contabo](https://contabo.com/)
* [Linode](https://www.linode.com/)
* [Vultr](https://www.vultr.com/)
* [Vultr](https://www.vultr.com/)

72
docs/apache-proxypass-config.md → docs/getting-started/reverse-proxy.md
View File

@ -1,13 +1,52 @@
# Using Apache for proxy pass and SSL
# 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, [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, [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```
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 thing might 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.
## Example apache config
```apache
```xml
<VirtualHost *:80>
# The ServerName directive sets the request scheme, hostname and port that
# the server uses to identify itself. This is used when creating
@ -52,9 +91,26 @@ Bear in mind that your neko server doesn't have to run on the same computer as a
</VirtualHost>
```
After creating your new config file, just use ```sudo a2ensite neko.conf``` and then ```sudo systemctl reload apache2```
(by @DarkReaper231, [source](https://github.com/nurdism/neko/blob/cad98a62a5bd7f1daf2c11980631bb14ba81a1f6/docs/apache-proxypass-config.md#example-apache-config))
# Enabling SSL
After creating your new config file, just use `sudo a2ensite neko.conf` and then `sudo systemctl reload apache2`
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.
### 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, [source](https://github.com/nurdism/neko/pull/125/commits/eb4ceda75423b0d960c8aea0240acf6d7a10fef4))

189
docs/getting-started/troubleshooting.md Normal file
View File

@ -0,0 +1,189 @@
# Troubleshooting
Neko UI loads but you don't see the screen and it gives you `connection timeout` or `disconnected` error?
## Test your client
Test whether your cleint can connect to WebRTC here: https://test.webrtc.org/
## Networking
Most problems are networking related.
### 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.
```diff
version: "3.4"
services:
neko:
image: "m1k1o/neko:latest"
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
```
### Validate UDP ports reachability
Ensure, that your ports are reachable through your external IP.
To validate UDP connection the simpliest 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](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.
### 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 conenct to.
```shell
docker-compose logs neko | grep nat_ips
```
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:<nil> CredentialType:password}]" module=webrtc nat_ips=<your-IP>
```
If your IP is not correct, you can specify own IP resover using `NEKO_IPFETCH`. It needs to return IP address that will be used.
```diff
version: "3.4"
services:
neko:
image: "m1k1o/neko:latest"
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
+ NEKO_IPFETCH: https://ifconfig.co/ip
```
Or you can specify your IP address manually using `NEKO_NAT1TO1`:
```diff
version: "3.4"
services:
neko:
image: "m1k1o/neko:latest"
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
+ NEKO_NAT1TO1: <your-IP>
```
If you want to use n.eko only locally, you must put here your local IP address, otherwise public address will be used.
## Debug mode
To see verbose information from n.eko server, you can enable debug mode using `NEKO_DEBUG`.
```diff
version: "3.4"
services:
neko:
image: "m1k1o/neko:latest"
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
+ NEKO_DEBUG: 1
```
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://<your-IP>/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 brwosers.
### 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.

BIN
docs/getting-started/udp-ports-nc.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.4 KiB

1
docs/glossary.md
View File

@ -1 +0,0 @@
# Glossary (WIP)

3
docs/index.html
View File

@ -37,6 +37,7 @@
<script src="//unpkg.com/docsify-copy-code"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-go.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-yaml.min.js"></script>
<script src="//unpkg.com/prismjs/components/prism-diff.min.js"></script>
</body>
</html>

5
docs/mobile-support.md Normal file
View File

@ -0,0 +1,5 @@
# Mobile support
N.eko is now working on iOS and Android! Also, the UI screens have been fixed for small screens.
![mobile-screens](_media/mobile-support.png)

7
docs/non-goals.md
View File

@ -1,5 +1,6 @@
# Non Goals (WIP)
# Non Goals
* Turning n.eko into a service that serves multiple rooms and browsers/desktops.
* Supporting multiple platforms
* Voice chat, use [Discord](https://discordapp.com/)
* For multiple room management software, visit https://github.com/m1k1o/neko-rooms.
* Supporting multiple platforms.
* Voice chat, use [Discord](https://discordapp.com/) or [Jitsi](https://meet.jit.si/).

69
docs/server.md
View File

@ -1,69 +0,0 @@
# Server (WIP)
Server for n.eko, as of right now this will *only* work on Linux systems, only tested on Debian based distros.
## Configuration
------
```
--debug // (bool) enable debug mode
--logs // (bool) save logs to file
--config "" // (string) configuration file path
--bind "127.0.0.1:8080" // (string) address/port/socket to serve neko
--cert "" // (string) path to the SSL cert used to secure the neko server
--key "" // (string) path to the SSL key used to secure the neko server
--static "./www" // (string) path to neko client files to serve
--device "auto_null.monitor" // (string) audio device to capture
--display ":99.0" // (string) XDisplay to capture
--audio "" // (string) audio codec parameters to use for streaming (unused)
--video "" // (string) video codec parameters to use for streaming (unused)
--screen "1280x720@30" // (string) default screen resolution and framerate
--epr "59000-59100" // (string) limits the pool of ephemeral ports that ICE UDP connections can allocate from
--vp8 // (bool) use VP8 video codec
--vp9 // (bool) use VP9 video codec
--h264 // (bool) use H264 video codec
--opus // (bool) use Opus audio codec
--g722 // (bool) use G722 audio codec
--pcmu // (bool) use PCMU audio codec
--pcma // (bool) use PCMA audio codec
--nat1to1 // ([]string) sets a list of external IP addresses of 1:1 (D)NAT and a candidate type for which the external IP address is used
--icelite // (bool) configures whether or not the ice agent should be a lite agent
--iceserver "stun:stun.l.google.com:19302" // ([]string) describes a single STUN and TURN server that can be used by the ICEAgent to establish a connection with a peer
--password "neko" // (string) password for connecting to stream
--password_admin "admin" // (string) admin password for connecting to stream
```
Config can be set via environment variables with the prefix `NEKO_` (I.E. NEKO_BIND="127.0.0.1:8080")
## Requirements
------
Runtime:
```
gstreamer1.0-plugins-base // opus plugin
gstreamer1.0-plugins-good // pulseaudio, ximagesrc & vpx plugins
gstreamer1.0-plugins-bad // openh264 plugin (build from source)
gstreamer1.0-plugins-ugly // x264 plugin
gstreamer1.0-pulseaudio // pulseaudio plugin
xclip // clipboard sync
libxtst6 // keyboard and mouse input
```
Development:
```
libxtst-dev
```
## Testing
------
located in `.docker` folder
```
./test firefox // creates an x server, puleseaudio server add firefox instance
./test chromium // creates an x server, puleseaudio server add chromium instance
```
## Building
------
located in `.docker` folder
```
./build gst // builds the required gst packages in `.build/gst/`
./build docker // builds the docker images
./build push // pushes the images to docker hub
```

2
docs/technologies.md
View File

@ -1 +1 @@
# Technologies (WIP)
# Technologies (WIP)