Can I self-host Plex?

294 lines · 13,667 bytes

You are Claude Code on the user's machine. The user has completed Prompt Zero: `ssh vps` works,
Docker and Caddy are installed, the firewall is default-deny.

Run every command in this prompt on the server over `ssh vps` unless the step says otherwise.

Install Jellyfin 10.10.7 on that server, reachable at https://<DOMAIN>, behind the existing
Caddy with automatic TLS.

## 1. Preflight

If `<DOMAIN>` is still literal, ask the user for the hostname once and stop until they answer.
Its A record must already point at this server.

Say three things before anything installs, because they decide whether this is the right box.
One: Jellyfin streams files the user already owns. There is no catalogue, no store, and nothing
to search that they have not copied onto a disk. Two: a home box with the library on the same
LAN is the usual shape; a VPS is a remote front door, and every remote stream burns that
provider's egress quota the way a Netflix bill would. Three: between first start and the end of
the setup wizard, anyone who can reach the hostname may finish setup first and become the
administrator.

Jellyfin needs 2048 MB of RAM available and 20 GB free on /srv before any media. The image
publishes amd64 and arm64. Measure all four:

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
```

If available RAM is under 2048 MB or free disk is under 20 GB, print both numbers and stop. Do
not install and hope. If `dig +short` prints nothing, print that and stop: Caddy cannot certify
a hostname that does not resolve. The 20 GB covers the image, config, cache and a small library
staging area; a real movie collection lives on storage the user already has and is not counted
here.

## 2. Layout

Config and cache are what Jellyfin writes. Media is a path the user already owns, mounted read
only, not an empty directory this install invents and never fills.

STOP: ask the user for the absolute path on this server to a media library they already have
(or will fill themselves), for example `/mnt/media` or `/home/them/videos`. Do not continue until they confirm. If they have no library yet, they may give `/srv/jellyfin/media` and you
will create that empty directory, with the understanding that playback stays empty until they
copy files in.

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/jellyfin /srv/jellyfin/backups /srv/jellyfin/config /srv/jellyfin/cache
# If the user chose /srv/jellyfin/media as the library path, create it owned by them:
# sudo install -d -m 755 -o $(id -u) -g $(id -g) /srv/jellyfin/media
ls -la /srv/jellyfin
test -d "<MEDIA_PATH>" && ls -ld "<MEDIA_PATH>"
```

Replace `<MEDIA_PATH>` with the path they gave. Assert: config, cache and backups exist and are
owned by the login user. The media path exists as a directory (create it only if they chose
`/srv/jellyfin/media`). If the media path is owned by root and unreadable by other users, fix
ownership or mode so the container can read it: `sudo chmod -R a+rX <MEDIA_PATH>` is enough
when the image runs as root (the default when no `user:` line is set). Do not leave a
root-owned empty `media/` that nothing ever mounts from their real library.

Write the path into `.env` so compose can interpolate it. This is not a secret:

```bash
umask 077
printf 'JELLYFIN_MEDIA_PATH=%s\n' '<MEDIA_PATH>' > /srv/jellyfin/.env
chmod 600 /srv/jellyfin/.env
umask 022
ls -la /srv/jellyfin/.env
cat /srv/jellyfin/.env
```

Assert: `.env` is mode 600 and prints one line with the path they chose, not a placeholder.

## 3. Secrets

No secret is generated for this install and there is no application password in `.env`. The
first credential is the administrator account the user creates in the setup wizard in step 7.
Between the container starting and that account existing, anyone who can reach the hostname may
finish the wizard first. Step 7 is a hard stop for that reason: create the account immediately,
then assert the wizard is closed.

## 4. compose.yml

