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 (uv is available in the ebook-search dev shell):

nix develop .#ebook-search -c uv lock --project python/ebook_search/docker

Tests

The main pytest suite excludes tests/ebook_search (its dependencies are no longer in the nix dev shell). The test ebook search CI workflow runs them in a uv env built from the lockfile in this directory — same commands work locally from the repo root (the --override-ini drops the main suite's ignore):

uv sync --locked --project python/ebook_search/docker
uv run --project python/ebook_search/docker --no-sync pytest tests/ebook_search --override-ini addopts="-n auto -ra"

They can also run inside the Docker test image, which validates the image itself:

python -m python.ebook_search.docker.containers test

or the raw docker equivalent:

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

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.