Skip to content

Plex

Plex is the media server / streaming front-end for the stack — it indexes the libraries the *arr apps fill and streams them to clients (TV apps, phones, web, Plex Amp). This page covers the container as it runs here; the full stack compose lives on the Media Server page.

Plex Support · LinuxServer image docs · Get a claim token

Container

Runs from the LinuxServer.io image in host networking mode — Plex relies on a number of ports plus local discovery (GDM/DLNA), and host mode is the recommended setup.

  plex:
    image: lscr.io/linuxserver/plex:1.43.4.10903-e5521bd8c-ls328   # pinned; Renovate bumps it
    container_name: plex
    network_mode: host
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - VERSION=docker
      - PLEX_CLAIM=${PLEX_CLAIM}   # from https://www.plex.tv/claim (first run only)
    # No `ports:`: it does nothing under network_mode: host.
    devices:
      - /dev/dri:/dev/dri          # Intel QuickSync HW transcode (8th-gen+)
    volumes:
      - ${APPDATA_PATH}/plex/config:/config
      - /mnt/appdata/plex/transcode:/transcode   # transcode scratch on the appdata SSD
      - ${MEDIA_DATA}/media:/data/media:ro       # Plex only reads media
    # linuxserver's s6 init only drops privileges, so no-new-privileges is safe; no cap_drop (init needs chown/setuid).
    security_opt:
      - no-new-privileges:true
    restart: always
    # /identity is the standard unauthenticated Plex health endpoint
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:32400/identity"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Note

network_mode: host means a ports: block would be ignored — Plex binds 32400 (and its discovery ports) directly on the host.

Why the media mount is read-only

Plex only reads media; Radarr, Sonarr and qBittorrent write it through their own read-write mounts. Plex is the one service in the stack that people reach from outside the house, so it gets the least access: only media/ (not the torrents folder), read-only, plus no-new-privileges. If Plex were ever compromised it couldn't delete or change the library. The trade-off: deleting media from inside Plex fails. Delete through Radarr/Sonarr instead.

First run & claiming the server

The PLEX_CLAIM token links a brand-new server to your account automatically on first boot.

  1. While logged in, open plex.tv/claim and copy the claim-xxxx token into PLEX_CLAIM in your .env.
  2. docker compose up -d plex within ~4 minutes — the token expires that fast.
  3. Browse to http://<YOUR_SERVER_IP>:32400/web, finish the setup wizard, and add libraries pointing at /data/media/....

Tip

The claim token is only needed for the very first launch. Once the server is associated with your account you can blank PLEX_CLAIM — subsequent restarts keep the association from the /config volume. Never commit a real claim token to git — keep it in .env only.

Libraries & naming

Plex matches files to metadata by naming convention. Follow Plex's naming so matches are clean:

  • Movies: Movie Name (Year)/Movie Name (Year).ext
  • TV: Show Name (Year)/Season 01/Show Name - S01E01.ext

Radarr and Sonarr already produce Plex-friendly names — see TRaSH Guides for the recommended naming schemes and quality settings that keep Plex, Radarr, and Sonarr agreeing on file layout.

Hardware transcoding (QuickSync)

Direct Play (client plays the file as-is) is always best. When a client needs a different format/bitrate, Plex transcodes — and hardware transcoding offloads that to the Intel iGPU instead of hammering the CPU.

Requires Plex Pass

Hardware-accelerated streaming is a Plex Pass feature. Without it, transcoding is CPU-only.

  • Passing /dev/dri into the container exposes the Intel iGPU for QuickSync (Intel 8th-gen or newer).
  • Enable it: Settings → Transcoder → "Use hardware acceleration when available".
  • Verify: play a file that forces a transcode and check the Dashboard — the session should show "(hw)" next to Transcode.
  • The /transcode mount is scratch space for in-progress transcodes; put it on fast storage (SSD/NVMe), or map it to /dev/shm (RAM) if you have the memory to spare. Here it's on the appdata SSD, and Settings → Transcoder → Transcoder temporary directory is set to /transcode.
  • My server's iGPU is an Intel UHD Graphics 630 (Coffee Lake), passed in as /dev/dri/renderD128.

Remote access

The simplest way to watch from outside the house is Plex's own remote access.

  • Settings → Remote Access. Plex either maps a port automatically (UPnP / NAT-PMP on the router) or you forward 32400/tcp (or a port of your choice) to the server manually. Fully accessible outside your network means clients connect directly.
  • Relay fallback. If clients can't reach the server directly, Plex routes the stream through its own Relay servers. That works with no port forward at all, but each relayed stream is capped at 2 Mbps, so the server transcodes down to fit.
  • Custom server access URLs (Settings → Network) let you publish your own https:// address to plex.tv, if you run Plex behind your own reverse proxy or forwarded port. Clients try it alongside the default connections.
  • Account requirement. Streaming personal media from outside your network now needs a Plex Pass on the server owner's account, or a Plex Pass / Remote Watch Pass on the viewer's account. Music in Plexamp and photos are exempt.

Don't put Plex behind Cloudflare Tunnel

A Cloudflare Tunnel proxies every byte through Cloudflare's network, and Cloudflare's service terms restrict serving video (or a disproportionate share of large files) through it without one of their paid video products. Streaming a media library through a tunnel is exactly that, and accounts doing it can be limited. Use Plex's remote access or relay instead, or your own reverse proxy on a forwarded port.

Sources & further reading