```bash
cat > /srv/jellyfin/compose.yml <<'EOF'
# Jellyfin · the deterministic fallback. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   container install ... https://jellyfin.org/docs/general/installation/container
#   setup wizard ........ https://jellyfin.org/docs/general/post-install/setup-wizard/
#   backup .............. https://jellyfin.org/docs/general/administration/backup-and-restore
#
# One container. Config and cache are the server state (users, library metadata,
# watch progress). Media is a bind mount of a path the user already owns, read
# only, supplied via JELLYFIN_MEDIA_PATH in .env (not a secret; compose
# interpolates it). This file never downloads content. Tag and digest are the
# 10.10.7 release read from Docker Hub on 2026-08-07; amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  jellyfin:
    image: jellyfin/jellyfin:10.10.7@sha256:7ae36aab93ef9b6aaff02b37f8bb23df84bb2d7a3f6054ec8fc466072a648ce2
    container_name: jellyfin
    restart: unless-stopped
    volumes:
      # Database, users, library metadata, watch state. The thing to back up.
      - /srv/jellyfin/config:/config
      # Transcode and image cache. Safe to lose; rebuilds itself.
      - /srv/jellyfin/cache:/cache
      # The user's own library. Path comes from .env (JELLYFIN_MEDIA_PATH).
      # Read only: Jellyfin does not need to write into the media tree.
      - ${JELLYFIN_MEDIA_PATH}:/media:ro
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8204.
      - "127.0.0.1:8204:8096"
EOF
cd /srv/jellyfin && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. One service, one published port. Config and cache are the
writable state; media is read only. Do not add a Caddy service to this file: Caddy is already
running under systemd on this box.

## 5. Caddy and TLS

Append the block below to the Caddyfile Prompt Zero installed, with `<DOMAIN>` replaced by the
real hostname. Copy the file first: a syntax error here takes down every other site on the box.

```bash
cat > /srv/jellyfin/Caddyfile <<'EOF'
# Jellyfin · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://jellyfin.org/docs/general/networking/caddy and
# https://caddyserver.com/docs/automatic-https
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed, with
# <DOMAIN> replaced by the hostname pointed at this box. Caddy runs under systemd
# on the host. There is no Caddy container anywhere in this project.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8204 is the loopback port compose publishes; it is never in the firewall.
	reverse_proxy 127.0.0.1:8204
}
EOF
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-jellyfin
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sed "s|<DOMAIN>|${REAL_DOMAIN}|g" /srv/jellyfin/Caddyfile | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Set `REAL_DOMAIN` to the hostname the user gave in step 1 before running sed (for example
`REAL_DOMAIN=media.example.com`). Do not wrap the value in extra quotes inside the sed
replacement. Assert: validate and reload exit 0. If validate fails, restore
`/etc/caddy/Caddyfile.before-jellyfin`, reload, and report what it objected to. Caddy requests
the certificate on the first request and renews it on its own.

## 6. Firewall

Two ports open, both Caddy's. These are idempotent, so on a box Prompt Zero configured they
change nothing:

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

80/tcp answers the ACME challenge and redirects to HTTPS, 443/tcp is the only way in, and
443/udp is HTTP/3. 8204 stays closed because compose binds it to 127.0.0.1. Assert:
`ufw status verbose` prints `Status: active`, shows 80, 443/tcp and 443/udp, and no rule
mentioning 8204 or 8096.

## 7. Start and verify

```bash
cd /srv/jellyfin
docker compose pull
docker compose up -d
for i in $(seq 1 30); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/System/Info/Public); echo "$i $code"; [ "$code" = 200 ] && break; sleep 5; done
curl -sS https://<DOMAIN>/System/Info/Public
curl -sS https://<DOMAIN>/System/Info/Public | grep -o '"StartupWizardCompleted":[^,]*'
curl -sSL https://<DOMAIN>/web/ | grep -ci 'jellyfin'
```

Assert all four, and print what you received for each. The loop ends printing `200`. The public
system info is JSON that names the product. Before the wizard finishes,
`StartupWizardCompleted` is `false`. The web shell mentions jellyfin (case insensitive count
greater than 0). If any of the four misses, stop, run `docker compose logs --tail 40 jellyfin`,
and name the likely earlier step: a container that exits on a volume error is usually step 2
(the media path does not exist or is not readable), and a 502 from Caddy with a running
container is step 5. A running container is not success.

STOP: tell the user to open https://<DOMAIN> in a private window now, complete the setup
wizard (language, administrator username and password, and optionally add a library pointing at
`/media` inside the container, which is their host path), and confirm back to you that they can
sign in as that administrator. Do not continue until they confirm. This is the claim-race
window: whoever finishes the wizard first owns the box.

```bash
curl -sS https://<DOMAIN>/System/Info/Public | grep -o '"StartupWizardCompleted":[^,]*'
```

Assert: that prints `"StartupWizardCompleted":true`. That is the security assert in this block.
If it still prints `false`, the wizard was not completed; do not go on.

## 8. First backup and restore

One archive: config (users, library metadata, watch state), cache, compose, the media path
pointer in `.env`, and the live Caddy site block. Media files are not in it. That is deliberate:
they are large, already owned by the user, and belong in whatever backup protects the machine
they came from.

```bash
cd /srv/jellyfin
docker compose stop
sudo tar -czf /srv/jellyfin/backups/jellyfin-$(date +%F).tar.gz -C /srv/jellyfin config cache compose.yml .env -C /etc/caddy Caddyfile
docker compose start
ls -lh /srv/jellyfin/backups/
```

Assert: the archive exists and is non-empty. Print its size. Downtime is about ten seconds, and
the container is stopped on purpose so SQLite under config is not copied mid-write.

