Skip to main content

Requirements and compatibility

What you need to run PlexSub​

PlexSub is designed to run as a self-hosted application with Docker Compose. The public project template uses two services:

  • app: the PlexSub application.
  • db: PostgreSQL.

The reference files are:

  • docker-compose.example.yml
  • .env.example
  • Dockerfile

Docker and Docker Compose​

PlexSub is deployed with Docker Compose.

Typical commands:

docker compose pull
docker compose up -d
docker compose ps

The public guide recommends copying docker-compose.example.yml and .env.example into a runtime folder outside the source-code checkout.

PostgreSQL​

The current template uses PostgreSQL:

  • Default image: postgres:18.4-alpine
  • Image variable: PLEXSUB_POSTGRES_IMAGE_REF
  • Data volume: plexsub_postgres_data
  • Mounted path inside the container: /var/lib/postgresql

Important:

  • Do not change PostgreSQL major versions by recreating the container on the same volume.
  • Before a major upgrade, create a backup and test restoring it.
  • When migrating from an earlier PostgreSQL version, treat it as a controlled dump/restore operation or equivalent.

Minimum resources​

The project does not publish a fixed minimum-requirements table by number of users. docker-compose.example.yml does define recommended limits and reservations for its sample deployment:

ServiceCPU reservationCPU limitRAM reservationRAM limit
app1 CPU2 CPU512 MB1 GB
db0.5 CPU1 CPU256 MB512 MB

In practice:

  • For a small installation, use at least the resources reserved by the template.
  • Leave extra capacity when you enable many integrations, history queries, searches, or download modules.
  • Keep enough free storage for PostgreSQL, backups, and uploads.

Supported architecture​

The Dockerfile uses Node 24 Alpine and PostgreSQL Alpine images. The repository does not publish an official CPU architecture matrix.

  • Use an architecture supported by the Docker images you plan to run.
  • Confirm that the image digest you pin exists for your platform.
  • On a NAS, Unraid, ARM, or less common hardware, validate first with docker compose pull and docker compose up -d.

Node runtime​

The codebase declares:

  • Node.js: >=24.0.0 <25.0.0
  • Runtime image: node:24-alpine

For local development, use Node 24. Docker is the recommended production path.

Browsers​

PlexSub is a modern web application with a React frontend. Use a current version of Chrome, Edge, Firefox, or Safari. Avoid outdated browsers and WebViews; if you see a visual issue, first try an up-to-date desktop browser.

Network and ports​

By default:

  • The application listens on port 5000 inside the container.
  • The template exposes ${PORT:-5000}:5000.
  • The public demo compose binds 127.0.0.1:${DEMO_PORT:-5001}:5000.

When exposing PlexSub to the internet:

  • Use HTTPS.
  • Configure APP_BASE_URL accurately.
  • Set TRUST_PROXY_LEVEL only when a trusted proxy is in front of PlexSub.
  • Keep FORCE_SECURE_COOKIES=1.