Installation

Installation

Keelarr runs as one container. It needs the Docker socket and the host directories your stack uses.

Requirements

• Docker with the Compose plugin (docker compose, not docker-compose)
• A Linux-style filesystem. See Windows below
• Somewhere to put stack files, app config, and media

Quick start

No clone needed — the image is published.

mkdir -p ~/keelarr && cd ~/keelarr
curl -fsSLO https://raw.githubusercontent.com/tx-joshg/keelarr/main/deploy/compose.example.yml
docker compose -f compose.example.yml up -d

Then open http://localhost:4687.

Nothing needs editing first. On first run Keelarr asks you to set a password, detects the host, and proposes paths under $HOME/keelarr. You change them in the app, not in a file — see First Run and Host Setup.

Pinning a version

latest moves. To hold a specific build, set KEELARR_VERSION in .env beside the compose file:

KEELARR_VERSION=0.1.0

Tags available: latest, 0.1, 0.1.0, and a sha-<commit> tag for every build. 0.1 follows patch releases; 0.1.0 never moves.

Images are built for linux/amd64 and linux/arm64.

Running from source

git clone https://github.com/tx-joshg/keelarr.git
cd keelarr/deploy
docker compose -f compose.example.yml -f compose.build.yml up -d --build

compose.build.yml replaces the published image with a local build. Use it if you are changing the code; otherwise the published image is simpler.

Demo mode

Demo mode runs against a simulated stack with no Docker socket behind it. There is nothing to break and no password in the way, so it is the fastest way to see what Keelarr does before pointing it at anything real.

npm install && npm run demo

Every screenshot in the repository comes from here, which is also why none of them contain a real address, path or key.

Changing the port

The controller listens on 4687. To use another host port, set KEELARR_PORT in .env:

KEELARR_PORT=4688

This changes the published host port; the container still listens on 4687 internally.

What the container mounts

Four things, and each matters:

Mount	Why
/var/run/docker.sock	How Keelarr runs Compose and inspects containers
Your host roots	Mounted at the same absolute path inside the container, which is what lets Keelarr generate Compose files whose paths are correct for the host while still being able to read them itself
./data	Settings, credentials, jobs, activity and the log
../deploy	So Keelarr can rewrite its own .env when you change a path in the app

The same-absolute-path rule is the single most important thing to understand about Keelarr. It is explained in First Run and Host Setup.

Windows

Unsupported outside WSL2, by design rather than by omission. Keelarr mounts each host root at the same absolute path inside the container, and C:\Media has no equivalent inside a Linux container.

Inside WSL2 with POSIX paths it should work — but nobody has confirmed it does. If you try it, that is one of the scenarios we need help with.

Updating the controller

docker compose -f compose.example.yml pull
docker compose -f compose.example.yml up -d

Your settings live in the data directory, not the image, so they survive.

Uninstalling

docker compose -f compose.example.yml down

That is the whole procedure. Your stack keeps running — every service Keelarr manages is an ordinary Compose project in its own directory, and nothing about it depended on the controller being alive. Delete the data directory if you want its settings gone too.