dotfiles/python/ebook_search/docker

Ebook Search Docker

Run the EPUB search app against the existing Postgres database on jeeves:

python -m python.ebook_search.docker.containers start --library-path /path/to/epubs --build

All ebook-search Docker files live in this directory:

• Dockerfile — multi-stage: test (runs pytest) and runtime (default target, the app image)
• docker-compose.yml
• containers.py — Typer lifecycle CLI
• pyproject.toml / uv.lock — the container's uv-locked dependencies

The app listens on http://localhost:8070.

Useful lifecycle commands:

python -m python.ebook_search.docker.containers build
python -m python.ebook_search.docker.containers start --library-path /path/to/epubs
python -m python.ebook_search.docker.containers test
python -m python.ebook_search.docker.containers logs
python -m python.ebook_search.docker.containers ps
python -m python.ebook_search.docker.containers stop

Direct compose usage from the repo root:

docker compose -f python/ebook_search/docker/docker-compose.yml ps

Dependencies

The image builds its environment with uv from pyproject.toml + uv.lock in this directory — this is the source of truth for the container's dependencies. To add or update a dependency, edit pyproject.toml here and regenerate the lock (requires uv on the host; it is not in the nix dev shell):

cd python/ebook_search/docker && uv lock

Tests

The main pytest suite excludes tests/ebook_search (its dependencies are no longer in the nix dev shell). The ebook tests run inside the Docker test image instead:

python -m python.ebook_search.docker.containers test

or the raw docker equivalent (what the test ebook search CI workflow runs):

docker build --file python/ebook_search/docker/Dockerfile --target test --tag ebook-search:test .
docker run --rm ebook-search:test

To run them on the host instead, use a venv with the ebook deps installed and override the ignore: pytest tests/ebook_search -o addopts="-ra".

Configuration

The compose service loads the repo root .env into the container via env_file.

Mount your EPUB directory by setting EBOOK_LIBRARY_HOST_PATH in an env file or on the command line. The container sees it as /library, and EBOOK_SEARCH_LIBRARY_PATHS is set to /library inside the container.

Database connection settings are controlled by RICHIE_DB, RICHIE_HOST, RICHIE_PORT, RICHIE_USER, and RICHIE_PASSWORD. The default host is jeeves.