Migrations/neko
1
0
Fork 0
mirror of https://github.com/m1k1o/neko.git synced 2026-11-03 00:11:48 -06:00
Code Issues Packages Projects Releases Wiki Activity

Add example Docker Compose configurations for Neko (#684)

Browse Source 
* Add example Docker Compose configurations for Neko

- Introduced a simple browser example using Firefox in Docker with optional persistent profile configuration.
- Added a TURN server example using Coturn alongside Neko for WebRTC support.
- Updated installation documentation to include new examples and improved organization.
- Enhanced Docusaurus configuration to support dynamic code imports for example files.
- Updated package dependencies to include remark-code-import for better documentation handling.

* feat: rename GPU-accelerated browser examples for Intel and Nvidia.

* feat: update GPU browser examples and add OAuth configuration example

* feat: add Raspberry Pi GPU browser example and update documentation links

* feat: update GPU browser examples section for clarity and organization
This commit is contained in:
Miroslav Šedivý
2026-09-27 17:13:20 +02:00
committed by GitHub
parent f4d632df2c
commit 3f4f94087a
16 changed files with 838 additions and 367 deletions
Download Patch File Download Diff File Expand all files Collapse all files
examples/README.md
+17
View File
@@ -0,0 +1,17 @@
# Examples
Ready-to-use [Docker Compose](https://docs.docker.com/compose/) configurations for Neko. Each folder is self-contained and can be copied out and run on its own with `docker compose up`. All files are heavily commented, showing available options and linking to the relevant documentation inline.
These are the same examples shown in the [documentation](https://neko.m1k1o.net/docs/v3/installation/examples), kept here so they can be browsed, cloned or downloaded directly from the repository.
| Example | Description |
| --- | --- |
| [simple-browser](./simple-browser) | Firefox with commented options for persistent/custom profiles and other available browser images. |
| [kiosk-browser](./kiosk-browser) | Firefox in kiosk mode that opens a fixed URL on startup (e.g. a streaming service or dashboard). Stateless by default. |
| [oauth](./oauth) | Firefox authenticating members through an external OAuth 2.0 / OpenID Connect provider, configured via a mounted config.yaml. |
| [gpu-nvidia-browser](./gpu-nvidia-browser) | Firefox with Nvidia GPU acceleration, with a commented "encode-only" option. |
| [gpu-intel-browser](./gpu-intel-browser) | Firefox with Intel (VAAPI) GPU acceleration, with a commented "encode-only" option. |
| [gpu-raspberry-pi-browser](./gpu-raspberry-pi-browser) | Firefox tuned for Raspberry Pi, with a commented hardware-encoding option. |
| [arm64-browser](./arm64-browser) | Firefox on generic ARM64 hosts, with links to DRM setup and GPU acceleration options. |
| [turn-server](./turn-server) | A Coturn TURN server running alongside Neko for WebRTC NAT traversal. |
examples/arm64-browser/docker-compose.yaml
+33
View File
@@ -0,0 +1,33 @@
# Neko - ARM64 Browser Example
#
# Runs Firefox on a generic ARM64 host (e.g. Apple M1/M2 under virtualization,
# AWS Graviton, Oracle Cloud ARM free tier). The same multi-arch image used
# on amd64 works here - no special image tag is required.
#
# See supported architectures and per-app availability:
# https://neko.m1k1o.net/docs/v3/installation/docker-images#availability
services:
neko:
image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
shm_size: "2gb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
environment:
NEKO_DESKTOP_SCREEN: '1920x1080@30'
NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#nat1to1
# NEKO_WEBRTC_NAT1TO1: <your-IP>
# DRM (Widevine) support is limited on ARM64 and needs extra setup for
# protected streaming content:
# See: https://neko.m1k1o.net/docs/v3/customization/browsers#arm64-drm
# GPU ACCELERATION OPTION: if your ARM64 device exposes a V4L2 M2M
# hardware encoder (common on SBCs like Raspberry Pi), reuse the same
# pipeline as in the Raspberry Pi example:
# https://github.com/m1k1o/neko/tree/main/examples/gpu-raspberry-pi-browser
examples/gpu-intel-browser/docker-compose.yaml
+35
View File
@@ -0,0 +1,35 @@
# Neko - Intel Browser Example
#
# Runs Firefox with Intel GPU hardware acceleration (VAAPI) for both browser
# rendering and video encoding. Requires the host to expose /dev/dri and have
# the Intel graphics driver installed.
#
# Other GPU-accelerated flavors are listed here:
# https://neko.m1k1o.net/docs/v3/installation/docker-images#intel
services:
neko:
image: "ghcr.io/m1k1o/neko/intel-firefox:latest"
# ENCODE-ONLY OPTION: if you only want to accelerate video encoding, not
# the browser rendering, use the plain firefox image instead:
# image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
shm_size: "2gb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
devices:
# Required for VAAPI hardware acceleration - gives the container access
# to the GPU's render node. The render group is detected automatically.
- "/dev/dri:/dev/dri"
environment:
# The intel-firefox image already sets NEKO_HWENC=vaapi by default.
# Uncomment to be explicit, or when using the plain firefox image above
# for encode-only acceleration:
# NEKO_HWENC: "vaapi"
NEKO_DESKTOP_SCREEN: '1920x1080@30'
NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#nat1to1
# NEKO_WEBRTC_NAT1TO1: <your-IP>
examples/gpu-nvidia-browser/docker-compose.yaml
+86
View File
@@ -0,0 +1,86 @@
# Neko - Nvidia Browser Example
#
# Runs Firefox with full Nvidia GPU acceleration (both browser rendering and
# video encoding) using CUDA. Requires the Nvidia Container Toolkit:
# https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html
#
# Check if your GPU supports hardware encoding:
# https://developer.nvidia.com/video-encode-decode-gpu-support-matrix
#
# Other GPU-accelerated flavors are listed here:
# https://neko.m1k1o.net/docs/v3/installation/docker-images#nvidia
services:
neko:
image: "ghcr.io/m1k1o/neko/nvidia-firefox:latest"
# ENCODE-ONLY OPTION: if you only want to accelerate video encoding, not
# the browser rendering, use the plain firefox image instead - see the
# matching commented pipeline/env vars further down.
# image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
shm_size: "2gb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
environment:
# ENCODE-ONLY OPTION: uncomment these two when using the plain firefox
# image above, so the container can still see the GPU for encoding.
# NVIDIA_VISIBLE_DEVICES: all
# NVIDIA_DRIVER_CAPABILITIES: all
# `nvautogpuh264enc` (GStreamer 1.22+) is recommended for NVIDIA driver
# 590+; it auto-selects CUDA or system memory. On older drivers or
# GStreamer versions, use `nvh264enc` instead. If your GPU does not
# support CUDA, drop `cudaupload`/`cudaconvert` below (see the
# ENCODE-ONLY pipeline further down for that variant).
NEKO_CAPTURE_VIDEO_PIPELINE: |
ximagesrc display-name={display} show-pointer=true use-damage=false
! video/x-raw,framerate=25/1
! cudaupload ! cudaconvert ! queue
! video/x-raw(memory:CUDAMemory),format=NV12
! nvautogpuh264enc
name=encoder
preset=2
gop-size=25
spatial-aq=true
temporal-aq=true
bitrate=4096
vbv-buffer-size=4096
rc-mode=6
! h264parse config-interval=-1
! video/x-h264,stream-format=byte-stream
! appsink name=appsink
# ENCODE-ONLY OPTION: replace the active pipeline above with this one
# when using the plain "firefox" image - it swaps cudaupload/cudaconvert
# for a plain videoconvert, since the browser itself no longer needs CUDA:
# NEKO_CAPTURE_VIDEO_PIPELINE: |
# ximagesrc display-name={display} show-pointer=true use-damage=false
# ! video/x-raw,framerate=25/1
# ! videoconvert ! queue
# ! video/x-raw,format=NV12
# ! nvautogpuh264enc
# name=encoder
# preset=2
# gop-size=25
# spatial-aq=true
# temporal-aq=true
# bitrate=4096
# vbv-buffer-size=4096
# rc-mode=6
# ! h264parse config-interval=-1
# ! video/x-h264,stream-format=byte-stream
# ! appsink name=appsink
NEKO_CAPTURE_VIDEO_CODEC: "h264"
NEKO_DESKTOP_SCREEN: 1920x1080@30
NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#nat1to1
# NEKO_WEBRTC_NAT1TO1: <your-IP>
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
examples/gpu-raspberry-pi-browser/docker-compose.yaml
+43
View File
@@ -0,0 +1,43 @@
# Neko - Raspberry Pi Browser Example
#
# Runs Firefox on a Raspberry Pi (or similar ARM SBC). Works out of the box
# with software rendering/encoding; see below for optional hardware-
# accelerated encoding on boards with a V4L2 M2M encoder (e.g. Pi 3/4).
#
# See supported architectures and known caveats:
# https://neko.m1k1o.net/docs/v3/installation/docker-images#availability
services:
neko:
image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
# increase on Pi's with more than 1gb ram.
shm_size: "520mb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
# note: required for the GPU ACCELERATION OPTION below, alternatively
# mount the specific /dev/video* devices instead of running privileged.
# privileged: true
environment:
# GPU ACCELERATION OPTION: enable hardware encoding via the Broadcom
# VideoCore V4L2 M2M encoder (available on Raspberry Pi 3/4, not Pi 5).
# Requires `privileged: true` above (or the matching /dev/video* devices).
# NEKO_CAPTURE_VIDEO_PIPELINE: |
# ximagesrc display-name={display} show-pointer=true use-damage=false
# ! video/x-raw,framerate=25/1
# ! videoconvert ! queue
# ! video/x-raw,format=NV12
# ! v4l2h264enc
# name=encoder
# extra-controls="controls,h264_profile=1,video_bitrate=1250000;"
# ! h264parse config-interval=-1
# ! video/x-h264,stream-format=byte-stream
# ! appsink name=appsink
# NEKO_CAPTURE_VIDEO_CODEC: "h264"
NEKO_DESKTOP_SCREEN: '1280x720@30'
NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#nat1to1
# NEKO_WEBRTC_NAT1TO1: <your-IP>
examples/kiosk-browser/docker-compose.yaml
+34
View File
@@ -0,0 +1,34 @@
# Neko - Kiosk Browser Example
#
# Runs Firefox in kiosk mode (no address bar, tabs or browser chrome) and
# opens a fixed URL automatically on startup. Useful for turning a smart
# display, thin client or dedicated terminal into an app-like experience.
#
# This works by overriding the Firefox supervisor command, see ./firefox.conf
# and the Supervisord Configuration docs:
# https://neko.m1k1o.net/docs/v3/customization#supervisord
services:
neko:
image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
shm_size: "2gb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
volumes:
- "./firefox.conf:/etc/neko/supervisord/firefox.conf:ro"
# NOTE: this setup is intentionally stateless - no profile is persisted,
# so cookies and logins are lost every time the container restarts. If
# you want the kiosk session to stay logged in across restarts, mount a
# persistent profile directory as well:
# See: https://neko.m1k1o.net/docs/v3/customization/browsers#persistent-profile
# - "./profile:/home/neko/.mozilla/firefox/profile.default"
environment:
NEKO_DESKTOP_SCREEN: '1280x720@30'
NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#nat1to1
# NEKO_WEBRTC_NAT1TO1: <your-IP>
examples/kiosk-browser/firefox.conf
+13
View File
@@ -0,0 +1,13 @@
[program:firefox]
environment=HOME="/home/%(ENV_USER)s",USER="%(ENV_USER)s",DISPLAY="%(ENV_DISPLAY)s"
; Replace <YOUR-KIOSK-URL> with the page to open automatically on startup,
; e.g. https://www.disneyplus.com/ for a dedicated streaming kiosk.
command=/usr/bin/firefox --kiosk --no-remote -P default --display=%(ENV_DISPLAY)s -setDefaultBrowser -width 1280 -height 720 <YOUR-KIOSK-URL>
stopsignal=INT
autorestart=true
priority=800
user=%(ENV_USER)s
stdout_logfile=/var/log/neko/firefox.log
stdout_logfile_maxbytes=100MB
stdout_logfile_backups=10
redirect_stderr=true
examples/oauth/config.yaml
+42
View File
@@ -0,0 +1,42 @@
# See: https://neko.m1k1o.net/docs/v3/configuration/authentication#member.oauth
member:
provider: "oauth"
oauth:
enabled: true
# When true, visiting the Neko root page immediately starts OAuth login.
auto_redirect: true
name: "Example SSO"
admin_emails: ["admin@example.com"]
user_emails: [] # if empty, any authenticated user is allowed to log in
client_id: "<client-id>"
client_secret: "<client-secret>"
# For OpenID Connect providers, issuer_url alone is enough - Neko
# discovers the authorization, token and user-info endpoints from
# /.well-known/openid-configuration.
issuer_url: "https://id.example.com"
scopes: ["openid", "profile", "email"]
# Configure these to match the JSON returned by the user-info endpoint.
subject_field: "sub"
username_field: "name"
avatar_field: "picture"
success_redirect: "/"
user_profile:
is_admin: false
can_login: true
can_connect: true
can_watch: true
can_host: true
can_share_media: true
can_access_clipboard: true
sends_inactive_cursor: true
can_see_inactive_cursors: false
admin_profile:
is_admin: true
can_login: true
can_connect: true
can_watch: true
can_host: true
can_share_media: true
can_access_clipboard: true
sends_inactive_cursor: true
can_see_inactive_cursors: true
examples/oauth/docker-compose.yaml
+23
View File
@@ -0,0 +1,23 @@
# Neko - OAuth Example
#
# Authenticates users via an external OAuth 2.0 / OpenID Connect provider
# instead of the built-in multiuser passwords. OAuth has many settings, so
# they are set via a mounted config.yaml instead of environment variables.
#
# See: https://neko.m1k1o.net/docs/v3/configuration/authentication#member.oauth
services:
neko:
image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
shm_size: "2gb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
volumes:
- "./config.yaml:/etc/neko/neko.yaml"
environment:
NEKO_DESKTOP_SCREEN: '1920x1080@30'
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#nat1to1
# NEKO_WEBRTC_NAT1TO1: <your-IP>
examples/simple-browser/docker-compose.yaml
+39
View File
@@ -0,0 +1,39 @@
# Neko - Simple Browser Example
#
# Runs Firefox in Neko. Firefox is the default, most tested image, but Neko
# supports many other browsers and applications - see the full list here:
# https://neko.m1k1o.net/docs/v3/installation/docker-images#apps
#
# Other browser images you can swap in below:
# ghcr.io/m1k1o/neko/chromium
# ghcr.io/m1k1o/neko/google-chrome
# ghcr.io/m1k1o/neko/brave
# ghcr.io/m1k1o/neko/vivaldi
# ghcr.io/m1k1o/neko/microsoft-edge
# ghcr.io/m1k1o/neko/tor-browser
# ghcr.io/m1k1o/neko/waterfox
services:
neko:
image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
shm_size: "2gb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
# volumes:
# Persist Firefox settings, bookmarks, extensions and history across
# container restarts by mounting the profile directory.
# See: https://neko.m1k1o.net/docs/v3/customization/browsers#persistent-profile
# - "./profile:/home/neko/.mozilla/firefox/profile.default"
# Or mount your own pre-configured Firefox profile instead of an empty one.
# See: https://neko.m1k1o.net/docs/v3/customization/browsers#persistent-profile
# - "./my-custom-profile:/home/neko/.mozilla/firefox/profile.default"
environment:
NEKO_DESKTOP_SCREEN: '1920x1080@30'
NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#nat1to1
# NEKO_WEBRTC_NAT1TO1: <your-IP>
examples/turn-server/docker-compose.yaml
+52
View File
@@ -0,0 +1,52 @@
# Neko - TURN Server Example
#
# WebRTC needs a direct connection between the client and the server. When
# that is not possible (e.g. both sides are behind restrictive NATs or
# firewalls), a TURN server relays the traffic instead. This example runs a
# Coturn TURN server alongside Neko.
#
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#iceservers
services:
neko:
image: "ghcr.io/m1k1o/neko/firefox:latest"
restart: "unless-stopped"
shm_size: "2gb"
ports:
- "8080:8080"
- "52000-52100:52000-52100/udp"
environment:
NEKO_DESKTOP_SCREEN: '1920x1080@30'
NEKO_MEMBER_MULTIUSER_USER_PASSWORD: neko
NEKO_MEMBER_MULTIUSER_ADMIN_PASSWORD: admin
NEKO_WEBRTC_EPR: 52000-52100
NEKO_WEBRTC_ICELITE: 1
# Tell the client to use the TURN server below as a fallback ICE
# server. Replace <MY-COTURN-SERVER> with the LAN or public IP address
# the TURN server is reachable at, matching the coturn service below.
# See: https://neko.m1k1o.net/docs/v3/configuration/webrtc#iceservers
NEKO_WEBRTC_ICESERVERS_FRONTEND: |
[{
"urls": [ "turn:<MY-COTURN-SERVER>:3478" ],
"username": "neko",
"credential": "neko"
}]
coturn:
image: "coturn/coturn:latest"
restart: "unless-stopped"
network_mode: "host"
command: |
-n
--realm=localhost
--fingerprint
--listening-ip=0.0.0.0
--external-ip=<MY-COTURN-SERVER>
--listening-port=3478
--min-port=49160
--max-port=49200
--log-file=stdout
--user=neko:neko
--lt-cred-mech
# Replace <MY-COTURN-SERVER> above with your LAN or Public IP address.
# Open ports 3478/tcp (control) and 49160-49200/udp (relay) on your
# firewall. More info: https://github.com/coturn/coturn