Documentation

Getting started with Pufferfin

Pufferfin is a media server built on Jellyfin. It plays what you already have and, through your *arr apps, fetches what you don't. This guide takes you from nothing to a working server in a few minutes.

Requirements

• A machine that runs Docker and Docker Compose.
• A folder with your media (movies, shows, books).
• Optional: Radarr, Sonarr, Prowlarr, qBittorrent, Bazarr and Shelfmark, if you want Pufferfin to download for you.

Already using Jellyfin? Pufferfin works the same way, so your habits carry over.

Installation

Create a folder for Pufferfin, then add a docker-compose.yml file inside it:

services:
  pufferfin:
    image: ghcr.io/pufferfin/pufferfin:latest
    container_name: pufferfin
    restart: unless-stopped
    ports:
      - "8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /path/to/media:/media
      - /path/to/downloads:/downloads

Replace /path/to/media and /path/to/downloads with your own folders, then start it:

docker compose up -d

Pufferfin is now running at http://your-server:8096.

First launch

1. Open http://your-server:8096 in your browser.
2. Pick your language and create your admin account.
3. Add a library: choose a type (Movies, Shows, Books) and point it to a folder under /media.
4. Finish the setup and sign in.

Connecting services

Everything is configured from the admin panel. Go to Dashboard → Services, pick a service, and fill in two fields:

• URL: where the service runs, for example http://radarr:7878.
• API key: found in the service's own settings, under General.

Press Test to check the connection, then Save.

ServiceUsed for

RadarrMovies

SonarrShows

ProwlarrIndexers

qBittorrentDownloads

BazarrSubtitles

ShelfmarkBooks and audiobooks

API keys stay on your server. They are never sent back to the interface.

Using Pufferfin

Browse

The home screen shows your library alongside the full catalog. Titles you don't own yet appear next to the ones you do.

Play or download

Open any title. You'll see a single button:

• Play if the title is already in your library.
• Download if it isn't. Pufferfin sends the request to the right service and the title shows up once it's ready.

Navigate

Use your mouse, the arrow keys, or a TV remote. Enter selects, Esc goes back.

Updating

From your Pufferfin folder, pull the new image and restart:

docker compose pull
docker compose up -d

Your settings and library are kept in ./config, so nothing is lost.

Getting help

Stuck, or found a bug? We're happy to help.