Plex integration

Purpose

Plex is marked as a required module in PlexSub's service registry. It manages identity, access, libraries, activity, history, downloads, and data shown in the Customer Portal.

It appears in PlexSub at:

• Admin: /plex-users
• Customer Portal: general status, downloads, playback history, and usage

Requirements

• A Plex server reachable from PlexSub.
• A valid Plex token.
• Libraries configured in Plex.
• Connectivity from the app container to the Plex server URL.

Related variables:

• PLEX_SERVER_URL
• PLEX_TOKEN
• PLEX_ALLOWED_LIBRARIES

It can also be configured from Settings > Services when the installation uses encrypted credentials stored in the database.

Recommended configuration

1. Confirm Plex works outside PlexSub.
2. Set the URL PlexSub uses to reach the server.
3. Configure a token with sufficient permissions.
4. Limit libraries if you do not want to expose the entire server.
5. Save the configuration in PlexSub.
6. Run the service diagnostic.

Troubleshooting

Symptom	Likely cause	Resolution
Plex is not configured	URL or token missing	Check Settings > Services or .env.
PlexSub cannot connect	URL unreachable from Docker	Test connectivity from the host and check network/proxy settings.
Libraries do not appear	Insufficient token permissions or disallowed libraries	Check the token and PLEX_ALLOWED_LIBRARIES.
History or artwork does not load	Plex or analytics provider does not respond	Check Plex, Tracearr/Tautulli, and application logs.

Privacy

The Plex token is sensitive; do not share it. PlexSub encrypts service credentials configured from Admin Settings, but APP_SETTINGS_ENCRYPTION_KEY must be kept outside Git and outside the database.