Self-Host with Docker
RecommendedThe fastest way to get Tentacle TV running. Copy, paste, done.
Includes MariaDB + Tentacle TV in a single stack:
services:
db:
image: mariadb:11
container_name: tentacle-db
restart: unless-stopped
environment:
MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
MYSQL_DATABASE: tentacle_db
MYSQL_USER: tentacle_user
MYSQL_PASSWORD: ${MYSQL_PASSWORD}
volumes:
- tentacle-db-data:/var/lib/mysql
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 5
web:
image: ghcr.io/knaox/tentacle-tv:latest
container_name: tentacle-tv
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
DATABASE_URL: mysql://tentacle_user:${MYSQL_PASSWORD}@db:3306/tentacle_db
JWT_SECRET: ${JWT_SECRET}
PORT: "3000"
HOST: "0.0.0.0"
volumes:
- tentacle-data:/app/apps/backend/data
ports:
- "3000:3000"
volumes:
tentacle-db-data:
tentacle-data:
docker compose up -dAlready have a MariaDB/MySQL instance? Use this minimal config:
services:
web:
image: ghcr.io/knaox/tentacle-tv:latest
container_name: tentacle-tv
restart: unless-stopped
environment:
JWT_SECRET: ${JWT_SECRET}
PORT: "3000"
HOST: "0.0.0.0"
volumes:
- tentacle-data:/app/apps/backend/data
ports:
- "3000:3000"
volumes:
tentacle-data:
docker compose -f docker-compose.external.yml up -dFirst launch: Open
http://your-server:3000 — the setup wizard guides you through database, Jellyfin connection, and admin account creation.Configuration
| Variable | Description | Default |
|---|---|---|
DATABASE_URL | MariaDB connection string | — |
JWT_SECRET | Secret key for token signing | — |
PORT | Server listening port | 3000 |
HOST | Server bind address | 0.0.0.0 |
RATE_LIMIT | Max requests/min per IP | 1000 |
Jellyfin URL and API key are configured through the web setup wizard and stored in the database.
Architecture
Tentacle Backend
/api/*
Auth, invites, tickets, config, pairing, plugins
Jellyfin Proxy
/api/jellyfin/*
Streaming, media browsing, user data via backend proxy
| Layer | Technology |
|---|---|
| Web | React 19, Vite 6, Tailwind CSS, Framer Motion |
| Desktop | Electron (Windows, macOS) · Tauri v2 (Linux), native mpv player |
| Mobile | React Native 0.76, Expo 52, NativeWind |
| TV | React Native — ExoPlayer/Media3 (Android TV), AVPlayer (tvOS) |
| Backend | Fastify 5, Prisma 6, MariaDB 11 |
| Data | TanStack Query v5 |
| Video | hls.js (web), mpv (desktop), react-native-video |
| Language | TypeScript 5.7, strict mode |