Skip to content
Klutch.sh Docs

Deploying a Neko Rooms App

Introduction

Neko Rooms is an open-source browser-based remote desktop/streaming solution powered by WebRTC. Deploying Neko Rooms with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for configuration—all managed from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your Neko Rooms Dockerfile (GitHub is the only supported git source)
  • Strong user/admin passwords for room access
  • Optional TURN credentials for improved WebRTC connectivity

For onboarding, see the Quick Start.

Architecture and ports

  • Neko Rooms serves the web interface on internal port 8080; choose HTTP traffic.
  • WebRTC media flows over TCP/UDP. For Klutch.sh, keep TCP port 8080 and ensure TURN is available for better connectivity.
  • Persistent storage is optional for custom configs; mount a volume if you store overrides.

Repository layout

neko-rooms/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets (passwords, TURN credentials) out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t neko-rooms-local .
docker run -p 8080:8080 \
  -e NEKO_PASSWORD=guestpass \
  -e NEKO_ADMIN=adminpass \
  neko-rooms-local

Dockerfile for Neko Rooms (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM ghcr.io/m1k1o/neko:latest


ENV NEKO_PASSWORD=guestpass \
    NEKO_ADMIN=adminpass \
    NEKO_BIND=:8080 \
    NEKO_EPR=52000-52100


EXPOSE 8080
CMD ["neko"]

Notes:

  • Pin the image tag (e.g., ghcr.io/m1k1o/neko:3.2.x) for stability and upgrade intentionally.
  • NEKO_EPR defines the ephemeral port range for media; keep it narrow for firewalling. On Klutch.sh, TURN support is recommended to traverse restrictive networks.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • NEKO_PASSWORD=<guest-password>
  • NEKO_ADMIN=<admin-password>
  • NEKO_BIND=:8080
  • NEKO_EPR=52000-52100 (optional, media port range)
  • Optional TURN: NEKO_TURN_URL, NEKO_TURN_USERNAME, NEKO_TURN_PASSWORD
  • Optional display tweaks: NEKO_SCREEN=1920x1080@60

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=neko

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required) if you persist configs or recordings:

  • /home/neko/.config — custom configuration.
  • /home/neko/recordings — optional recordings if enabled.

Ensure these paths are writable.

Deploy Neko Rooms on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 8080.
  4. Add the environment variables above, including strong admin/guest passwords and any TURN configuration.
  5. Attach persistent volumes for /home/neko/.config (and /home/neko/recordings if used) sized to fit your config and media needs.
  6. Deploy. Access your Neko Rooms instance at https://example-app.klutch.sh and invite users with the configured passwords.

Sample API usage

Check server status (if your build exposes a simple health path):

Terminal window
curl -I https://example-app.klutch.sh/

Join from client JS (socket example depends on your variant):

const socket = io("https://example-app.klutch.sh", { transports: ["websocket"] });
socket.emit("join", { room: "demo-room" });

Health checks and production tips

  • Add an HTTP probe to / for readiness.
  • Enforce HTTPS at the edge; forward internally to port 8080.
  • Use TURN for reliable media; keep TURN secrets in Klutch.sh and rotate them regularly.
  • Monitor resource usage (CPU/GPU if enabled) and media port range; scale as needed.
  • Pin image versions and test upgrades in staging before production.

Neko Rooms on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 8080 configured, and TURN set up, you can deliver secure browser-based remote rooms without extra YAML or workflow overhead.