Installing Collectoh

Collectoh runs on one machine — the computer or NAS that holds your media, or can reach it — and serves everything to web browsers. You install it once, finish a short setup wizard in your browser, and do everything else from the app.

#System requirements

#Choose how to install

The installers are the quickest route on a computer you already use; Docker is the most flexible for an always-on server.

#Windows

1. Download the Windows installer from collectoh.com and run it.
2. It installs Collectoh as a background service that starts with Windows, then opens the setup wizard in your browser. If the wizard doesn't appear, go to http://localhost:8080.
3. From other devices, use http://<this-pc-address>:8080. If they can't connect, allow port 8080 through the firewall.

#macOS

1. Download Collectoh for macOS and move it to your Applications folder.
2. Open it. Collectoh starts its server in the background and opens the setup wizard at http://localhost:8080.
3. A sleeping Mac can't serve anything, so keep it awake while others are watching.

#Linux

The packages install Collectoh as a system service that starts at boot.

# Debian, Ubuntu and similar
sudo apt install ./<downloaded-file>.deb

# Fedora, RHEL and similar
sudo dnf install ./<downloaded-file>.rpm

Then open http://localhost:8080 on that machine, or http://<server-address>:8080 from another device. The service needs permission to read your media folders; if it can't read one, the scan report names the folder.

#Docker

The compose file runs three containers: Collectoh itself (the collectoh/server image, listening on port 8080), its PostgreSQL database and a Redis job queue. You need Docker with Compose v2 — the docker compose command. Docker Desktop on Windows and macOS works too, with the network limits described below.

#Start it

mkdir collectoh && cd collectoh
curl -fsSLO https://collectoh.com/docker-compose.yml
printf 'SECRET_KEY=%s\nDB_PASSWORD=%s\nMEDIA_DIR=/path/to/your/media\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 16)" > .env
docker compose up -d

Replace /path/to/your/media with your media folder before running the third line — or edit .env afterwards and run docker compose up -d again. Then open http://localhost:8080 (or http://<server-address>:8080) for the setup wizard. Inside the container your media is at /media: that's the path to give the wizard.

To follow the server's log: docker compose logs -f server.

#Settings in .env

After editing .env, run docker compose up -d to apply it. Keep a copy of .env somewhere safe.

#Folders

CONFIG_DIR, METADATA_DIR and PGDATA_DIR in .env move the first three elsewhere.

Your media is mounted read-only (:ro), so nothing Collectoh does can change it. The few opt-in features that write beside your media — saving downloaded subtitles next to a film, writing course.nfo files — need a writable mount, which you'd have to set up deliberately.

More media folders. Add a line for each under the server's volumes: in docker-compose.yml, then run docker compose up -d:

      - /mnt/disk2/tv:/tv:ro

In Collectoh, pick /tv with Browse this PC… when choosing a library's folders.

Transcode cache in memory. With 8 GB of RAM or more, replace the plain transcode-cache: entry at the bottom of docker-compose.yml:

volumes:
  transcode-cache:
    driver: local
    driver_opts: { type: tmpfs, device: tmpfs, o: "size=8g" }
  redis-data:

#Hardware transcoding

Create a file called docker-compose.gpu.yml beside docker-compose.yml.

For Intel Quick Sync or AMD:

services:
  server:
    devices:
      - /dev/dri:/dev/dri
    group_add:
      - '${RENDER_GID:-993}'

Find your render group's number with getent group render | cut -d: -f3 and add it to .env as RENDER_GID. A wrong number is the most common reason hardware transcoding doesn't work; the container's log says so when it starts, and names the fix.

For NVIDIA, install the NVIDIA Container Toolkit on the host and use:

services:
  server:
    environment:
      NVIDIA_VISIBLE_DEVICES: all
      NVIDIA_DRIVER_CAPABILITIES: compute,video,utility
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu, video]

Start with both files, and give the same two -f options to every command, updates included:

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

Admin → Diagnostics shows which encoder Collectoh will use, and Re-probe hardware tests again after a change.

#Your home network

