Skip to content
credenzaDocs

Installation

Credenza runs on anything that runs Docker, or directly on a Linux machine with systemd. Both installs are the same release with the same version numbers, so you can pick whichever suits the machine and switch later.

Docker Compose Linux package
Runs on Anything with Docker and Compose — a NAS, a home server, a VPS Debian 12+, Ubuntu 22.04+, Fedora, RHEL 9+ and its rebuilds, or any other glibc Linux with systemd
Architectures x86-64, ARM64 x86-64, ARM64
Database A second container, already set up Set up for you by credenza-setup, in Docker or in the machine’s own PostgreSQL
ffmpeg Included in the image A dependency of the .deb and .rpm; install it yourself with the tarball
Upgrades docker compose pull Run the install command again, or your package manager

Windows and macOS installers are coming soon.

What Credenza needs

Section titled “What Credenza needs”
  • A PostgreSQL database with three extensions — pgmq (the background job queue), pg_search (search) and pgvector (which pg_search depends on). No distribution ships that combination, so both install methods provide it for you: Compose runs a ready-made Postgres image, and the Linux installer either runs the same image in Docker or adds the extensions to a PostgreSQL you already have.
  • ffmpeg, which Credenza uses to read your files and to transcode anything a device cannot play directly. The Docker image carries its own; the .deb and .rpm packages pull in your distribution’s, and the tarball expects you to install it (and ICU, if your system lacks it).
  • Read access to your media, and write access if you want Credenza to save its small .credenza.json match files beside your media when you correct a match. It writes nothing else into your media folders.

The server listens on port 8080. Once it is running, open http://<your-server>:8080 in a browser and it walks you through first-run setup.

Docker Compose

Section titled “Docker Compose”

The server and its database run as two containers.

  1. Make a folder for Credenza and save this as docker-compose.yml inside it.

    docker-compose.yml
    services:
      credenza:
        image: credenza/credenza:${CREDENZA_VERSION:-latest}
        restart: unless-stopped
        user: "${PUID:?set PUID in .env}:${PGID:?set PGID in .env}"
        ports:
          - "8080:8080"
        environment:
          HOME: /data
          MediaServer__Database__ConnectionString: >-
            Host=postgres;Database=credenza;Username=credenza;Password=${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
        volumes:
          - ./data/credenza:/data
          # Your media, at the same path on both sides:
          # it is the path you give Credenza when you add a library.
          - /srv/media:/srv/media
        depends_on:
          postgres:
            condition: service_healthy
    

      postgres:
        image: credenza/postgres:18-pgmq1.12.0-pgsearch0.25.3
        restart: unless-stopped
        user: "${PUID:?set PUID in .env}:${PGID:?set PGID in .env}"
        environment:
          POSTGRES_DB: credenza
          POSTGRES_USER: credenza
          POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
        volumes:
          - ./data/postgres:/var/lib/postgresql
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U credenza -d credenza"]
          interval: 5s
          timeout: 3s
          retries: 30

    Change /srv/media:/srv/media to wherever your films, shows and games are. Keep the path the same on both sides of the colon: the path inside the container is the one you type when you add a library, so mounting /srv/media at /srv/media means the folder is called the same thing everywhere. Add one line per folder if your media is in several places.

  2. In the same folder, create an .env file with a database password and the account the containers should run as, make the data folders, and start everything:

    Terminal window
    echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" > .env
    echo "PUID=$(id -u)" >> .env
    echo "PGID=$(id -g)" >> .env
    mkdir -p data/credenza data/postgres
    docker compose up -d

  3. Visit port 8080 on the machine. The server asks for its administrator, its first libraries and a TMDB token — see First run.

Choosing PUID and PGID

Section titled “Choosing PUID and PGID”

Both containers run as the user and group ids in PUID and PGID. The commands above use your own account. If your media belongs to a different account — a media user, or a network share mounted with a fixed owner — set them to that account’s ids instead, so Credenza can read the files and write match files beside them.

Where your data lives

Section titled “Where your data lives”

Everything Credenza keeps is in the two folders you created beside docker-compose.yml:

Folder What is in it
data/credenza The artwork cache, game saves, the server’s log files and the keys that keep people signed in
data/postgres The database: your libraries, accounts, watch history and every setting made in the browser

Your media is never copied into either. Transcoding scratch files stay inside the container and are cleaned up as streams end. See Updating for what to back up.

Transcoding on the GPU

Section titled “Transcoding on the GPU”

This is optional. Credenza transcodes on the CPU out of the box, and uses a GPU only when it can reach one. To give it one, save the matching file below as docker-compose.override.yml next to docker-compose.yml and run docker compose up -d again. Settings → Server → Transcoding then shows which encoder it chose. See Hardware acceleration for how it decides.

Needs the NVIDIA Container Toolkit on the host. This also works on Windows under Docker Desktop.

docker-compose.override.yml
services:
  credenza:
    environment:
      NVIDIA_DRIVER_CAPABILITIES: compute,utility,video
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu, video]

