About lunarr-go

Lunarr-go is a self-hosted web media server designed as a lightweight alternative to Plex for managing movie and TV show libraries on headless servers. It supports both local file systems and SFTP remote storage, enabling users to access media from anywhere. The application automatically scans folders, identifies content, and enriches it with metadata from The Movie Database. It offers flexible playback options including direct streaming for compatible files and temporary HLS transcoding for unsupported formats, with a web-based interface accessible from any browser. Key features include support for common video extensions like MP4, MKV, and AVI, automatic detection of VTT subtitle files, and robust directory layout recognition for TV shows. Administrators have control over user accounts, library sharing permissions, and system settings. The software is container-ready with Docker support, requiring only an authentication secret and data volume for deployment. It includes background job management for schedul

l

Published by

lunarr-app

Visit View Profile

README.md

View on GitHub

Lunarr

Lunarr is a self-hosted web media server for local and SFTP movie and TV libraries. It scans folders, matches media with TMDb metadata, and plays files in the browser with direct streaming or temporary HLS transcoding.

Draft screenshot

Quick Start With Docker

Run Lunarr with persistent app data:

docker run -d \
  --name lunarr \
  --restart unless-stopped \
  -p 3000:3000 \
  -e AUTH_SECRET=replace-with-a-random-secret-at-least-32-chars \
  -e ORIGIN=http://127.0.0.1:3000 \
  -v lunarr-data:/data \
  sayem314/lunarr:latest

For local media libraries, mount your media into the container and add the container path in Lunarr:

docker run -d \
  --name lunarr \
  --restart unless-stopped \
  -p 3000:3000 \
  -e AUTH_SECRET=replace-with-a-random-secret-at-least-32-chars \
  -e ORIGIN=http://127.0.0.1:3000 \
  -v lunarr-data:/data \
  -v /mnt/media:/media:ro \
  sayem314/lunarr:latest

Open http://127.0.0.1:3000, create the first admin account, add a movie or TV library, then run a scan from Libraries.

Docker Compose users can start from docker-compose.yml.

Local Development

Install dependencies and create a local environment file:

bun install
cp .env.example .env

Set AUTH_SECRET in .env to a stable random value with at least 32 characters, then start the dev server:

bun run dev

Open http://127.0.0.1:5173, create the first admin account, add a library, and scan it.

First Scan

Lunarr supports local and SFTP libraries. Local libraries can watch file changes, and both local and SFTP libraries can use scheduled rescans. Manual scans are always available from Libraries.

Common TV layouts:

Show Name/Season 01/Show Name - S01E02 - Episode Title.mkv
Show.Name.S01E02.mkv
Show Name/Show Name 1x02.mkv
Show Name/Season 1/02 - Episode Title.mkv
Show Name/Specials/S00E01.mkv

Supported video extensions are .mp4, .mkv, .mov, .avi, and .webm. Sidecar .vtt subtitles are detected during scans.

Documentation

Getting Started: first-run setup, TMDb, adding libraries, and scanning.
Configuration: environment variables, Docker, data storage, and production start.
Libraries: local and SFTP behavior, watchers, scheduled rescans, and remote tuning.
Playback And Maintenance: direct play, HLS, transcode cache, cleanup, and job history retention.
API: authenticated JSON APIs and API-key usage.
NodeAV Transcoding Runtime: deeper transcoding implementation notes.

Verification

bun run check
bun run build
bun test
bun run smoke:transcode

To verify live TMDb connectivity and poster metadata once credentials are configured:

bun run verify:tmdb

Notes

The first registered user becomes admin.
Later signup is disabled by default unless an admin enables it in Settings.
AUTH_SECRET must stay stable between restarts.
LUNARR_DATA_DIR stores the SQLite database and temporary playback artifacts; keep it on persistent storage.
Admins can share each library with all users or only selected regular users.
Raw library paths, scan errors, jobs, users, and settings are admin-only.

lunarr-go