cueplex/cueplex repository overview

⁠CuePlex

Self-hosted Plex media discovery and request app — browse TMDB, request movies/TV, sync Plex availability, and route approvals to Radarr/Sonarr. The web UI and API ship in this single image; it needs a PostgreSQL container (included below).

⁠Quick start

1. Create a .env next to your compose file with the one required value:

   DB_PASSWORD=replace_with_a_strong_password
   

   Copy

2. Create docker-compose.yml:

   services:
     cueplex-db:
       image: postgres:15-alpine
       restart: unless-stopped
       environment:
         POSTGRES_DB: cueplex
         POSTGRES_USER: cueplex
         POSTGRES_PASSWORD: ${DB_PASSWORD}
       volumes:
         - cueplex-db-data:/var/lib/postgresql/data
       networks: [cueplex-internal]
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U cueplex -d cueplex"]
         interval: 10s
         timeout: 5s
         retries: 5
   
     cueplex:
       image: cueplex/cueplex:latest
       pull_policy: always
       restart: unless-stopped
       depends_on:
         cueplex-db:
           condition: service_healthy
       environment:
         DATABASE_URL: postgresql+asyncpg://cueplex:${DB_PASSWORD}@cueplex-db:5432/cueplex
         ENVIRONMENT: production
       volumes:
         - cueplex-data:/data
       networks: [cueplex-internal]
       extra_hosts:
         - "host.docker.internal:host-gateway"
       healthcheck:
         test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8002/health')"]
         interval: 30s
         timeout: 5s
         retries: 3
         start_period: 20s
       ports:
         - "${FRONTEND_PORT:-7474}:7474"
   
   volumes:
     cueplex-db-data:
     cueplex-data:
   
   networks:
     cueplex-internal:
       driver: bridge
   

   Copy

3. Start and open the app:

   docker compose up -d
   

   Copy

   Then visit http://localhost:7474 and follow the setup wizard.

⁠Connecting Plex / Radarr / Sonarr

You enter these URLs in the setup wizard. CuePlex must reach them from inside the container:

• Services on the Docker host: http://host.docker.internal:<port> (Plex 32400, Radarr 7878, Sonarr 8989).
• If a service runs in its own Docker network — or Plex only listens on 127.0.0.1:32400 — add that network to the cueplex service and use the container name, e.g. http://Plex:32400.

⁠Optional settings

All optional, set under the cueplex service environment::

• FRONTEND_PORT — host port for the UI (default 7474)
• SECRET_KEY — JWT signing secret (auto-generated in /data if unset)
• TMDB_API_KEY — your own TMDB key (a bundled key is used otherwise)
• VAPID_CONTACT_EMAIL — contact identity for web-push notifications

⁠Update

docker compose pull && docker compose up -d

⁠Data & backup

App data lives in two volumes: cueplex-db-data (PostgreSQL) and cueplex-data (generated app data, including the secret key). Back up the database before removing volumes:

docker compose exec -T cueplex-db pg_dump -U cueplex cueplex > cueplex_backup.sql

⁠Troubleshooting

A 502 after startup is almost always because DB_PASSWORD was changed after the database volume already existed — PostgreSQL only applies the password on first init. Check logs with docker compose logs cueplex.

Any Issues or feedback/feature requests feel free to leave at my github⁠ page