| name | setup-app |
| description | Set up and run the Plex Collection Creator web app (Docker or local dev), connect it to a Plex server, choose libraries, and add an AI provider key. Use when a user wants to install, start, or configure the original web application for the first time. |
Set up the Plex Collection Creator web app
Goal: get the Next.js web app running and connected so the user can generate AI
collection suggestions in the browser.
1. Check prerequisites
- Docker (recommended path):
docker --version and docker compose version.
- Local dev path: Node 22+ (
node -v; the repo standardizes on 22 via
.nvmrc / engines). Some very new Node releases can fail to build the native
better-sqlite3 dependency — see [[setup-mcp]] for the same caveat.
Ask which path they want if it's unclear. Default to Docker.
2. Start the app
Docker:
docker compose up -d --build
The app is served at http://localhost:32500 (container port 3000). Data
(SQLite + encryption key) persists in the plex-collections-data volume.
Local dev:
npm install
npm run dev
Optional: set ENCRYPTION_KEY (generate with openssl rand -hex 32) in
.env / docker-compose.yml for a stable key across rebuilds. If omitted, one
is auto-generated and stored in the data volume.
3. Walk the user through the setup wizard
Open the app and complete the three steps in the UI:
- Connect to Plex — click connect, sign in via the Plex OAuth popup. The
token is stored encrypted locally.
- Choose libraries — select the Movie / TV libraries to manage.
- Add an AI key — pick a provider (Anthropic, OpenAI, Bedrock, or Vertex)
and paste the key. Keys can also be supplied via env vars (see
.env.example).
4. Verify
- The dashboard shows the connected server and selected libraries.
- Run a scan, then "Generate" to confirm suggestions appear.
Troubleshooting
- Port in use: change the host port mapping in
docker-compose.yml.
- Plex won't connect: ensure the server is reachable and the popup wasn't
blocked; retry the connect step.
- better-sqlite3 build fails (local dev): use the Node version in
.nvmrc
(nvm use), or use the Docker path.
Once the app works, offer [[setup-mcp]] so they can also drive Plex from
Claude Code.
