Self-hosting the docs

The documentation is set up as a static MkDocs site. That is a good fit for a self-hosted deployment behind your existing Caddy-based Docker Compose stack.

Local build

Build the site locally:

uv sync --group docs
uv run mkdocs build --strict

The generated static site is written to:

site/

Container build

This repository includes a Dockerfile.docs at the repository root, which builds the MkDocs site and serves it from a lightweight web server.

Build it manually if you want to test the image in isolation:

docker build -f Dockerfile.docs -t lls-docs:latest .
docker run --rm -p 8080:80 lls-docs:latest

Compose service proposal

If your main Compose stack already routes traffic with Caddy, add a dedicated docs service that only serves the static output:

services:
  lls-docs:
    build:
      context: /path/to/LLS
      dockerfile: Dockerfile.docs
    image: lls-docs:latest
    restart: unless-stopped
    networks:
      - caddy
    labels:
      caddy: docs.example.com
      caddy.reverse_proxy: "{{upstreams 80}}"

This keeps the docs deployment separate from the solver package itself:

  • the image contains only rendered documentation
  • no source control access is required at runtime
  • no implementation internals need to be exposed beyond what you document

If you use a central Caddyfile instead of labels

Keep the same lls-docs service, but wire it up in Caddy with a normal reverse proxy:

docs.example.com {
    reverse_proxy lls-docs:80
}

In that setup, make sure the docs service is attached to the same Docker network as Caddy.

For this repository, the cleanest setup is:

  1. Build the docs image from the repo.
  2. Publish only the static site container.
  3. Route a dedicated subdomain such as docs.example.com through Caddy.

That gives you a public, usage-focused documentation site while keeping the private repository and full implementation details off the public web.