tmcrage904/voterr repository overview

⁠Voterr

A film voting platform for movie nights that integrates with your Plex ecosystem. Vote on movies, track who's watched what, and organize recurring movie nights with friends.

⁠Links

• Docker Hub⁠
• GitHub Repository⁠

⁠Screenshots

Dashboard	Group	Movie Night

⁠Features

• Plex OAuth authentication
• Import Plex users and create local users for guests
• Create groups for different friend circles
• Recurring and one-off movie night schedules
• Nominate movies via Overseerr or TMDB search
• Vote on nominations with watch history tracking via Tautulli
• Guest access via shareable invite links
• Host assignment with veto power
• Attendance tracking

⁠Requirements

• Docker
• Plex Media Server with Plex Pass (for OAuth)
• Overseerr or TMDB API key (for movie search) - optional
• Tautulli (for watch history) - optional

⁠Quick Start

docker run -d --name voterr -p 5056:5056 -v ./voterr-data:/app/data tmirage/voterr:latest

Open http://localhost:5056 and complete the setup wizard to configure Plex and other services.

⁠Getting API Keys

⁠Tautulli API Key

1. Go to Tautulli Settings
2. Navigate to Web Interface
3. Copy the API Key

⁠Overseerr API Key

1. Go to Overseerr Settings
2. Navigate to General
3. Copy the API Key

⁠TMDB API Key

1. Create account at themoviedb.org
2. Go to Settings > API
3. Request an API key

⁠Development

⁠Prerequisites

• Node.js 20+
• npm

⁠Setup

# Install dependencies
npm install
cd client && npm install && cd ..

# Start development servers
npm run dev

This starts the frontend dev server with hot reload on http://localhost:5173, which proxies API requests to the backend on port 5056.

In production (Docker), the backend serves the built frontend directly on a single port.

⁠Project Structure

voterr/
├── client/                 # React frontend
│   ├── src/
│   │   ├── components/     # Reusable components
│   │   ├── context/        # React context (auth)
│   │   ├── lib/            # Utilities (API client)
│   │   └── pages/          # Page components
│   └── ...
├── server/                 # Express backend
│   ├── db/                 # Database setup
│   ├── middleware/         # Express middleware
│   ├── routes/             # API routes
│   └── services/           # External service integrations
├── data/                   # SQLite database (created at runtime)
├── docker-compose.yml
├── Dockerfile
└── package.json

⁠API Endpoints

⁠Authentication

• GET /api/auth/plex - Initiate Plex OAuth
• GET /api/auth/plex/callback - Check Plex auth status
• GET /api/auth/me - Get current user
• POST /api/auth/logout - Logout

⁠Users

• GET /api/users - List all users
• GET /api/users/plex-friends - Get importable Plex friends
• POST /api/users/import-plex - Import a Plex user
• POST /api/users/local - Create a local user
• DELETE /api/users/:id - Delete a user

⁠Groups

• GET /api/groups - List user's groups
• GET /api/groups/:id - Get group details
• POST /api/groups - Create a group
• POST /api/groups/:id/members - Add members
• DELETE /api/groups/:id/members/:userId - Remove member
• DELETE /api/groups/:id - Delete group

⁠Schedules

• GET /api/schedules/group/:groupId - List group schedules
• POST /api/schedules - Create a schedule
• DELETE /api/schedules/:id - Delete a schedule
• GET /api/schedules/movie-nights/group/:groupId - List movie nights
• GET /api/schedules/movie-nights/:id - Get movie night details
• PATCH /api/schedules/movie-nights/:id - Update movie night
• POST /api/schedules/movie-nights/:id/attendance - Set attendance

⁠Movies

• GET /api/movies/library - Get movies from Overseerr
• GET /api/movies/search?q=term - Search movies
• GET /api/movies/:tmdbId - Get movie details

⁠Votes

• GET /api/votes/movie-night/:id - Get nominations with votes
• POST /api/votes/nominate - Nominate a movie
• DELETE /api/votes/nominations/:id - Remove nomination
• POST /api/votes/vote - Vote for a nomination
• DELETE /api/votes/vote/:nominationId - Remove vote
• POST /api/votes/movie-night/:id/decide - Pick winner (host/admin)

⁠Invites

• POST /api/invites/create - Create guest invite link
• GET /api/invites/validate/:token - Validate invite
• POST /api/invites/guest-login - Login as guest via invite
• GET /api/invites/movie-night/:id - List invites for movie night
• DELETE /api/invites/:id - Delete invite

⁠Configuration

All settings (Plex, Tautulli, Overseerr, TMDB) are configured through the web UI. Session secrets are auto-generated and stored in the database.

⁠Security

• Session secrets are auto-generated on first run and stored in the database
• Cookies automatically use secure: true when accessed via HTTPS (auto-detected via X-Forwarded-Proto header)
• All API endpoints require authentication except health check and setup status
• CSRF protection on all POST/PUT/DELETE requests
• Rate limiting on invite link validation (5 requests/minute per IP)
• Rate limiting on PIN attempts (5 failures = 1 minute lockout per IP)
• Groups can require a 6-digit PIN for invite links
• Local invite users can only access their specific movie night
• Image uploads restricted to authenticated non-guest users
• All SQL queries use parameterized statements (no SQL injection)

⁠Docker Installation

⁠Using Pre-built Image (Recommended)

docker run -d \
  --name voterr \
  -p 5056:5056 \
  -v ./voterr-data:/app/data \
  tmirage/voterr:latest

That's it! Open http://localhost:5056 and complete the setup wizard to configure Plex and other services.

⁠Docker Compose

services:
  voterr:
    image: tmirage/voterr:latest
    container_name: voterr
    restart: unless-stopped
    ports:
      - "5056:5056"
    volumes:
      - ./voterr-data:/app/data

⁠Supported Architectures

The Docker image is built for multiple platforms:

• linux/amd64 - Standard x86_64 servers
• linux/arm64 - Raspberry Pi 4, Apple Silicon, ARM servers

⁠License

MIT