sandobserver/posteryard repository overview

⁠Posteryard

Clean, consistent posters for Plex, Jellyfin and Emby, picked, rendered and kept current automatically.

Website: posteryard.sandobserver.com⁠

Source and issues: github.com/SandObserver/Posteryard⁠

Studio posters come in every font, tagline and layout. Posteryard swaps them for textless art with the title in the same spot on every poster. It then renders, uploads and refreshes them on its own as your library grows. You only step in when you want a different picture.

⁠What you get

• Clean art. Textless art from TMDB, with the title logo in one spot at one size. Art with a printed title is skipped.
• Where it streams. Shows get the mark of the service they stream on.
• Quality badges. 4K, HDR, Dolby Vision and Atmos badges, read from your files.
• Status labels. JUST ADDED, NEW EPISODE and NEW SEASON, plus a red countdown before Maintainerr⁠ deletes a title.
• Seasons, episodes and collections. Each season gets its own art and number. Collections can get a tile too.
• Safe to try. It starts in preview mode and changes nothing until you say so. Everything it uploads can be undone.

⁠Getting started

You need Docker⁠ on a 64-bit Intel, AMD or ARM machine, a free TMDB API key⁠ and your Plex token⁠. Using Jellyfin or Emby? See Jellyfin and Emby⁠.

⁠1. Create the compose file

Save this as compose.yml and replace the example values. The same image is on Docker Hub as sandobserver/posteryard.

services:
  posteryard:
    image: sandobserver/posteryard:latest
    container_name: posteryard
    restart: unless-stopped
    init: true
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    environment:
      # TMDB API Key or API Read Access Token
      - TMDB_API_KEY=your-tmdb-api-key
      # Plex's network address. Not localhost.
      - PLEX_URL=http://192.168.1.10:32400
      - PLEX_TOKEN=your-plex-token
      # Any long random text: openssl rand -hex 16
      - WEBHOOK_SECRET=any-long-random-text
      # The daily pass runs at DAILY_AT in this time zone
      - TZ=America/New_York
      - DRY_RUN=true
    volumes:
      - ./data:/data
    ports:
      - "8000:8000"

./data is the folder on your server where Posteryard keeps its files. If Plex runs in Docker on the same network, set PLEX_URL to its container name, such as http://plex:32400.

⁠2. Start it

In the folder with compose.yml:

mkdir -p ./data && sudo chown 1000:1000 ./data
docker compose up -d

Posteryard runs as user 1000 and writes only to ./data and /tmp.

⁠Without Compose

mkdir -p ./data && sudo chown 1000:1000 ./data
docker run -d --name posteryard --restart unless-stopped \
  --init --read-only --tmpfs /tmp --cap-drop ALL \
  --security-opt no-new-privileges:true \
  -e TMDB_API_KEY=your-tmdb-api-key \
  -e PLEX_URL=http://192.168.1.10:32400 \
  -e PLEX_TOKEN=your-plex-token \
  -e WEBHOOK_SECRET=any-long-random-text \
  -e TZ=America/New_York -e DRY_RUN=true \
  -v ./data:/data -p 8000:8000 \
  sandobserver/posteryard:latest

To go live, run docker rm -f posteryard and the same command with DRY_RUN=false.

⁠3. Check the preview

Plex is not changed yet. Posteryard saves each poster to data/previews, such as 5646-poster.jpg. Open a few to check them. docker logs -f posteryard shows progress.

⁠4. Go live

When you like them, change DRY_RUN=true to false in compose.yml and run docker compose up -d again. Posteryard uploads the images and locks them, so a Plex refresh keeps them.

Two more steps are worth it:

• New titles right away. With Plex Pass, add http://SERVER-IP:8000/webhook/YOUR-WEBHOOK-SECRET under Settings > Webhooks. Without it, new titles get posters within 15 minutes.
• One poster tool at a time. Turn off poster overlays in other tools, such as Kometa, or the two overwrite each other.

⁠Image tags

Every tag is built for linux/amd64 and linux/arm64. The same image is on ghcr.io/sandobserver/posteryard⁠. Release notes are on GitHub Releases⁠.

⁠Unraid

Open Apps, search for Posteryard and choose Install. Fill in the TMDB API key, the Plex URL and token, and a webhook secret. Previews land in /mnt/user/appdata/posteryard/previews. The webhook port is 8098. Use it in place of 8000 in every webhook address, such as http://UNRAID-IP:8098/webhook/YOUR-WEBHOOK-SECRET for Plex. The template runs as Unraid's nobody user (--user=99:100) with the same lockdown as the compose file, and restarts the container after a crash.

To go live, open the container's Edit screen, set Dry Run to false and choose Apply. The container's Logs show progress.

If Apps does not list Posteryard yet, save the template from the Unraid terminal, then pick Posteryard under Docker, Add Container, Template:

curl -fsSL -o /boot/config/plugins/dockerMan/templates-user/my-Posteryard.xml \
  https://raw.githubusercontent.com/SandObserver/Posteryard/main/templates/posteryard.xml

⁠Settings

Every setting except the first four has a default. Add a line under environment: only to change one. The landing page⁠ builds these lines for you.

⁠Change a poster

Run a command in the container, naming the title the way Plex shows it:

docker exec posteryard posteryard art next The Office

art next switches to the next best art. art set uses your own image, and why shows why a picture was picked. You can also add a label in Plex, such as posteryard-ignore. See Commands and labels⁠.

⁠Documentation

• Commands and labels⁠: change, reset or skip a poster.
• Jellyfin and Emby⁠: setup and differences from Plex.
• How it works⁠: what each image looks like, where the art comes from, when it runs, and what it changes.
• Alerts and monitoring⁠: notifications, health check and Uptime Kuma.
• Troubleshooting⁠: log messages and what to do.
• Upgrade, back up, uninstall⁠

⁠Contributing

See CONTRIBUTING.md⁠ for setup, checks and releases. Changes are listed in CHANGELOG.md⁠.

⁠Credits

Artwork and metadata come from TMDB⁠, and with FANART_API_KEY also from fanart.tv⁠. Posteryard uses TMDB and the TMDB APIs but is not endorsed, certified, or otherwise approved by TMDB. Streaming availability comes from JustWatch⁠ through TMDB. Service and Dolby marks: see assets/marks-src/SOURCES.md⁠. Fonts, all under the SIL Open Font License: Inter, and for other scripts Vazirmatn (Persian, Arabic), Pretendard (Korean, Japanese) and Noto Sans (Chinese, Hebrew, Thai, Devanagari); licences in src/posteryard/assets/fonts/.

⁠License

Apache License 2.0⁠. See NOTICE⁠ for the name, the logo and third-party assets.