How to Deploy Jellyfin on a VPS

#Install Jellyfin (Docker Compose)

The official image is jellyfin/jellyfin. Upstream's compose example runs the server as a specific uid:gid instead of root, keeps /config and /cache on persistent storage, and bind-mounts the media. Record your user's IDs in a .env file so the compose file doesn't hard-code them:

copymkdir -p ~/jellyfin && cd ~/jellyfin
mkdir -p config cache
printf 'PUID=%s\nPGID=%s\n' "$(id -u)" "$(id -g)" > .env

copycd ~/jellyfin
cat > docker-compose.yml <<'YAML'
services:
  jellyfin:
    image: jellyfin/jellyfin
    container_name: jellyfin
    user: "${PUID}:${PGID}"
    ports:
      # Loopback only — Caddy is the sole route in from outside.
      - "127.0.0.1:8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - type: bind
        source: /srv/media
        target: /media
        read_only: true
    restart: unless-stopped
YAML
docker compose up -d

Two deliberate differences from the upstream example:

• No 7359/udp port. That port is for client auto-discovery on a local network. A VPS isn't on your LAN, so there is nothing for it to discover.
• Media mounted read-only. Jellyfin only needs to read your library. If you later want it to write artwork or subtitles next to the files, drop read_only: true.

Wait for the server to answer and check the container is healthy:

copycd ~/jellyfin
for i in $(seq 1 60); do curl -fsS -o /dev/null http://127.0.0.1:8096/ && break; sleep 2; done
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8096/
docker compose ps

A 302 (a redirect to the web UI) means Jellyfin is up.

#HTTPS + domain

Point an A record for media.example.com at the server's public IP and wait for it to resolve. Then put Caddy in front — see Automatic HTTPS with Caddy for the full setup. Jellyfin's own reverse-proxy documentation gives the Caddyfile as a single block:

media.example.com {
    reverse_proxy 127.0.0.1:8096
}

Caddy obtains and renews the certificate and passes WebSocket connections through without extra configuration. If you run Caddy as a container, 127.0.0.1 is the proxy's own loopback — put both services in one compose file and use reverse_proxy jellyfin:8096 instead.

If you'd rather serve Jellyfin under a path such as example.com/jellyfin, set Base URL under Admin → Networking first, then proxy only that path. A dedicated subdomain is simpler and is what the client apps expect by default.

#First run: the setup wizard

Open https://media.example.com. The first visit starts Jellyfin's setup wizard, which asks for a display language, then creates the administrator account, then offers to add libraries. Do this straight away — until the wizard is finished, anyone who reaches the URL can claim the server.

When adding libraries, pick the content type (Movies, Shows, Music) and point each at its folder under /media — /media/movies, /media/shows, /media/music. The path is the one inside the container, not /srv/media.

#Securing it

• Keep the admin separate. Create a normal user for day-to-day watching and keep the administrator account for administration.
• Leave the port on loopback. The compose file above never publishes 8096 to the internet; everything goes through HTTPS.
• Check who is signed in. Dashboard → Devices and the activity log show which clients have sessions; revoke anything you don't recognise.
• Don't expose an unfinished wizard. If you install now and configure later, keep the firewall closed until the admin account exists.

#Backups

Jellyfin's state — users, watch history, library database, metadata — lives in ./config. The media itself is yours to back up separately. Upstream's guidance for a manual backup is to stop the server first, because a copy of a database in use may not restore:

copycd ~/jellyfin
docker compose stop
tar czf jellyfin-config-$(date +%F).tar.gz config docker-compose.yml .env
docker compose start

./cache holds transcodes and image caches that Jellyfin regenerates, so it doesn't need backing up. Current versions also have a built-in backup under Dashboard → Backups, which writes a zip into config/data/backups — handy, but it is still on the same disk, so copy archives off the box either way. Restoring means putting config back in place, then starting the container on the same Jellyfin version the backup came from.

#Upgrades

copycd ~/jellyfin
docker compose pull
docker compose up -d

The image tag tracks the latest stable release, and database migrations run on startup. Back up config first — migrations are one-way, and a backup restores cleanly only on the version that made it. Read the release notes before a major version jump.

#Troubleshooting

Libraries stay empty. The container user can't read the folders, or the library points at the host path. Libraries must use the container path (/media/...), and ls -ln /srv/media should show the IDs from .env, or permissions that let them read.

Playback buffers and the CPU sits at 100%. You're transcoding on the CPU. The Dashboard's active-sessions view shows each stream's play method: if it says Transcoding, set the client to the original quality, or store the file in a format the client plays directly.

The container restarts in a loop. Read the log:

copycd ~/jellyfin
docker compose logs --tail 50 jellyfin

A permissions error on /config or /cache means those folders aren't owned by the IDs in .env — sudo chown -R $(id -u):$(id -g) ~/jellyfin/config ~/jellyfin/cache fixes it.

Apps can't connect through the domain. Test that the proxy answers with curl -I https://media.example.com from another machine. A certificate error means DNS didn't point at the box when Caddy asked for the certificate.

#Verification + next steps

You're done when you can load https://media.example.com over a valid certificate, sign in as a non-admin user, play a film in a browser and on a phone, and see Direct Play rather than Transcoding in the Dashboard's active sessions for your usual clients.

From there, automate the library: Sonarr for TV and Radarr for films. For music, a dedicated server such as Navidrome is lighter than a full media server, and Audiobookshelf handles audiobooks and podcasts with progress sync.