A backup on the same disk as the data is not a backup. Run this from the user's machine, not
the server:

```bash
mkdir -p ~/backups/jellyfin
scp vps:/srv/jellyfin/backups/*.tar.gz ~/backups/jellyfin/
```

To restore: `docker compose down`, `sudo rm -rf /srv/jellyfin/config /srv/jellyfin/cache`,
recreate those directories as in step 2, untar the archive back into /srv/jellyfin (which
restores config, cache, compose.yml and `.env`), put the Caddy block back if that is what was
lost, then `docker compose up -d`. Tell the user which half matters: `config/` is every account
and every watched progress, `.env` is which host path is mounted as `/media`, and the media
files themselves are outside this archive. Losing config loses the server identity. Losing media
loses the library. Neither half replaces the other.

## 9. Updating later

New versions are listed at https://github.com/jellyfin/jellyfin/releases. The release tag and
the image tag are the same string, so release `10.10.8` is image tag `10.10.8`. This install
pins 10.10.7, the settled end of the 10.10 line, rather than the newer 10.11 series: 10.11 is
the release that migrates the library database, and a first install is the wrong moment to
take a one-way migration. Move to 10.11 deliberately, after a backup, once its release notes
read as settled to you. Take a backup first, then edit the image line in
/srv/jellyfin/compose.yml to the new tag and its digest:

```bash
cd /srv/jellyfin
docker compose pull
docker compose up -d
docker compose logs --tail 30 jellyfin
```

Watch that log until it settles, then re-run step 7's public info check and a signed-in browse
before calling the update done.

## 10. What will probably go wrong

You will stream a 4K file to a phone on a mobile network through this VPS and watch the
provider's egress counter climb while the CPU pegs on a software transcode. I did that on a
two-core cloud instance and called the box broken. It was not broken; it was the wrong place
for that workload. Direct-play on the LAN, or a home box with the library on the same switch,
is the shape this product assumes. The VPS path is for when the library already lives near a
good uplink and you still want HTTPS and remote friends. Match clients to formats the TV can
play without transcoding, or buy CPU, and treat egress as a real line item.

## 11. Out of scope

- Do not add a Caddy container to the compose file. Caddy is already running under systemd on
  this box, and a second one would fight it for 80 and 443.
- Do not publish 8096 or 8204 on the public interface or open them in the firewall. Caddy is
  the only way in.
- Do not download copyrighted media or point the library at someone else's content. This
  install only mounts a path the user supplies.
- Do not enable hardware transcoding devices in this prompt. That needs host-specific devices
  and drivers; software transcoding is the portable default.

This path is slower: you paste every command yourself, and there is nobody watching the output
but you. If you can run Claude Code, use the other tab.

You are installing Jellyfin 10.10.7 on a VPS where Prompt Zero is done: `ssh vps` works,
Docker and Caddy are installed, the firewall is default-deny. Run everything over `ssh vps`
unless a step says otherwise, and replace `<DOMAIN>` with the hostname whose A record already
points at the box.

Read these three before step 1, because together they decide whether you want this at all.
Jellyfin streams files you already own: there is no catalogue and nothing appears that you did
not put on a disk. A home box with the library on the same LAN is the usual shape; a VPS is a
remote front door, and every remote stream burns that provider's egress the way a Netflix bill
would. Between first start and the end of the setup wizard, anyone who can reach the hostname
may finish setup first and become the administrator, so you will create that account in the
same session you start the container.

## 1. Preflight

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
```

You should see: at least `2048` MB available, at least `20` G free, `amd64` or `arm64`, and your
server's IP on the last line.

If you do not: an empty last line means the A record does not exist yet. Add it, wait a minute,
run `dig +short <DOMAIN>` again. Caddy cannot get a certificate for a hostname that does not
resolve, and failed attempts count against a rate limit you cannot see. Under the RAM or disk
floor means stop: a software transcode on a starving box fails mid-stream, not at start-up.


Jellyfin needs 2048 MB free RAM and 20 GB free on /srv before any media. The 20 GB covers
the image, config, cache and a small staging area. A real movie collection lives on storage
you already own and is not counted in that floor. Software transcoding is CPU-heavy: if you
plan to convert 4K to phone formats on this box, treat the RAM floor as a minimum and prefer
more cores.


## 2. Layout

Config and cache are what Jellyfin writes. Media is a path you already own, mounted read only.

Pick an absolute path on this server to a library you already have (or will fill yourself), for
example `/mnt/media`. If you have nothing yet, use `/srv/jellyfin/media` and create it empty.

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/jellyfin /srv/jellyfin/backups /srv/jellyfin/config /srv/jellyfin/cache
# Only if you chose the empty staging path:
# sudo install -d -m 755 -o $(id -u) -g $(id -g) /srv/jellyfin/media
ls -la /srv/jellyfin
test -d /mnt/media && ls -ld /mnt/media
```

