Archived

This repository has been archived on 2024-06-24. You can view files and clone it, but cannot push or open issues or pull requests.

History

Bad d2765c30fd readd -> read		2023-03-19 18:13:06 +01:00
..
configuration.md	readd -> read	2023-03-19 18:13:06 +01:00
examples.md	codecs from string not bools.	2022-09-17 18:37:30 +02:00
quick-start.md	update readme.	2022-12-22 21:40:31 +01:00
README.md	add gpu acceleration to docs.	2023-03-17 19:04:57 +01:00
reverse-proxy.md	docs - fix typos	2023-03-02 19:47:39 +01:00
troubleshooting.md	docs - fix typos	2023-03-02 19:47:39 +01:00
udp-ports-nc.png	update docs #95 .	2021-10-23 15:54:58 +02:00

README.md

Getting started & FAQ

Use the following docker images from Docker Hub 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).
m1k1o/neko:google-chrome - for Google Chrome (needs --cap-add=SYS_ADMIN, see the security implications).
m1k1o/neko:ungoogled-chromium - for Ungoogled Chromium (needs --cap-add=SYS_ADMIN, see the security implications) (by @whalehub).
m1k1o/neko:microsoft-edge - for Microsoft Edge (needs --cap-add=SYS_ADMIN, see the security implications).
m1k1o/neko:brave - for Brave Browser (needs --cap-add=SYS_ADMIN, see the security implications).
m1k1o/neko:vivaldi - for Vivaldi Browser (needs --cap-add=SYS_ADMIN, see the security implications) (by @Xeddius).
m1k1o/neko:opera for Opera Browser (requires extra steps to enable DRM, see instructions here. 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=<proto>://[<username>[:<password>]@]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=<path_to_profile.remmina>.
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 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.

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 use:

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.

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

Using mux instead of epr

When using a mux, not so many ports are needed.

version: "3.4"
services:
  neko:
    image: "m1k1o/neko:firefox"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "8080:8080"
      - "8081:8081/tcp"
      - "8082:8082/udp"
    environment:
      NEKO_SCREEN: 1920x1080@30
      NEKO_PASSWORD: neko
      NEKO_PASSWORD_ADMIN: admin
      NEKO_TCPMUX: 8081
      NEKO_UDPMUX: 8082
      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.

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 file, modify and mount it as: -v '${PWD}/policies.json:/usr/lib/firefox/distribution/policies.json'
For Chromium, copy this file, modify and mount it as: -v '${PWD}/policies.json:/etc/chromium/policies/managed/policies.json'
For others, see where existing policies.json is placed in their Dockerfile.

Allow file uploading & downloading

From security perspective, browser is not enabled to access local file data.
If you want to enable this, you need to modify following policies:

  "DownloadRestrictions": 0,
  "AllowFileSelectionDialogs": true,
  "URLAllowlist": [
      "file:///home/neko/Downloads"
  ],

Want to preserve browser data between restarts?

You need to mount browser profile as volume.
For Firefox, that is this /home/neko/.mozilla/firefox/profile.default folder, mount it as: -v '${PWD}/data:/home/neko/.mozilla/firefox/profile.default'
For Chromium, that is this /home/neko/.config/chromium folder, mount it as: -v '${PWD}/data:/home/neko/.config/chromium'
For other chromium based browsers, see in supervisord.conf folder that is specified in --user-data-dir.

Allow persistent data in policies

From security perspective, browser is set up to forget all cookies and browsing history when its closed.
If you want to enable this, you need to modify following policies:

  "DefaultCookiesSetting": 1,
  "RestoreOnStartup": 1,

Nvidia GPU acceleration

You need to have nvidia-docker installed, start the container with --gpus all flag and use images built for nvidia (see above).

docker run -d --gpus all \
  -p 8080:8080 \
  -p 56000-56100:56000-56100/udp \
  -e NEKO_SCREEN=1920x1080@30 \
  -e NEKO_PASSWORD=neko \
  -e NEKO_PASSWORD_ADMIN=admin \
  -e NEKO_EPR=56000-56100 \
  -e NEKO_NAT1TO1=192.168.1.10 \
  -e NEKO_ICELITE=1 \
  --shm-size=2gb \
  --cap-add=SYS_ADMIN \
  --name neko \
  ghcr.io/m1k1o/neko/nvidia-google-chrome:latest

If you want to use docker-compose, you can use this example:

version: "3.4"
services:
  neko:
    image: "ghcr.io/m1k1o/neko/nvidia-google-chrome:latest"
    restart: "unless-stopped"
    shm_size: "2gb"
    ports:
      - "8080:8080"
      - "56000-56100:56000-56100/udp"
    cap_add:
      - SYS_ADMIN
    environment:
      NEKO_SCREEN: '1920x1080@30'
      NEKO_PASSWORD: neko
      NEKO_PASSWORD_ADMIN: admin
      NEKO_EPR: 56000-56100
      NEKO_NAT1TO1: 192.168.1.10
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Note, currently only browser GPU acceleration is supported, not encoding.

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.
Disabling passwords is not possible. However, you can use following query parameters to create auto-join links:
- Adding ?pwd=<password> will prefill password.
- Adding ?usr=<display-name> will prefill username.
- Adding ?cast=1 will hide all control and show only video.
- e.g. http(s)://<URL:Port>/?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.

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.