In Docker's default network mode the container can't see your home network's broadcasts, so televisions can't find it over DLNA, apps can't discover it by themselves, and it can't ask your router to open direct access's port, which you then open yourself. Browsing to its address works as normal. For discovery, run it on the host's network on Linux: add network_mode: host to the server service, and it listens on port 8080 of the host directly. Docker Desktop on Windows and macOS can't do this. See DLNA.

#NAS

From the app centre. Where your NAS's app centre lists Collectoh, install it from there.

With the Docker image. Otherwise, use your NAS's container tool with the compose file above. Most can take a compose file directly; if yours can't, create the same three containers with the same images, ports, folders and variables. Then:

• Set PUID and PGID to the NAS user that owns your media shares.
• Point MEDIA_DIR at the share — typically something like /volume1/media on Synology, /share/Multimedia on QNAP, /mnt/user/media on Unraid or /mnt/<pool>/media on TrueNAS.
• For hardware transcoding on a NAS with an Intel processor, pass through the render device as described above.
• On a smaller NAS, switch on Admin → Settings → Low-priority scanning so a scan never makes playback stutter.

#The first-run wizard

The first time you open Collectoh, a five-step wizard sets it up:

1. Sign in with Collectoh: the wizard shows a code, like BXRT-7KQM. Open the link beside it, or go to collectoh.com/account/link on any device, sign in to your free Collectoh account, check it's this server that's waiting, and confirm. The wizard notices within a few seconds. A code lasts fifteen minutes; ask for another if it runs out. If you set a server up again, or move it to a new computer, choose the old one it replaces, and the old one is let go.
2. Create the owner account: a username (at least three characters), an optional display name and a password (at least eight; longer is better). This is your sign-in on the server itself. The owner can do everything; you add other people later.
3. Add storage: where your media lives — a name, and the folder's path (/media with Docker). Choose Test; you can carry on once the server can read it.
4. Create the first library: a name, a type and one or more folders. Before anything is saved, the wizard shows what the scanner would make of them (the first 20 items), so a wrong folder or type shows up straight away. "Nothing found here" usually means one or the other.
5. Remote access: optional. Enter the address you'd use from outside your home and test it, or choose Skip and finish. The test doesn't store the address, so put it in PUBLIC_URL as well. See Remote access.

The first step needs your server to reach collectoh.com. After that, nothing depends on us. Your server checks in once a day with its name, platform and version. If it can't, nothing changes: everyone still signs in and watches as before. Admin → Settings → Collectoh account shows which account the server belongs to.

Collectoh then starts the first scan and opens the home screen with its progress. The server's name, shown on the sign-in screen and to devices on your network, is "Collectoh" until you change it in Admin → Settings → Server.

#Updating

Docker:

docker compose pull && docker compose up -d

Database changes are applied when the new version starts, and they only go forwards: an older version refuses to start on a database a newer one has upgraded. Make a backup before updating (see Backup and restore). Automatic updaters such as Watchtower work, but updating by hand lets you choose when the server restarts.

Knowing when there's a new version: once a day your server asks collectoh.com which version is the latest. The request carries nothing about your server. When a newer one is out, admins get a notification, and Admin → Settings → Updates shows it with a link to what's new. Check now asks straight away. Turn off Look for a newer version once a day if you'd rather your server never asked. Collectoh never updates itself.

Windows, macOS and Linux packages: install the newer version over the old one, the same way as before. Your libraries, settings and watch history are kept.

NAS: update from the app centre, or pull the new image as for Docker.

#Where your data lives

Your media stays where it is. Collectoh reads it; it never moves or renames your files, and nothing in the app deletes them. Everything Collectoh knows is kept in its own data — with Docker, the config, metadata and pgdata folders above. The desktop installs keep the same pieces together in the app's data folder.

• The database matters most: from it, everything except artwork can be rebuilt, and artwork can be fetched again.
• The metadata folder is worth backing up too, so artwork and thumbnails needn't be rebuilt.
• The cache is disposable.

Admin → Backup makes backups on demand or every night. See Backup and restore.

#Next steps

• Quick start
• Libraries and folders
• Metadata and artwork: add your catalogue keys before a big first scan
• Remote access