Swiparr 🍿

Discover what to watch next, by yourself or together.

Swiparr turns the dreaded "what should we watch?" question into a fun, collaborative experience.
Like Tinder for movies, but smarter and works for groups.

🎯 The Problem

The struggle is real: 30 minutes of "what should we watch?" that ends with watching the same show again. Swiparr fixes this by:

✨ Turning discovery into a fun, game-like experience
🤝 Finding content everyone actually wants to watch
⚡ Making group decisions in minutes, not hours
🌍 Working with your existing media libraries OR standalone

✨ Features

🎬 Content Discovery

• Intuitive Swipe Interface - Browse movies with a familiar card-based design
• Multi-Provider Support - Works with Jellyfin, Emby, Plex, or TMDB directly
• Smart Matching - Automatically finds content everyone in your group will enjoy
• Mobile-First - Optimized for phones, with desktop keyboard shortcuts
• PWA Ready - Install as a web app for the best experience

👥 Built for Groups

• Instant Sessions - Create or join in seconds, no complex setup
• Flexible Match Rules - Choose "any two people" or "everyone must agree"
• Session Controls - Limit likes, dislikes, or total matches
• Watchlist Sync - Seamlessly save favorites back to your media server

🔧 Universal Compatibility

• Jellyfin - Full native integration
• Emby - Experimental support (improving)
• Plex - Experimental support (improving)
• TMDB - No media server required, works standalone

🚀 Quick Start

Fastest: Swiparr Global

No setup, no server, no problem.

🌐 swiparr.com - Free to use, community-supported (hopefully)

Easiest: Deploy to Vercel

One-click deployment, perfect for personal or small group use:

Note: The automatic deployment workflow in Vercel uses the Turso integration by default as a database service provider. Free to set up, possible to swap out ¹.

Vercel security note: AUTH_SECRET is auto-generated during the build (via scripts/ensure-auth-secret.cjs) and persisted in the database when not provided.

Full Control: Self-Host with Docker

Using Docker Compose (Recommended):

1. Create docker-compose.yml:

services:
  swiparr:
    image: ghcr.io/m3sserstudi0s/swiparr:latest
    container_name: swiparr
    restart: unless-stopped
    environment:
      - PROVIDER=jellyfin  # or plex, emby, tmdb (or set PROVIDER_LOCK to "false")
      - JELLYFIN_URL=http://your-jellyfin:8096 # adjust to provider, none without server lock
    volumes:
      - ./swiparr-data:/app/data
    ports:
      - 4321:4321

2. Run it:

docker compose up -d

Using Docker CLI:

docker run -d \
  --name swiparr \
  --restart unless-stopped \
  -p 4321:4321 \
  -v $(pwd)/swiparr-data:/app/data \
  -e PROVIDER=jellyfin \
  -e JELLYFIN_URL=http://your-jellyfin:8096 \
  ghcr.io/m3sserstudi0s/swiparr:latest

3. Open http://localhost:4321

Docker security note: AUTH_SECRET is auto-generated on first boot (via scripts/ensure-auth-secret.cjs) and stored in the database when not provided.

⚙️ Configuration Reference

Provider-Specific Settings

Choose one provider setup based on your needs:

PROVIDER=jellyfin
JELLYFIN_URL=http://your-jellyfin:8096              # Internal URL (required)
JELLYFIN_PUBLIC_URL=https://jellyfin.example.com    # Public URL (optional)
JELLYFIN_USE_WATCHLIST=false                         # Use Watchlist (plugin needed) vs Favorites (optional)

PROVIDER=emby
EMBY_URL=http://your-emby:8096        # Internal URL (required)
EMBY_PUBLIC_URL=https://emby.example.com  # Public URL (optional)

PROVIDER=plex
PLEX_URL=http://your-plex:32400       # Internal URL (required)
PLEX_PUBLIC_URL=https://plex.example.com # Public URL (optional)

PROVIDER=tmdb
TMDB_ACCESS_TOKEN=your-tmdb-token     # API Read-Only Token (required)
TMDB_DEFAULT_REGION=SE                # Default region for availability/certifications (optional)

Security & Advanced Options

# Authentication
AUTH_SECRET=random-string-32-chars-min     # Auto-generated on boot/build when not provided. See Security & Privacy.
USE_SECURE_COOKIES=true                    # Required for HTTPS

# Application
PORT=4321                                  # Default port
HOSTNAME=0.0.0.0                          # Bind address
DATABASE_URL=file:/app/data/swiparr.db    # SQLite path or Turso URL
DATABASE_AUTH_TOKEN=your-token            # Required for Turso/Remote DB

# Base path (build-time only — see Custom Base Path section)
# URL_BASE_PATH=/swipe

# Admin
ADMIN_USERNAME=your-username                      # Global auto-grant admin privileges
JELLYFIN_ADMIN_USERNAME=jelly-admin               # Provider-specific admin (overrides global)
PLEX_ADMIN_USERNAME=plex-admin                   # Provider-specific admin (overrides global)
EMBY_ADMIN_USERNAME=emby-admin                   # Provider-specific admin (overrides global)

# Security Headers
X_FRAME_OPTIONS=DENY                       # Frame control
CSP_FRAME_ANCESTORS=none                   # Embedding policy

# Network Safety
ALLOW_PRIVATE_PROVIDER_URLS=false          # Block private/LAN URLs for user-supplied providers (BYOP)
PLEX_IMAGE_ALLOWED_HOSTS=plex.example.com,*.plex.direct  # Optional extra image hosts

# BYOP Mode - Bring Your Own Provider
PROVIDER_LOCK=false                          # Let users choose and configure their own provider

