Messer-Swipe
Docker app from grtgbln's Repository
Messer Swipe is a fun way to discover and decide what to watch next from your Jellyfin media library.
Requirements
Requires a separate Jellyfin instance.
Overview
Readme
View on GitHub
Swipe on what to watch next, alone or with a group.
MIT · Next · SQLite · v2.0.0 · ghcr.io/jakobbjelver/messer-swipe
Swipe turns "what should we watch?" into a deck everyone can agree on. One person creates a session, the others join from a phone, and the app finds the titles two people liked — or that everyone did.
It works with the media server you already run (Jellyfin, Plex, Emby) or standalone against TMDB, with no server at all. Mobile-first, installable, and it keeps its own tiny SQLite database of sessions, swipes and matches.
Run
docker run -d \
--name messer-swipe \
--restart unless-stopped \
-p 4321:4321 \
-v "$PWD/messer-swipe-data:/app/data" \
-e PROVIDER=jellyfin \
-e JELLYFIN_URL=http://your-jellyfin:8096 \
ghcr.io/jakobbjelver/messer-swipe:latest
Then open http://localhost:4321. Or build it yourself: npm ci && npm run build && npm start after
npm run db:migrate (make docker builds the image the CI publishes).
AUTH_SECRET is generated on first boot and stored beside the database when unset; set it explicitly if
you run more than one replica. For HTTPS set USE_SECURE_COOKIES=true and APP_PUBLIC_URL to the
hostname that serves the app — it drives canonical URLs, the OG image, robots.txt and secure cookies.
A hosted demo runs at swipe.messer.wtf in TMDB mode. One-click deploy to Vercel: clone with the Turso integration.
What it does
| Providers | Jellyfin and TMDB are the supported pair; Emby and Plex are experimental |
| Shows | series cards with seasons, episodes and the commitment numbers; a detail sheet that answers "where do I start" |
| Deck modes | movies, shows, whole shows or single episodes, what you are already watching, or both kinds mixed |
| Sessions | create or join in seconds from a link; no account for a guest |
| Match rules | "any two people" or "everyone must agree" |
| Session limits | cap likes, dislikes or total matches so a session ends |
| Watchlist sync | a match is written back to the media server you already use |
| Mobile | phone-first deck, installable as a PWA, keyboard shortcuts on a desktop |
| Standalone | TMDB mode needs no media server and no library |
Two provider modes. Server lock (PROVIDER_LOCK=true, the default) fixes the provider from the
environment: one server, one library, nothing to configure in the UI. BYOP (PROVIDER_LOCK=false) lets
each visitor point the app at their own server at runtime — private or LAN URLs stay refused unless you
set ALLOW_PRIVATE_PROVIDER_URLS=true.
The variables that matter most:
| Variable | Default | |
|---|---|---|
PROVIDER |
jellyfin |
jellyfin, plex, emby or tmdb |
PROVIDER_LOCK |
true |
false lets a visitor choose their own provider |
JELLYFIN_URL / PLEX_URL / EMBY_URL |
— | the server the app reads from |
TMDB_ACCESS_TOKEN |
— | required for PROVIDER=tmdb |
DATABASE_URL |
file:/app/data/swiparr.db |
a SQLite path, or a Turso URL with DATABASE_AUTH_TOKEN |
APP_PUBLIC_URL |
swipe.messer.wtf |
canonical host; set it to yours |
AUTH_SECRET |
generated | session and guest-lending keys, ≥ 32 chars |
USE_SECURE_COOKIES |
false |
true behind HTTPS |
MAX_IMAGE_WIDTH |
960 |
largest poster the client asks for |
The full matrix — including the image queue, security headers and admin usernames — is in
docs/configuration.md; what each deck mode does is in
docs/features.md. Upgrading from 1.x? Read docs/upgrading-to-2.0.md
first: it covers the one stored change (TMDB ids are typed in 2.0) and how to roll back.
Contract
The app is a Next.js server with route handlers under /api: auth, session, swipe, media,
user, events (SSE for a live session), admin, og, health and version. Every failure answers
the same envelope, {"error":{"code","message"}}, and GET /api/version reports the build.
Sessions are the unit of state: a session owns its members, its swipes and its matches, and the deck is computed per member from the provider's catalogue. There is no accounts system — a member is a name and a signed cookie, and the admin is the first account that logs in on a provider that has accounts at all.
Agents
Read AGENTS.md — the code contract, the invariants and the commands — then
docs/llms.txt, the primer for an agent that is about to change code. npm run check
(lint, typecheck, tests) is the gate; npm run doctor diagnoses a deployment; npm run e2e drives the
contract against a running instance.
To operate an instance with an agent rather than change its code, see docs/agents.md:
the CLI ships inside the image, so docker exec <container> messer-swipe status is the whole setup.
Contributions are closed: no pull requests. Issues and discussions are open — bug reports and ideas
are read, and a bug with a reproduction gets fixed. A vulnerability goes to a private advisory, per
SECURITY.md.
Design notes
The deck is a view, not a table. Nothing is precomputed per user: the deck is a page of the provider's catalogue filtered by what this member has already swiped. A session with 40 members costs one query per member, not 40 tables.
A match is a rule, not a majority. "Any two" and "everyone" are the two rules that make group watching actually work; a match record names the rule that produced it, so a surprising match is explainable.
One image budget. Posters are fetched through the app, not hot-linked from the server, because a
slow media server must not make the deck feel broken: the queue is bounded by IMAGE_CONCURRENCY, each
fetch has a timeout, and a failure is a 504 the card retries — never a cached broken image.
Status
Active. The supported path is Jellyfin and TMDB; Emby and Plex work and are labelled experimental because their libraries differ in ways that still surprise the deck.
License
MIT. Not accepting pull requests — see CONTRIBUTING.md. Bug reports go to issues,
security to a private advisory.
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/jakobbjelver/messer-swipe:latestRuntime arguments
- Web UI
http://[IP]:[PORT:4321]/- Network
bridge- Privileged
- false
Template configuration
Container Port: 4321
- Target
- 4321
- Default
- 4321
- Value
- 4321
Internal URL to your Jellyfin server.
- Target
- JELLYFIN_URL
- Default
- http://IP_ADDRESS:8096
- Value
- http://IP_ADDRESS:8096
(Optional) Public URL to your Jellyfin server. Defaults to the internal URL if not set.
- Target
- JELLYFIN_PUBLIC_URL
Set to true to use Watchlist instead of Favorites
- Target
- JELLYFIN_USE_WATCHLIST
- Default
- false|true
Set to true if accessing Messer Swipe over HTTPS
- Target
- USE_SECURE_COOKIES
- Default
- false|true
(Optional) A Jellyfin username that will always have admin privileges.
- Target
- ADMIN_USERNAME
Random string (min 32 chars). Generated automatically if not set.
- Target
- AUTH_SECRET
Internal path to database. Not recommended to change.
- Target
- DATABASE_URL
- Default
- file:/app/data/swiparr.db
- Value
- file:/app/data/swiparr.db
Internal port Messer Swipe listens on. Not recommended to change.
- Target
- PORT
- Default
- 4321
- Value
- 4321
Internal host Messer Swipe binds to. Not recommended to change.
- Target
- HOSTNAME
- Default
- 0.0.0.0
- Value
- 0.0.0.0
X-Frame-Options header. Set to DISABLED to remove.
- Target
- X_FRAME_OPTIONS
- Default
- DENY
- Value
- DENY
Content-Security-Policy frame-ancestors directive.
- Target
- CSP_FRAME_ANCESTORS
- Default
- none
- Value
- none
Path to the application data folder
- Target
- /app/data
- Default
- /mnt/user/appdata/swiparr/data
- Value
- /mnt/user/appdata/swiparr/data
- Default
- 099
- Value
- 099
- Default
- 100
- Value
- 100