Setup Guide

Get MediaSurv running on your server with Docker Compose. From zero to streaming in about 10 minutes.

Prerequisites

Before you begin, make sure you have the following installed on your server:

Docker Engine 24+ and Docker Compose v2
A TMDB API key — free at themoviedb.org
A directory containing your media files (movies, TV shows, music)

Supported platforms: Any system that runs Docker — Linux, Windows (WSL2), macOS. MediaSurv is tested on Ubuntu 22.04+, Debian 12, and Windows Server 2022.

Quick Start

1. Clone the repository

    git clone https://github.com/SpasticPalate/MediaSurv.git

    cd MediaSurv

2. Create your environment file

cp .env.example .env

Open .env in your editor and set the required values:

Variable	Required	Description
`POSTGRES_PASSWORD`	Yes	A strong password for the PostgreSQL database
`TMDB_API_KEY`	Yes	Your TMDB v3 API key for metadata lookups
`MEDIA_ROOT`	Yes	Absolute path to your media directory

3. Start the stack

docker compose up -d

This starts all five services: PostgreSQL, Redis, the Go API, the SvelteKit frontend, and nginx.

4. Open MediaSurv

Navigate to http://your-server-ip:3000 in your browser. You should see the MediaSurv dashboard.

5. Add your libraries

Go to Settings, add your library paths (e.g., /media/movies, /media/tv), and click Scan. MediaSurv will index your files and pull metadata from TMDB automatically.

Media Directory Structure

MediaSurv is flexible about directory layout, but the following structure works best:

    /media/

      movies/

        Movie Name (2024)/

          Movie Name (2024).mkv

      tv/

        Show Name/

          Season 01/

            S01E01.mkv

      music/

        Artist/

          Album/

            01 - Track.flac

Supported video formats: MKV, MP4, AVI, M4V, MOV, WMV, TS, M2TS
Supported audio formats: MP3, FLAC, M4A, AAC, OGG, WAV

Environment Variables

Full reference of available configuration options:

Variable	Default	Description
`POSTGRES_PASSWORD`	—	PostgreSQL database password
`TMDB_API_KEY`	—	TMDB v3 API key
`MEDIA_ROOT`	`/media`	Root path for media files inside the container
`ARTWORK_CACHE_DIR`	`/artwork`	Directory for cached artwork and posters
`ENABLE_QSV`	`false`	Enable Intel Quick Sync Video hardware transcoding
`ENABLE_NVENC`	`false`	Enable NVIDIA NVENC hardware transcoding
`RADARR_API_KEY`	—	Radarr API key for webhook integration
`RADARR_WEBHOOK_SECRET`	—	Shared secret for Radarr webhook auth
`SONARR_API_KEY`	—	Sonarr API key for webhook integration
`SONARR_WEBHOOK_SECRET`	—	Shared secret for Sonarr webhook auth

Hardware Transcoding

MediaSurv supports hardware-accelerated transcoding for smoother multi-stream playback.

Intel Quick Sync (QSV)

Set ENABLE_QSV=true in your .env file. Your host must have an Intel CPU with integrated graphics and the appropriate drivers installed. The Docker container will be passed the /dev/dri device automatically.

NVIDIA NVENC

Set ENABLE_NVENC=true in your .env file. You'll also need the NVIDIA Container Toolkit installed on your host.

Note: Software transcoding (CPU-only) works out of the box with no extra configuration. Hardware transcoding is optional and only needed for heavy multi-stream use.

Radarr & Sonarr Integration

MediaSurv can automatically rescan libraries when new media is added via Radarr or Sonarr.

Radarr Setup

In Radarr, go to Settings → Connect → Add → Webhook
Set the URL to http://your-server:3000/api/v1/webhooks/radarr
Add a custom header: X-Webhook-Secret: your-secret-here
Enable the On Import and On Upgrade events

Sonarr Setup

In Sonarr, go to Settings → Connect → Add → Webhook
Set the URL to http://your-server:3000/api/v1/webhooks/sonarr
Add a custom header: X-Webhook-Secret: your-secret-here
Enable the On Import and On Upgrade events

Set the matching RADARR_WEBHOOK_SECRET and SONARR_WEBHOOK_SECRET in your .env file.

Reverse Proxy (Optional)

If you want to expose MediaSurv on a custom domain with HTTPS, put it behind a reverse proxy. Here's an example nginx config:

    # /etc/nginx/sites-available/mediasurv

    server {

      listen 443 ssl http2;

      server_name media.example.com;

      ssl_certificate /etc/letsencrypt/live/media.example.com/fullchain.pem;

      ssl_certificate_key /etc/letsencrypt/live/media.example.com/privkey.pem;

      location / {

        proxy_pass http://127.0.0.1:3000;

        proxy_set_header Host $host;

        proxy_set_header X-Real-IP $remote_addr;

        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_set_header X-Forwarded-Proto $scheme;

      }

    }

Cloudflare Tunnel: If you use Cloudflare Tunnel, point the tunnel to http://localhost:3000 and Cloudflare handles SSL termination for you. No nginx needed.

Troubleshooting

Containers won't start

Run docker compose logs to check for errors. Common causes:

Missing .env file — make sure you copied .env.example
Port 3000 already in use — change the port mapping in compose.yml
Insufficient permissions on the media directory

No metadata appearing

Verify your TMDB_API_KEY is correct
Check the API container logs: docker compose logs api
Ensure your server can reach api.themoviedb.org (no firewall blocks)

Playback buffering

Large files may need transcoding — enable hardware acceleration if available
Check your network bandwidth between server and client
Reduce concurrent streams if CPU usage is high

Health check

Verify your instance is running:

curl http://localhost:3000/api/v1/health

A healthy response returns {"status":"ok"}.

← Back to Home