# Misc
USE_ANALYTICS=false                          # Enable anonymous usage analytics (Vercel deployments)
ENABLE_DEBUG=false                           # Enable verbose debug logging and client-server error mapping
USE_STATIC_FILTERS=false                     # Skip dynamic filter fetching; use built-in genre/year/rating lists instead (useful for very large libraries where filter API calls time out)

Environment Variable Matrix

✳️ = Required conditionally

Features (Deep dive)

Session Settings

When you create a session, customize it for your group:

🔄 Provider Flexibility: Two Modes

Server Lock Mode

PROVIDER_LOCK=true

One provider, admin-controlled

• Admin configures ONE provider in environment variables
• All users automatically use this provider
• Best for: Families, roommates, shared media servers

BYOP Mode

PROVIDER_LOCK=false

Bring Your Own Provider

• Each user connects their own provider during onboarding
• Users can switch providers anytime
• Best for: Users with different media servers, and/or you have none

🔒 Security & Privacy

• Generating AUTH_SECRET (optional):

# macOS and Linux
openssl rand -base64 32

Windows users can use https://generate-secret.vercel.app/32.

• Encrypted Sessions: iron-session with secure, encrypted cookies
• Encrypted Guest Lending Tokens: host access tokens are encrypted at rest when Guest Lending is enabled
• Scoped Access: Guests can only swipe, no account access
• Data Ownership: Self-hosted = your data stays on your server
• Provider Isolation: No credential sharing in BYOP mode
• CORS Protection: Configured for safe media server integration
• Security Headers: X-Content-Type-Options, X-XSS-Protection, CSP, Referrer-Policy
• Network Safety: Private/LAN provider URLs are blocked by default; enable via ALLOW_PRIVATE_PROVIDER_URLS
• Mode Awareness: Env-configured providers are trusted when PROVIDER_LOCK=true; user-supplied URLs are checked

🤝 Contributing

Swiparr is now open for contributions! 🎉

How to Contribute

1. Start with Discussion - Propose changes before coding
   • 💡 Ideas & Feature Proposals
   • 🐛 Bug Reports
2. Fork & Develop - After discussion approval
3. Pull Request - With clear description and tests

Development Setup

git clone https://github.com/m3sserstudi0s/swiparr.git
cd swiparr
npm install
npm run dev          # Start dev server
npm run lint         # Check code style

Contribution Areas

• Provider Integrations: Improve Emby/Plex support
• UI/UX: Mobile responsiveness, accessibility
• Performance: Optimize queries, bundle size
• Documentation: Examples, guides, tutorials
• Testing: Add test coverage (currently minimal)

First-time contributors welcome! Start with "good first issue" discussions.

💚 Support the Project

Swiparr is free, open source, and community-supported. Your contributions help:

• ☕ Buy Me a Coffee - Quick one-time support
• 🌟 Star on GitHub - Show your support (it's free!)
• 🏢 Use swiparr.com - The hosted version includes infrastructure funding

All support directly funds development and infrastructure costs.

📞 Community & Support

All support, questions, and discussions happen in GitHub Discussions:

🐳 Docker Advanced Topics

Custom Base Path

If you want to serve Swiparr under a subpath — e.g. https://jellyfin.example.com/swipe/ — you need to set URL_BASE_PATH at image build time, not as a runtime environment variable.

Why? Next.js bakes asset URLs (/_next/static/...) into the compiled output at build time. Setting a base path only at runtime can fix page routing but leaves all JS/CSS/image references pointing at the wrong path, breaking the app. The prefix must be known before the build.

The prebuilt image from ghcr.io does not support URL_BASE_PATH — it is built without a base path. You must build your own image.

If you are not using compose and want to build the image

git clone https://github.com/m3sserstudi0s/swiparr.git
cd swiparr
docker build --build-arg URL_BASE_PATH=/swipe -t swiparr-custom .

Then use swiparr-custom as your image name in your docker run command.

If you are using compose, compose can build and manage the image for you at runtime

services:
  swiparr:
    pull_policy: build
    build:
      context: https://github.com/m3sserstudi0s/swiparr.git
      args:
        URL_BASE_PATH: /swipe
    container_name: swiparr
    restart: unless-stopped
    environment:
      - JELLYFIN_URL=http://jellyfin:8096
      - URL_BASE_PATH=/swipe       # must match the --build-arg value exactly
    volumes:
      - ./swiparr-data:/app/data
    ports:
      - 4321:4321

URL_BASE_PATH must also be passed as a runtime environment variable so the app generates correct internal links and auth redirects. It must match the --build-arg value exactly.

Step 3 — Configure your reverse proxy

Forward requests for the subpath to the container. The app handles stripping the prefix internally — do not strip it in the proxy.

Nginx:

location /swipe {
    proxy_pass http://swiparr:4321;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Traefik (Docker labels):

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.swiparr.rule=Host(`jellyfin.example.com`) && PathPrefix(`/swipe`)"
  - "traefik.http.routers.swiparr.tls=true"

Caddy:

handle /swipe* {
    reverse_proxy swiparr:4321
}

Reverse Proxy Configuration (root path)

Nginx Example:

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

Required Headers:

• Host - Required for authentication
• X-Forwarded-For - Client IP for logging
• X-Forwarded-Proto - Protocol detection

Volume Management

volumes:
  - ./data:/app/data          # Database & cache
  - ./logs:/app/logs          # Optional: Persist logs

Environment File

Use --env-file .env with Docker for cleaner configuration management.

📚 Additional Resources

• AGENTS.md - Developer guide and code standards (for contributors)
• GitHub Releases - Detailed changelog for each version

📄 License

MIT License - See LICENSE file for details

You're free to use, modify, and distribute Swiparr. Commercial use is permitted.