Linux

Section titled “Linux”

One command installs Credenza as a systemd service:

Terminal window
curl -fsSL https://credenza.tv/install.sh | sh

You can read the script before running it. It:

  1. Installs the right package for your system — the .deb on Debian and Ubuntu, the .rpm on Fedora and RHEL, or a tarball on anything else with systemd — after checking it against the release’s checksums. Each package carries its own runtime, so nothing needs installing from Microsoft or compiling.
  2. Asks where the database should run, by starting sudo credenza-setup:
    • Docker (recommended) — a container with everything Credenza needs. If Docker is not installed, it offers to install it. Nothing else on the machine changes.
    • This machine’s PostgreSQL — it adds the three extensions to the PostgreSQL already running, or installs one first. This restarts PostgreSQL, which briefly disconnects anything else using it, and the script tells you before it asks. This option exists only where pg_search is published: Debian 12 and 13, Ubuntu 24.04 and 26.04, and RHEL 9 and 10 and their rebuilds, with PostgreSQL 15 to 18. Fedora, Ubuntu 22.04, Arch and anything else use Docker.
  3. Starts the server on port 8080. Open it in a browser to finish setting up.

It asks before installing or restarting anything, and running sudo credenza-setup again later is safe — use it to switch between the two database options or after upgrading PostgreSQL.

Unattended installs

Section titled “Unattended installs”

To answer the database question up front — for a script, or a machine you are not sitting at:

Terminal window
curl -fsSL https://credenza.tv/install.sh | sh -s -- --database docker --yes

Other options:

Option What it does
CREDENZA_VERSION=0.1.3 before sh Install that version rather than the latest
--no-setup Install the package only; run sudo credenza-setup yourself afterwards
--database docker or --database system Choose where the database runs without being asked
--yes Agree to anything setup would otherwise ask about

Without a terminal, setup never guesses: it needs --database, and anything it would ask about needs --yes.

Fedora, RHEL, Rocky and Alma

Section titled “Fedora, RHEL, Rocky and Alma”

Fedora’s default ffmpeg has no H.264 encoder, so anything that needs transcoding will not play. Swap it for RPM Fusion’s full build:

Terminal window
sudo dnf swap ffmpeg-free ffmpeg --allowerasing

RHEL, Rocky and Alma ship no ffmpeg at all. The installer stops and says so; enable EPEL and RPM Fusion, then run it again:

Terminal window
sudo dnf install epel-release
sudo dnf install https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-$(rpm -E %rhel).noarch.rpm
sudo crb enable

Letting the service read your media

Section titled “Letting the service read your media”

The server runs as a credenza system user, which needs to read your library folders — and write to them if you want match files saved beside your media. Usually that means adding it to the group that owns them:

Terminal window
sudo usermod -aG media credenza
sudo systemctl restart credenza

Replace media with whichever group owns your files. For hardware transcoding, the installer has already added the credenza user to the video and render groups where they exist; install your GPU’s VA-API driver (such as mesa-va-drivers or intel-media-va-driver) or NVIDIA’s driver as you would for ffmpeg itself.

Where things are

Section titled “Where things are”
Path What
/etc/credenza/credenza.env Configuration — see Configuration. Upgrades never overwrite it
/var/lib/credenza/ Game saves, the artwork cache and the keys that keep people signed in
/var/log/credenza/ The server’s log files, also readable at Settings → Server → Logs
/var/cache/credenza/ Transcoding scratch space; safe to delete while the server is stopped
Docker volume credenza-postgres The database, if it runs in Docker
/usr/lib/credenza/ (tarball: /opt/credenza/) The application itself

journalctl -u credenza shows the log as it happens.

A PostgreSQL on another machine

Section titled “A PostgreSQL on another machine”

If you want the database somewhere else entirely, it needs PostgreSQL 15 to 18 with pgmq, pg_search and pgvector installed and pg_search in shared_preload_libraries. Create a credenza role and database, then, as a superuser in that database:

CREATE EXTENSION pgmq CASCADE;
CREATE EXTENSION pg_search CASCADE;
GRANT USAGE, CREATE ON SCHEMA pgmq TO credenza;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA pgmq TO credenza;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA pgmq TO credenza;

Without the three grants the server starts, but background work — scanning included — never runs. Put the connection string in /etc/credenza/credenza.env and start the service with sudo systemctl enable --now credenza.

Removing Credenza

Section titled “Removing Credenza”

apt remove, dnf remove, or the tarball’s uninstall.sh stops the service and deletes the application. It deliberately leaves /etc/credenza, /var/lib/credenza, the credenza user and the credenza-postgres volume, because game saves and the library database cannot be rebuilt. To remove those too:

Terminal window
sudo rm -rf /var/lib/credenza /var/log/credenza /var/cache/credenza /etc/credenza
sudo docker volume rm credenza-postgres
sudo userdel credenza