Installation

beetkeeper can be run either as a Docker image (recommended for a self-hosted deployment) or installed from PyPI alongside an existing beets install.

Both methods point beetkeeper at your beets config: BEETSDIR (env var — the directory holding your beets config.yaml) or --config-path (CLI flag — the config file itself). See Configuration for what beetkeeper reads from that file.

Docker

Map your host directories to the container's volume paths:

Container path	Function
/beets	Persistent beets config file and app data
/music	Music library (beets-tagged and imported)
/downloads	Raw downloaded music, unprocessed by beets

docker composedocker run

services:
  beetkeeper:
    image: ghcr.io/zach-overflow/beetkeeper
    restart: unless-stopped
    stop_grace_period: 30s
    ports:
      - "8337:8337"
    environment:
      BEETSDIR: /beets
    volumes:
      - /host/path/to/beets_app_directory:/beets
      - /host/path/to/downloads:/data/raw
      - /host/path/to/music_library:/data/music

docker run \
  -v /host/path/to/beets_app_directory:/beets \
  -v /host/path/to/downloads:/data/raw \
  -v /host/path/to/music_library:/data/music \
  -e BEETSDIR=/beets \
  -p 8337:8337 \
  --stop-timeout 30 \
  ghcr.io/zach-overflow/beetkeeper

See Deployment for the full Docker workflow, including the one-time database migration step.

PyPI

To run without Docker, install both the server package and the beets plugin package into the same virtualenv as your beets install:

pip install beetkeeper beetkeeper-plugin

Then run the server, pointing it at your beets config:

beetkeeper run --config-path <path to your beets config>

Two packages

beetkeeper is the server; beetkeeper-plugin is the beets plugin that reports library events back to a running server. Install both so automated event tracking works.