Replace `/mnt/media` with your real path in the `test` line and below. If the directory is
root-owned and unreadable, fix mode so the container can read it:
`sudo chmod -R a+rX /path/to/media`. Do not invent a fresh empty `media/` under /srv and leave
your real library unmounted.


Ownership matters. The official image runs as root when no `user:` line is set, so it can
read a world-readable library. Prefer not to leave media root-owned with mode 700: the
container will start, the library scan will find zero files, and the dashboard will look empty
for a reason that is not a Jellyfin bug. `ls -ld` on the path should show that ordinary
processes can traverse and read it (`a+rX` is enough). Never create an empty `/srv/jellyfin/media`
as a substitute for mounting the folder where your files already live, unless you intend to
copy files into that empty folder yourself.


Write the path into `.env` (not a secret; compose interpolates it):

```bash
umask 077
printf 'JELLYFIN_MEDIA_PATH=%s\n' '/mnt/media' > /srv/jellyfin/.env
chmod 600 /srv/jellyfin/.env
umask 022
cat /srv/jellyfin/.env
```

You should see one line with your path. Mode of `.env` is `-rw-------`.

## 3. Secrets

No secret is generated here. The first credential is the administrator account you create in
the setup wizard in step 7. Between the container starting and that account existing, anyone
who can reach the hostname may finish the wizard first. Create the account immediately after
start.

## 4. compose.yml

Paste the whole block:

```bash
cat > /srv/jellyfin/compose.yml <<'EOF'
# Jellyfin · the deterministic fallback. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   container install ... https://jellyfin.org/docs/general/installation/container
#   setup wizard ........ https://jellyfin.org/docs/general/post-install/setup-wizard/
#   backup .............. https://jellyfin.org/docs/general/administration/backup-and-restore
#
# One container. Config and cache are the server state (users, library metadata,
# watch progress). Media is a bind mount of a path the user already owns, read
# only, supplied via JELLYFIN_MEDIA_PATH in .env (not a secret; compose
# interpolates it). This file never downloads content. Tag and digest are the
# 10.10.7 release read from Docker Hub on 2026-08-07; amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  jellyfin:
    image: jellyfin/jellyfin:10.10.7@sha256:7ae36aab93ef9b6aaff02b37f8bb23df84bb2d7a3f6054ec8fc466072a648ce2
    container_name: jellyfin
    restart: unless-stopped
    volumes:
      # Database, users, library metadata, watch state. The thing to back up.
      - /srv/jellyfin/config:/config
      # Transcode and image cache. Safe to lose; rebuilds itself.
      - /srv/jellyfin/cache:/cache
      # The user's own library. Path comes from .env (JELLYFIN_MEDIA_PATH).
      # Read only: Jellyfin does not need to write into the media tree.
      - ${JELLYFIN_MEDIA_PATH}:/media:ro
    ports:
      # Loopback only: the host's Caddy is the only thing that reaches 8204.
      - "127.0.0.1:8204:8096"
EOF
cd /srv/jellyfin && docker compose config >/dev/null && echo "compose OK"
```

You should see `compose OK`. One service, one published port. Config and cache are writable
state; media is read only. Do not add a Caddy service: Caddy already runs under systemd.

## 5. Caddy and TLS

Write the site block, then append it with your hostname in place of `<DOMAIN>`. Copy the live
Caddyfile first.

