Skip to content

https://arxiv.org/abs/2606.28344. The end of web parsing. The beginning of scalable pixel-native search. link: https://pixelrag.ai/

feat: dockerize pixelrag serve engine (#136)

chalbi youssef5f2dca2e4188
diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..88ef609
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,16 @@
+.git
+.venv
+.pytest_cache
+.ruff_cache
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+*.log
+tiles
+arxiv
+embeddings
+results
+logs
+tmp
+node_modules
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..69f4e95
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,135 @@
+# syntax=docker/dockerfile:1.7
+
+FROM python:3.12-slim-bookworm AS builder
+
+ENV DEBIAN_FRONTEND=noninteractive \
+ PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ UV_LINK_MODE=copy \
+ UV_PYTHON_DOWNLOADS=never \
+ UV_PROJECT_ENVIRONMENT=/opt/venv \
+ PATH="/opt/venv/bin:$PATH"
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ build-essential \
+ ca-certificates \
+ curl \
+ fonts-liberation \
+ libasound2 \
+ libatk-bridge2.0-0 \
+ libatk1.0-0 \
+ libatspi2.0-0 \
+ libcups2 \
+ libdbus-1-3 \
+ libdrm2 \
+ libfontconfig1 \
+ libfreetype6 \
+ libgbm1 \
+ libglib2.0-0 \
+ libgomp1 \
+ libgtk-3-0 \
+ libnspr4 \
+ libnss3 \
+ libpango-1.0-0 \
+ libpangocairo-1.0-0 \
+ libx11-6 \
+ libx11-xcb1 \
+ libxcomposite1 \
+ libxcursor1 \
+ libxdamage1 \
+ libxext6 \
+ libxfixes3 \
+ libxkbcommon0 \
+ libxrandr2 \
+ libxrender1 \
+ libxshmfence1 \
+ libxss1 \
+ libxtst6 \
+ libxcb1 \
+ zstd \
+ xdg-utils \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN python -m pip install --no-cache-dir uv
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock README.md LICENSE ./
+COPY src ./src
+COPY render/src ./render/src
+COPY embed/src ./embed/src
+COPY index/src ./index/src
+COPY serve/src ./serve/src
+
+RUN uv sync --frozen --extra serve
+RUN uv run pixelshot install-chrome
+
+
+FROM python:3.12-slim-bookworm AS runtime
+
+ENV DEBIAN_FRONTEND=noninteractive \
+ PYTHONDONTWRITEBYTECODE=1 \
+ PYTHONUNBUFFERED=1 \
+ UV_PROJECT_ENVIRONMENT=/opt/venv \
+ PATH="/opt/venv/bin:$PATH" \
+ PIXELRAG_INDEX_DIR=/data/index \
+ PIXELRAG_TILES_DIR=/data/tiles \
+ PIXELRAG_ARTICLES_JSON=/data/index/articles.json
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+ ca-certificates \
+ fonts-liberation \
+ libasound2 \
+ libatk-bridge2.0-0 \
+ libatk1.0-0 \
+ libatspi2.0-0 \
+ libcups2 \
+ libdbus-1-3 \
+ libdrm2 \
+ libfontconfig1 \
+ libfreetype6 \
+ libgbm1 \
+ libglib2.0-0 \
+ libgomp1 \
+ libgtk-3-0 \
+ libnspr4 \
+ libnss3 \
+ libpango-1.0-0 \
+ libpangocairo-1.0-0 \
+ libx11-6 \
+ libx11-xcb1 \
+ libxcomposite1 \
+ libxcursor1 \
+ libxdamage1 \
+ libxext6 \
+ libxfixes3 \
+ libxkbcommon0 \
+ libxrandr2 \
+ libxrender1 \
+ libxshmfence1 \
+ libxss1 \
+ libxtst6 \
+ libxcb1 \
+ xdg-utils \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=builder /opt/venv /opt/venv
+COPY --from=builder /root/.cache/pixelrag/chrome /root/.cache/pixelrag/chrome
+
+COPY pyproject.toml uv.lock README.md LICENSE ./
+COPY src ./src
+COPY render/src ./render/src
+COPY embed/src ./embed/src
+COPY index/src ./index/src
+COPY serve/src ./serve/src
+
+EXPOSE 8000
+
+# The image runs as root, so Chrome's setuid/namespace sandbox is unavailable and
+# pixelshot disables it automatically (logging a warning). Chrome's own sandbox
+# inside a container needs --cap-add=SYS_ADMIN or a seccomp profile; without those
+# a non-root USER stops Chrome launching at all. Rely on container isolation here,
+# and do not point this image at untrusted pages without it. See README.
+CMD ["pixelrag", "serve", "--host", "0.0.0.0", "--port", "8000"]
diff --git a/README.md b/README.md
index 0598cb3..f4cab9f 100644
--- a/README.md
+++ b/README.md
@@ -317,6 +317,33 @@ index:
# Set append: true or recreate: true when the collection already exists.
```
+### Run the API in Docker
+
+`Dockerfile` builds a two-stage image that installs the `serve` extra and a pinned Chromium,
+and `docker-compose.yml` runs `pixelrag serve` on port 8000 against mounted index and tile
+volumes:
+
+```bash
+docker compose up --build
+# then query it
+curl -X POST http://localhost:8000/search \
+ -H "Content-Type: application/json" \
+ -d '{"queries": [{"text": "What is the capital of France?"}], "n_docs": 5}'
+```
+
+Populate the `pixelrag-index` volume with an index built as described above; the container
+reads it read-only and writes only tiles.
+
+Two things to know before using it:
+
+- **Nothing in CI builds this image.** It is best-effort and can drift when dependencies or
+ source paths move, so build it yourself before relying on it.
+- **The container runs as root, so Chrome renders with its sandbox disabled.** Chrome's
+ sandbox inside a container requires `--cap-add=SYS_ADMIN` or a tailored seccomp profile,
+ and a non-root `USER` without those stops Chrome launching entirely. Container isolation
+ is therefore the only boundary around the renderer — keep the container isolated and do
+ not point it at untrusted pages otherwise.
+
### Training
Fine-tuning lives in `train/` — a **separate uv project** (`wiki-screenshot-training`) with its own
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..1096d4f
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,19 @@
+services:
+ pixelrag-api:
+ build:
+ context: .
+ dockerfile: Dockerfile
+ target: runtime
+ ports:
+ - "8000:8000"
+ environment:
+ PIXELRAG_INDEX_DIR: /data/index
+ PIXELRAG_TILES_DIR: /data/tiles
+ PIXELRAG_ARTICLES_JSON: /data/index/articles.json
+ volumes:
+ - pixelrag-index:/data/index:ro
+ - pixelrag-tiles:/data/tiles
+
+volumes:
+ pixelrag-index:
+ pixelrag-tiles: