poptonium

poptonium

Docker app from Benjavin's Repository

Companion backend for the Poptonium Plex client.

Overview
Companion backend for the Poptonium Plex client. Allows serving custom sections, curations and ratings, integrates with Overseerr and facilitates other extra functionalities on top of Plex.

Poptonium

Shape the Plex app everyone on your server sees.
The self-hosted companion server for Poptonium, a Plex client for iOS and Android.

Sections built in the admin, shown in the app
Build rows and heroes in the admin. They appear on everyone's Library page.

Rating badges set in the admin, shown in the app
Pick which scores show, with fallbacks when a title has none.

Spotlight on the TV with the phone as remote
Poptonium's own Cast receiver, with a Spotlight of your library while nothing plays.

Poptonium

Always, with or without the server

  • Google Cast done properly. Poptonium has its own receiver: styled ASS/SSA subtitles are never burned in, and switching subtitles doesn't restart the video. Controls live in a Live Activity on iPhone and a media notification on Android.
  • Plays almost anything. An mpv-based player on iPhone direct-plays nearly every container and codec. Android transcodes only when the device can't decode.

With this server

  • Your library, laid out your way. Rows, heroes and bento grids from Plex collections or filters. No streaming, Discover or live TV shelves.
  • Ratings you choose. IMDb, Rotten Tomatoes, TMDB and Metacritic, with your own display and weighting (via MDbList).
  • Subtitles without accounts. Viewers search and download in-app through your OpenSubtitles connection.
  • Discover and requests. A nightly popular feed, with requests routed to your Overseerr.
  • TV Spotlight. The Cast receiver shows your sections while nothing plays.
  • Share links with rich previews.

Feature details and guides: poptonium.app.

Install

Image ghcr.io/benjafin/poptonium:latest (stable), :dev (develop)
Port container 8085, published on host port 3654
Volumes /data for config, DB and caches. Optionally your media, read-only (below)

Unraid: install Poptonium from Community Applications.

Docker:

docker run -d --name poptonium --restart unless-stopped \
  -p 3654:8085 \
  -v /path/to/appdata/poptonium:/data \
  ghcr.io/benjafin/poptonium:latest

Compose: the included docker-compose.yml builds from source.

[!IMPORTANT] Publish on host port 3654, ideally on the same host as Plex. Without a proxy, the app probes http://<plex-host>:3654.

Configure

Open http://<host>:3654/admin, create the admin account, and run the setup wizard. It tests every connection before saving:

Integration Enables Credentials
Plex (required) Everything Server URL (e.g. http://plex:32400) and token
MDbList Ratings, popular feed API key
Overseerr Requests URL and API key
OpenSubtitles Subtitle search and download Consumer API key and an account (20 downloads/day free)

Every optional integration can be left out, which disables only its feature. The wizard then offers starter sections based on your libraries.

Reverse proxy

The proxy is what makes the server reachable outside your LAN and from the Cast receiver. Set it up after the server is running.

How the app finds the server

There is no address to enter in the app. It reads the connections plex.tv advertises for your Plex server and probes two candidates for each one, LAN connections first:

  1. <connection>/poptonium/capabilities (reverse proxy)
  2. http://<connection host>:3654/capabilities (direct)

The highest-priority candidate that answers wins. This means:

  • LAN, no proxy: works through (2) when Poptonium is published on port 3654 of the Plex host.
  • Remote: needs (1). Your proxied URL must be one of the connections Plex advertises.
  • Cast receiver: it runs on https://poptonium.app/cast/, so it can only reach an https backend. Spotlight and fast Cast subtitles need the https proxy, even on your LAN.

Steps

  1. Advertise the proxied Plex URL. In Plex, go to Settings > Network > Custom server access URLs and add your proxied domain, e.g. https://plex.example.com:443. Skip this if it's already listed.

  2. Proxy /poptonium/ to the container, without a path rewrite. The server serves every route under both / and /poptonium.

  3. Keep /poptonium/admin LAN-only. The app never calls it, and the admin stays reachable directly on :3654.

  4. If you geo-block or LAN-restrict the domain, exempt /poptonium/s/. Share pages are public, and link-preview crawlers need to reach them.

  5. Verify from outside your LAN:

    # expect {"service":"poptonium",...}
    curl -s https://plex.example.com/poptonium/capabilities
    # expect 403 (404 with SWAG)
    curl -sI https://plex.example.com/poptonium/admin
    

Then sign out and back in to the app, or relaunch it, so discovery runs again.

nginx

Add these blocks inside the server { } of your existing Plex proxy. The regex location is matched before the prefix location, and both win over Plex's location /.

location ~ ^/poptonium/admin(/|$) {
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    allow 192.168.0.0/16;
    deny all;
    proxy_pass http://poptonium:8085;    # no URI part: path is preserved
}

location /poptonium/ {
    proxy_pass http://poptonium:8085;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Use poptonium:8085 when the proxy shares a Docker network with the container, and <host-ip>:3654 otherwise.

SWAG: use swag/poptonium.subdomain.conf. It restricts the admin with SWAG's $lan-ip and includes proxy.conf/resolver.conf.

Caddy, Traefik and others: the requirements are the same. Forward /poptonium/* unchanged, restrict /poptonium/admin* to private ranges (remote_ip private_ranges in Caddy, an ipAllowList middleware in Traefik), and keep the Plex route as the catch-all.

Optional

Share links

Set Integrations > Share links to the public base URL, e.g. https://plex.example.com/poptonium. Leaving it blank keeps sharing off, and the app hides its Share button.

Media mount

Mount your media read-only at the same container paths Plex uses:

-v /mnt/user/media/Movies:/movies:ro -v "/mnt/user/media/TV Shows:/tv:ro"

The server then extracts embedded subtitle tracks for the Cast receiver straight from the file (ffmpeg is bundled). They arrive in under a second, with ASS styling kept. The mount also enables phone audio while casting: the TV plays muted, and the app streams a synced Opus track from /cast/audio.

If the paths can't match, map them with SUBTITLE_PATH_MAP=/plex/path=/container/path;.... The dashboard's Cast subtitles tile shows which Plex library folders are visible. Without the mount, subtitles go through Plex.

Environment variables

Configuration lives in /data/config.json and is managed in the admin. These variables only seed it on first start, which is useful for scripted deploys:

Variable
PLEX_URL, PLEX_TOKEN Plex
MDBLIST_API_KEY MDbList
OVERSEERR_URL, OVERSEERR_API_KEY Overseerr
OPENSUBTITLES_API_KEY, OPENSUBTITLES_USERNAME, OPENSUBTITLES_PASSWORD OpenSubtitles
PUBLIC_URL Share links base URL
SUBTITLE_PATH_MAP Media path mapping (read on every start)
TZ Timezone for the nightly jobs

License

MIT

Categories

Related apps

Explore more like this

Explore all

Links

Details

Repository
ghcr.io/benjafin/poptonium:latest
Last Updated2026-11-22
First Seen2026-06-23

Runtime arguments

Web UI
http://[IP]:[PORT:8085]/admin
Network
bridge
Shell
sh
Privileged
false

Template configuration

WebUI / API PortPorttcp

Host port for the web admin UI and API. Keep it at 3654: without a reverse proxy the app probes http://[Plex host]:3654.

Target
8085
Default
3654
Value
3654
DataPathrw

Persistent data: SQLite cache DB and custom sections.

Target
/data
Default
/mnt/user/appdata/poptonium
Value
/mnt/user/appdata/poptonium
Media (read-only)Pathro

Optional, for fast subtitles on the Poptonium Cast receiver: your media, read-only. Set the Container Path to the path Plex itself uses for this folder (copy it from your Plex container's own path mappings; add one mapping per Plex media path), or keep /media and set SUBTITLE_PATH_MAP. The dashboard shows whether every Plex library folder is visible. Without it, subtitles still work through Plex, just slower.

Target
/media
Default
/mnt/user/media
Value
/mnt/user/media
PLEX_URLVariable

REQUIRED. Internal Plex URL (e.g. http://plex:32400).

PLEX_TOKENVariable

REQUIRED. Plex server token (X-Plex-Token).

MDBLIST_API_KEYVariable

Optional. mdblist.com API key: the source for all ratings (IMDb/RT/TMDB/Metacritic/MDbList) plus the Discover feed. Blank disables ratings and the popular feed; the rest still works.

OVERSEERR_URLVariable

Optional. Overseerr base URL (e.g. http://overseerr:5055) for request/search proxy.

OVERSEERR_API_KEYVariable

Optional. Overseerr API key. Blank disables the Overseerr proxy.

OPENSUBTITLES_API_KEYVariable

Optional. OpenSubtitles app API key (opensubtitles.com, Profile, API Consumers). Required for online subtitle search/download.

OPENSUBTITLES_USERNAMEVariable

Optional. OpenSubtitles account username; its daily download quota (20/day free) is used for downloads.

OPENSUBTITLES_PASSWORDVariable

Optional. OpenSubtitles account password.

PUBLIC_URLVariable

Optional. This server's internet address through your reverse proxy (e.g. https://plex.example.com/poptonium). Enables share links; blank keeps sharing off. Editable later in the admin under Share links.

SUBTITLE_PATH_MAPVariable

Optional. Only if the media is mounted at a different path than Plex uses: Plex path=container path, separated by ';' (e.g. /data/movies=/media/Movies;/data/tv=/media/TV Shows). Blank when the paths match.

TZVariable

Optional. Container timezone (e.g. Europe/Berlin). Sets the 'server time' used by the nightly ratings-sync schedule.