```bash
cat > /srv/jellyfin/Caddyfile <<'EOF'
# Jellyfin · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://jellyfin.org/docs/general/networking/caddy and
# https://caddyserver.com/docs/automatic-https
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed, with
# <DOMAIN> replaced by the hostname pointed at this box. Caddy runs under systemd
# on the host. There is no Caddy container anywhere in this project.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# 8204 is the loopback port compose publishes; it is never in the firewall.
	reverse_proxy 127.0.0.1:8204
}
EOF
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-jellyfin
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
REAL_DOMAIN='media.example.com'
sed "s|<DOMAIN>|${REAL_DOMAIN}|g" /srv/jellyfin/Caddyfile | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Put your real hostname in `REAL_DOMAIN` before you paste. You should see validate exit 0 and
reload exit 0. If validate fails, restore `/etc/caddy/Caddyfile.before-jellyfin`, reload, and
read the error. Caddy gets the certificate on the first request and renews it on its own.

## 6. Firewall

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

You should see `Status: active`, rules for 80 and 443, and nothing for 8204 or 8096. 80 is the
ACME challenge and HTTPS redirect, 443 is the only way in, 443/udp is HTTP/3.

## 7. Start and verify

```bash
cd /srv/jellyfin
docker compose pull
docker compose up -d
for i in $(seq 1 30); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/System/Info/Public); echo "$i $code"; [ "$code" = 200 ] && break; sleep 5; done
curl -sS https://<DOMAIN>/System/Info/Public
curl -sS https://<DOMAIN>/System/Info/Public | grep -o '"StartupWizardCompleted":[^,]*'
curl -sSL https://<DOMAIN>/web/ | grep -ci 'jellyfin'
```

You should see: the loop ends on `200`; JSON public system info; `StartupWizardCompleted` is
`false` until you finish the wizard; a jellyfin count greater than 0 on the web shell. If the
loop never reaches 200, run `docker compose logs --tail 40 jellyfin`. A missing or unreadable
media path is step 2; a 502 with a running container is step 5.

STOP: open https://<DOMAIN> in a private window now. Complete the setup wizard: language, admin
username and password, and optionally a library at `/media` (that is your host path inside the
container). Sign in as that administrator. Do not continue until you can sign in. This is the
claim-race window.

```bash
curl -sS https://<DOMAIN>/System/Info/Public | grep -o '"StartupWizardCompleted":[^,]*'
```

You should see `"StartupWizardCompleted":true`. If it is still `false`, the wizard was not
finished; stop and finish it.


In the wizard, when you add a library, the path inside the container is `/media`. That is the
bind of `JELLYFIN_MEDIA_PATH` from `.env`, mounted read-only. If the scan finds nothing, re-check
permissions on the host path and that `.env` points at the folder that actually holds files,
not its parent with a different layout. Hardware acceleration is out of scope on this path:
software decode works without GPU devices.

After the wizard, put the admin password in a password manager. There is no second factor in
this install and no SMTP for resets. A forgotten admin password means database work or a
re-run of the wizard on a wiped config, both worse than writing it down once.


## 8. First backup and restore

One archive: config, cache, compose, `.env`, and the live Caddyfile. Media files are not in it.

```bash
cd /srv/jellyfin
docker compose stop
sudo tar -czf /srv/jellyfin/backups/jellyfin-$(date +%F).tar.gz -C /srv/jellyfin config cache compose.yml .env -C /etc/caddy Caddyfile
docker compose start
ls -lh /srv/jellyfin/backups/
```

The archive should exist and be non-empty. Print its size. Downtime is about ten seconds; the
container is stopped so config is not copied mid-write.

A backup on the same disk is not a backup. From your own machine (not the server):

```bash
mkdir -p ~/backups/jellyfin
scp vps:/srv/jellyfin/backups/*.tar.gz ~/backups/jellyfin/
```

To restore: `docker compose down`, remove `config` and `cache`, recreate them, untar the
archive into /srv/jellyfin, put the Caddy block back if needed, then `docker compose up -d`.
`config/` is accounts and watch state. `.env` is which host path mounts as `/media`. Media
files live outside this archive. Neither half replaces the other.


What the archive is not: your movies and shows. Those stay on `JELLYFIN_MEDIA_PATH`. Back them
up with whatever already protects that disk. What the archive is: every user, every library
definition, every watch progress marker, the compose pin, the path pointer, and the live
Caddy configuration that terminates TLS. Restore without media still boots an empty server
with your accounts. Restore media without config still leaves files on disk with no server
identity.




Remote friends need enough uplink and a client they can install. Jellyfin has clients for
phones, TVs and browsers; none of them remove the need for you to own the files. Plugins are
community code you choose to trust, and this install does not enable any. Live TV guide
subscriptions and paid plugin stores are out of scope the same way vendor support is out of
scope: there is no line to call.

When you later change `JELLYFIN_MEDIA_PATH`, stop the stack, edit `.env`, run
`docker compose up -d`, and re-scan libraries in the dashboard. A path that moves without an
update to `.env` is a silent empty library after reboot.

For a cold restore on a new VPS: install Docker and Caddy (Prompt Zero), restore the archive
into /srv/jellyfin, restore the Caddyfile fragment, ensure `JELLYFIN_MEDIA_PATH` still points
at media that exists on the new box (or re-attach storage first), then start compose and sign
in with the same admin account. Order matters: `.env` before first start, media path present
before you expect scans to find files.

## 9. Updating later

New versions are at https://github.com/jellyfin/jellyfin/releases. This install pins 10.10.7,
the settled end of the 10.10 line, on purpose: the newer 10.11 series migrates the library
database, and a first install is the wrong moment for a one-way migration. Move to 10.11
deliberately, after a backup, once its release notes read as settled to you. Take a backup
first, then edit the image line in /srv/jellyfin/compose.yml to the new tag and digest:

```bash
cd /srv/jellyfin
docker compose pull
docker compose up -d
docker compose logs --tail 30 jellyfin
```

Watch the log until it settles, then re-run step 7's public info check and a signed-in browse
before calling the update done.


If a release notes page mentions a one-way database migration, read it before pulling. Jellyfin
upgrades are usually forward-only: take the backup first, then pull, then watch logs for
migration messages. If the container loops, restore config from the archive and pin the previous
digest until you understand the failure.


## 10. What will probably go wrong

You will stream a 4K file to a phone on a mobile network through this VPS and watch the
provider's egress counter climb while the CPU pegs on a software transcode. That is not a
broken box; it is the wrong place for that workload. Direct-play on the LAN, or a home box
with the library on the same switch, is the shape this product assumes. Match clients to
formats the TV can play without transcoding, or buy CPU, and treat egress as a real line item.

The other common miss is leaving the wizard open. DNS for a new hostname is quieter than it
feels. Finish the admin account before you walk away to copy files. Assert
`StartupWizardCompleted` is true before you call the install done. Config without that assert
is an unlocked front door with a media server behind it.

## 11. Out of scope

- Do not add a Caddy container to the compose file. Caddy is already running under systemd on
  this box, and a second one would fight it for 80 and 443.
- Do not publish 8096 or 8204 on the public interface or open them in the firewall. Caddy is
  the only way in.
- Do not download copyrighted media or point the library at someone else's content. This
  install only mounts a path you supply.
- Do not enable hardware transcoding devices in this prompt. That needs host-specific devices
  and drivers; software transcoding is the portable default.

- Do not skip the first backup after the wizard. Config without a copy is a single disk failure
  away from losing every account and every watched position.

258 lines · 11,846 bytes

You are Claude Code on the user's own computer. There is no server and no Prompt Zero:
everything in this prompt runs on this machine and stays on it.

Run every command on this computer, in the shell you are already in. Nothing in this prompt
uses ssh.

Install Jellyfin 10.10.7 under ~/selfhost/jellyfin, answering at http://localhost:8204.

## 1. Preflight

Say this to the user before step 2 runs, because it decides whether they want this install at
all. Jellyfin streams files they already own. There is no catalogue and nothing appears that
they did not put on disk. This path answers only at http://localhost:8204, so a phone on the
same wifi and a friend on another network get nothing. What they get is a player and a library
on this desk, which is the home-box shape without the remote front door.

Detect the OS and measure the machine:

```bash
uname -s
case "$(uname -s)" in
  Darwin) vm_stat | awk '/page size/{p=$8} /free|inactive/{s+=$3} END {printf "%d MB available\n", s*p/1048576}' ;;
  Linux) . /etc/os-release && echo "$ID $VERSION_CODENAME"; free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}' ;;
  MINGW*|MSYS*) powershell -Command "(Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory" | awk '$1+0 {printf "%d MB available\n", $1/1024}' ;;
esac
df -h ~
```

`Darwin` is macOS, `Linux` is Linux, `MINGW` or `MSYS` is Windows under Git Bash. On Linux the
distribution ID and codename print next, for step 2. Jellyfin needs 2048 MB of RAM available
and 20 GB free on the home disk before a large library, and the image publishes amd64 and
arm64. Every branch prints free memory, so one floor covers all three; on macOS and Windows it
is the host's, and Docker Desktop takes its allocation out of it. If available RAM is under
2048 MB or free disk is under 20 GB, print both numbers and stop. Do not install and hope.

## 2. Docker

Check before installing anything:

```bash
docker info >/dev/null 2>&1 && echo "docker OK" || echo "docker MISSING"
docker compose version 2>/dev/null || true
```

If that printed `docker OK` and a compose version, skip to step 3.

Otherwise, install Docker for the OS step 1 detected:

- macOS: if `command -v brew` succeeds, run `brew install --cask docker`. If there is no
  Homebrew, STOP: tell the user to download Docker Desktop from
  https://www.docker.com/products/docker-desktop/ and install it, and wait until they
  confirm. Either way, then STOP: tell the user to open Docker Desktop once, accept its
  terms, and wait for the whale icon to say it is running. Do not continue until they
  confirm.
- Windows: run `winget install -e --id Docker.DockerDesktop`. If winget is missing or the
  install fails, STOP: tell the user to download Docker Desktop from the URL above and
  install it, and wait until they confirm. Docker Desktop configures WSL 2 itself and may
  ask for a reboot; if it does, STOP and tell the user to reboot and come back, this
  prompt resumes at this step. Then STOP: have the user open Docker Desktop, accept its
  terms, and confirm it says running.
- Linux, Debian or Ubuntu: install Docker Engine from download.docker.com's apt
  repository, with its signing key saved to a file first, never piped into a shell. The
  fence is guarded, a no-op on anything but a Linux with apt:

```bash
if [ "$(uname -s)" = "Linux" ] && command -v apt-get >/dev/null 2>&1; then
  sudo apt-get update
  sudo apt-get install -y ca-certificates curl
  sudo install -m 0755 -d /etc/apt/keyrings
  sudo curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$(. /etc/os-release && echo "$ID") $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
  sudo apt-get update
  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
  sudo usermod -aG docker "$USER"
fi
```

  Adding the user to the docker group is root-equivalent on this machine; say that to the
  user in one sentence, and tell them the group change lands at their next login.
- Linux, anything else: STOP. Tell the user to install Docker Engine and the compose
  plugin with their distribution's package manager, and to run this prompt again once
  `docker info` works.

Assert: `docker info` exits 0 and `docker compose version` prints a version. Do not
continue without both.

## 3. Layout

Config and cache live under ~/selfhost/jellyfin. Media is a folder the user already has,
mounted read only, not an empty tree this install invents.

```bash
mkdir -p ~/selfhost/jellyfin/config ~/selfhost/jellyfin/cache ~/selfhost/jellyfin/backups
ls -la ~/selfhost/jellyfin
```

STOP: ask the user for the absolute path to a media library on this computer (for example
`$HOME/Videos` or `$HOME/Movies`). Do not continue until they confirm. If they have no library
yet, they may give `$HOME/selfhost/jellyfin/media` and you create that empty directory.

```bash
# Create only if they chose the empty staging path:
# mkdir -p ~/selfhost/jellyfin/media
test -d "<MEDIA_PATH>" && ls -ld "<MEDIA_PATH>"
umask 077
printf 'JELLYFIN_MEDIA_PATH=%s\n' '<MEDIA_PATH>' > ~/selfhost/jellyfin/.env
chmod 600 ~/selfhost/jellyfin/.env
umask 022
cat ~/selfhost/jellyfin/.env
```

Replace `<MEDIA_PATH>` with the path they gave (expand `$HOME` yourself so `.env` holds a real
absolute path Docker can bind). Assert: the directory exists and `.env` prints one
`JELLYFIN_MEDIA_PATH=` line. On Windows under Git Bash, write a path Docker Desktop can see,
for example `/c/Users/them/Videos`, not `C:\Users\...`.

## 4. Secrets

No secret is generated for this install. The first credential is the administrator account the
user creates in the setup wizard in step 7. On localhost the claim-race is limited to other
software on this machine that can open http://localhost:8204, which is still enough reason to
finish the wizard in the same session.

## 5. compose.yml

```bash
cat > ~/selfhost/jellyfin/compose.yml <<'EOF'
# Jellyfin · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   container install ... https://jellyfin.org/docs/general/installation/container
#   setup wizard ........ https://jellyfin.org/docs/general/post-install/setup-wizard/
#   backup .............. https://jellyfin.org/docs/general/administration/backup-and-restore
#
# One container on the computer you are sitting at. Paths are relative to
# ~/selfhost/jellyfin/. Media is a bind of a folder the user already has, via
# JELLYFIN_MEDIA_PATH in .env. This file never downloads content. Tag and digest
# are the 10.10.7 release read from Docker Hub on 2026-08-07; amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  jellyfin:
    image: jellyfin/jellyfin:10.10.7@sha256:7ae36aab93ef9b6aaff02b37f8bb23df84bb2d7a3f6054ec8fc466072a648ce2
    container_name: jellyfin
    restart: unless-stopped
    volumes:
      - ./config:/config
      - ./cache:/cache
      # User library path from .env. Read only.
      - ${JELLYFIN_MEDIA_PATH}:/media:ro
    ports:
      # Loopback only: no other device on the wifi can reach 8204.
      - "127.0.0.1:8204:8096"
EOF
cd ~/selfhost/jellyfin && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. One service, one loopback port.

## 6. Firewall

Nothing to open. This install binds only to loopback. Confirm the binding:

```bash
grep -c '"127.0.0.1:' ~/selfhost/jellyfin/compose.yml
```

Assert: that prints `1`. Do not rebind to `0.0.0.0`. A media server on every network this
laptop joins is not what the local path is for.

## 7. Start and verify

```bash
cd ~/selfhost/jellyfin
docker compose pull
docker compose up -d
for i in $(seq 1 30); do code=$(curl -sS -o /dev/null -w '%{http_code}' http://localhost:8204/System/Info/Public); echo "$i $code"; [ "$code" = 200 ] && break; sleep 5; done
curl -sS http://localhost:8204/System/Info/Public
curl -sS http://localhost:8204/System/Info/Public | grep -o '"StartupWizardCompleted":[^,]*'
curl -sSL http://localhost:8204/web/ | grep -ci 'jellyfin'
```

Assert all four, and print what you received for each. The loop ends printing `200`. The public
info is JSON. Before the wizard finishes, `StartupWizardCompleted` is `false`. The web shell
mentions jellyfin. If any miss, stop, run `docker compose logs --tail 40 jellyfin`, and name
the cause: a missing media path is step 3; a port conflict means something else holds 8204.

STOP: tell the user to open http://localhost:8204, complete the setup wizard, create the
administrator account, optionally add a library at `/media`, and confirm they can sign in.
Do not continue until they confirm.

```bash
curl -sS http://localhost:8204/System/Info/Public | grep -o '"StartupWizardCompleted":[^,]*'
```

Assert: `"StartupWizardCompleted":true`. If it is still `false`, the wizard was not finished.

## 8. First backup and restore

One archive: config, cache, compose and the media path pointer. Media files stay outside.

```bash
cd ~/selfhost/jellyfin
docker compose stop
tar -C ~/selfhost/jellyfin -czf ~/selfhost/jellyfin/backups/jellyfin-$(date +%F).tar.gz config cache compose.yml .env
docker compose start
ls -lh ~/selfhost/jellyfin/backups/
```

Assert: the archive exists and is non-empty. Print its size. Downtime is about ten seconds;
the container is stopped so config is not copied mid-write.

That archive sits on the same disk as the data. Ask the user for a destination that leaves this
computer, a folder their sync service watches or a USB stick, and copy it there with `cp`. In
Git Bash a Windows drive is written `/d/Backups`, not `D:\Backups`. Assert: the user confirms
the filename is listed there.

To restore: `cd ~/selfhost/jellyfin`, `docker compose down`, `rm -rf config cache`, untar the
archive there, then `docker compose up -d`. Tell the user `config/` is accounts and watch
state, `.env` is which host path mounts as `/media`, and the media files themselves are not in
the archive.

## 9. Updating later

New versions are listed at https://github.com/jellyfin/jellyfin/releases. This install pins
10.10.7, the settled end of the 10.10 line, on purpose: the newer 10.11 series migrates the
library database, and a first install is the wrong moment for a one-way migration. Move to
10.11 deliberately, after a backup, once its release notes read as settled to you. Take a
backup first, then edit the image line in ~/selfhost/jellyfin/compose.yml to the new tag and
digest:

```bash
cd ~/selfhost/jellyfin
docker compose pull
docker compose up -d
docker compose logs --tail 30 jellyfin
```

Watch the log until it settles, then re-run step 7's public info check before calling the
update done.

## 10. What will probably go wrong

I closed the laptop mid-transcode and came back to a stalled client and a warm machine. Docker
Desktop and the lid are a pair: when the host sleeps, playback stops, and nothing here pages
you about it. Direct-play of files this computer can decode without a software transcode is the
reliable path. If the library is large, keep it on a disk that stays mounted; a missing bind at
start-up is a container that restarts into the same volume error until you fix `.env`.

## 11. Out of scope

- Do not expose this to the internet.
- Do not configure port forwarding on the router.
- Do not add a reverse proxy or TLS.
- Do not rebind 8204 to 0.0.0.0 so a phone on the wifi can load the library. Use the VPS path
  on this page when remote access is the goal.
- Do not download copyrighted media. This install only mounts a path the user supplies.

# Jellyfin · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   container install ... https://jellyfin.org/docs/general/installation/container
#   setup wizard ........ https://jellyfin.org/docs/general/post-install/setup-wizard/
#   backup .............. https://jellyfin.org/docs/general/administration/backup-and-restore
#
# One container on the computer you are sitting at. Paths are relative to
# ~/selfhost/jellyfin/. Media is a bind of a folder the user already has, via
# JELLYFIN_MEDIA_PATH in .env. This file never downloads content. Tag and digest
# are the 10.10.7 release read from Docker Hub on 2026-08-07; amd64 and arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  jellyfin:
    image: jellyfin/jellyfin:10.10.7@sha256:7ae36aab93ef9b6aaff02b37f8bb23df84bb2d7a3f6054ec8fc466072a648ce2
    container_name: jellyfin
    restart: unless-stopped
    volumes:
      - ./config:/config
      - ./cache:/cache
      # User library path from .env. Read only.
      - ${JELLYFIN_MEDIA_PATH}:/media:ro
    ports:
      # Loopback only: no other device on the wifi can reach 8204.
      - "127.0.0.1:8204:8096"