crawl4tools 1.0.0b1__tar.gz

crawl4tools-1.0.0b1/.dockerignore

@@ -0,0 +1,28 @@
+# Keep the build context small and avoid leaking local/dev-only files into
+# the image. README.md, LICENSE, NOTICE, pyproject.toml, uv.lock and src/
+# are intentionally NOT listed here: hatchling's wheel build needs them.
+
+.git
+.gitignore
+.venv
+venv
+**/__pycache__
+**/*.py[cod]
+.mypy_cache
+.pytest_cache
+.ruff_cache
+.crawl4ai
+dist
+build
+*.egg-info
+tests
+tools
+downloads
+.env
+.env.*
+PROJECT.md
+開発資料
+.patent-checker
+.claude
+Dockerfile
+compose.yaml

crawl4tools-1.0.0b1/.github/workflows/ci.yml

@@ -0,0 +1,122 @@
+name: CI
+
+on:
+  push:
+    branches: [main, "dev/**"]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    # Explicit bash runs every script with -e and -o pipefail.
+    shell: bash
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      # setup-uv publishes full version tags only (no floating v10 tag).
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.12.15"
+          enable-cache: true
+          python-version: "3.12"
+      - name: Lock, shellcheck, lint, format, type check and unit tests
+        run: tools/check.sh
+
+  py311:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      # python-version sets UV_PYTHON for the job, which beats .python-version (3.12).
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.12.15"
+          enable-cache: true
+          python-version: "3.11"
+      - name: Show the interpreter (must be 3.11)
+        run: |
+          uv run --python 3.11 python --version
+          uv run --python 3.11 python -c 'import sys; assert sys.version_info[:2] == (3, 11), sys.version'
+      # Unit tests only: mypy targets 3.12 and runs in the check job.
+      - name: Unit tests on Python 3.11
+        run: uv run --python 3.11 pytest -q tests/unit
+
+  package:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.12.15"
+          enable-cache: true
+          python-version: "3.12"
+      - name: Build the sdist and wheel
+        run: uv build
+      - name: Check the wheel's contents
+        run: tools/wheel_check.sh dist/crawl4tools-*.whl
+      - name: Install the wheel as a uv tool
+        run: |
+          uv tool install --with-executables-from playwright ./dist/crawl4tools-*.whl
+          # Put the tool's commands on PATH for the next steps.
+          uv tool dir --bin >> "$GITHUB_PATH"
+      - name: Check each command's --version line
+        run: |
+          version="$(uv version --short)"
+          status=0
+          for cmd in crawl4cli crawl4mcp crawl4server; do
+            if ! output="$("$cmd" --version)"; then
+              echo "::error::$cmd --version failed"
+              status=1
+              continue
+            fi
+            first="${output%%$'\n'*}"
+            if [[ "$first" == "$cmd $version "* ]]; then
+              echo "ok: $first"
+            else
+              echo "::error::$cmd --version printed '$first'; expected it to start with '$cmd $version '"
+              status=1
+            fi
+          done
+          exit "$status"
+
+  docker:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-buildx-action@v4
+      - name: Build the image for linux/amd64
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64
+          # Load into the local daemon so the smoke test can run it.
+          load: true
+          tags: crawl4tools:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - name: Validate compose.yaml
+        run: docker compose config -q
+      - name: Smoke-test the container
+        run: tools/docker_smoke.sh crawl4tools:ci
+
+  actionlint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+      # The image bundles shellcheck, so run: scripts are checked as well.
+      - name: Lint the workflows
+        run: docker run --rm -v "$PWD":/repo -w /repo rhysd/actionlint:1.7.12 -color

crawl4tools-1.0.0b1/.github/workflows/release.yml

@@ -0,0 +1,340 @@
+name: Release
+
+# Publishing a GitHub Release whose tag is v<version in pyproject.toml> puts that
+# version on PyPI (Trusted Publishing), on Docker Hub as xhighhongo41/crawl4tools
+# (linux/amd64 + linux/arm64, each built on its own native runner) and attaches
+# the sdist and wheel to the release.
+#
+# Re-running a failed job is safe: PyPI skips files it already has, images are
+# pushed by digest, the manifest job re-points the same tags, and the assets are
+# uploaded with --clobber. Re-run only the failed jobs with
+#   gh run rerun <run id> --failed
+#
+# A manual run is a dry run by default: it builds the packages and both images
+# and logs in to Docker Hub, but publishes nothing. A manual run with
+# dry_run=false publishes (to recover from a broken release run) and must run on
+# the tag: gh workflow run release.yml --ref v<version> -f dry_run=false
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Dry run: build the packages and images, but publish nothing"
+        type: boolean
+        default: true
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    # Explicit bash runs every script with -e and -o pipefail.
+    shell: bash
+
+env:
+  IMAGE: xhighhongo41/crawl4tools
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      version: ${{ steps.check.outputs.version }}
+      tag: ${{ steps.check.outputs.tag }}
+      is_prerelease: ${{ steps.check.outputs.is_prerelease }}
+      dry_run: ${{ steps.check.outputs.dry_run }}
+    steps:
+      - uses: actions/checkout@v7
+      # setup-uv publishes full version tags only (no floating v10 tag). No cache
+      # in this workflow: what gets published is built from fresh downloads only.
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.12.15"
+          enable-cache: false
+          python-version: "3.12"
+      - name: Check the version against the release
+        id: check
+        # Event data reaches the script through env only, never pasted into it.
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+          RELEASE_PRERELEASE: ${{ github.event.release.prerelease }}
+          DRY_RUN_INPUT: ${{ inputs.dry_run }}
+        run: |
+          version="$(uv version --short)"
+          # The version must be in PEP 440 normal form, or the wheel's name
+          # (normalized by the build) would not match the tag.
+          is_prerelease="$(uv run --no-project --with packaging python -c '
+          import sys
+
+          from packaging.version import InvalidVersion, Version
+
+          text = sys.argv[1]
+          try:
+              version = Version(text)
+          except InvalidVersion:
+              sys.exit(f"::error::{text!r} in pyproject.toml is not a PEP 440 version")
+          if str(version) != text:
+              sys.exit(f"::error::Write the version in PEP 440 normal form: {version} (not {text})")
+          if version.local is not None or version.epoch != 0:
+              sys.exit(f"::error::{text} has a local part or an epoch, which a Docker tag cannot hold")
+          print("true" if version.is_prerelease else "false")
+          ' "$version")"
+          tag="v$version"
+
+          dry_run=false
+          if [[ "$GITHUB_EVENT_NAME" == workflow_dispatch && "$DRY_RUN_INPUT" == true ]]; then
+            dry_run=true
+          fi
+
+          case "$GITHUB_EVENT_NAME" in
+            release)
+              if [[ -z "$RELEASE_TAG" || ! "$RELEASE_PRERELEASE" =~ ^(true|false)$ ]]; then
+                echo "::error::The release event carries no tag_name or prerelease field (tag '$RELEASE_TAG', prerelease '$RELEASE_PRERELEASE')"
+                exit 1
+              fi
+              if [[ "$RELEASE_TAG" != "$tag" ]]; then
+                echo "::error::The release's tag is $RELEASE_TAG, but pyproject.toml's version needs the tag $tag"
+                exit 1
+              fi
+              if [[ "$is_prerelease" == true && "$RELEASE_PRERELEASE" != true ]]; then
+                # A re-run replays this same event, so it cannot pick up the edit.
+                echo "::error::$version is a pre-release; mark the GitHub Release as a pre-release, then run this workflow on $tag with dry_run=false"
+                exit 1
+              fi
+              ;;
+            workflow_dispatch)
+              # A manual real publish runs on the tag, never on an arbitrary branch.
+              if [[ "$dry_run" == false && "$GITHUB_REF" != "refs/tags/$tag" ]]; then
+                echo "::error::A manual publish must run on the tag $tag (this run is on $GITHUB_REF); use --ref $tag, or run a dry run"
+                exit 1
+              fi
+              ;;
+            *)
+              echo "::error::Unexpected event: $GITHUB_EVENT_NAME"
+              exit 1
+              ;;
+          esac
+
+          {
+            echo "version=$version"
+            echo "tag=$tag"
+            echo "is_prerelease=$is_prerelease"
+            echo "dry_run=$dry_run"
+          } >>"$GITHUB_OUTPUT"
+          echo "version $version, tag $tag, pre-release $is_prerelease, dry run $dry_run"
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          version: "0.12.15"
+          enable-cache: false
+          python-version: "3.12"
+      - name: Build the sdist and wheel
+        run: uv build
+      - name: Check the wheel's contents
+        run: tools/wheel_check.sh dist/crawl4tools-*.whl
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    needs: [verify, build]
+    if: needs.verify.outputs.dry_run != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/crawl4tools/${{ needs.verify.outputs.version }}/
+    # Trusted Publishing: the OIDC token is the only credential, and only this
+    # job may request one.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      # Generates and uploads PEP 740 attestations by default.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  docker:
+    needs: verify
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-latest
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 45
+    steps:
+      - name: Name the platform for artifact names
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: echo "PLATFORM_PAIR=${PLATFORM//\//-}" >>"$GITHUB_ENV"
+      - uses: actions/checkout@v7
+      - uses: docker/setup-buildx-action@v4
+      # Also in a dry run, to prove the credentials work before a real release.
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      # Labels only; the tags are set by the manifest job.
+      - name: Image labels
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.IMAGE }}
+          labels: |
+            org.opencontainers.image.version=${{ needs.verify.outputs.version }}
+            org.opencontainers.image.licenses=Apache-2.0
+      # A push by digest and a plain build cannot share one step, so each run
+      # takes exactly one of the two steps below.
+      - name: Build and push by digest
+        id: build
+        if: needs.verify.outputs.dry_run != 'true'
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+      - name: Build without pushing (dry run)
+        if: needs.verify.outputs.dry_run == 'true'
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          push: false
+      - name: Export the digest
+        if: needs.verify.outputs.dry_run != 'true'
+        env:
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+            echo "::error::The build reported no image digest (got '$DIGEST')"
+            exit 1
+          fi
+          mkdir -p "$RUNNER_TEMP/digests"
+          touch "$RUNNER_TEMP/digests/${DIGEST#sha256:}"
+      # One artifact per platform, so the two matrix jobs never collide.
+      - name: Upload the digest
+        if: needs.verify.outputs.dry_run != 'true'
+        uses: actions/upload-artifact@v7
+        with:
+          name: digests-${{ env.PLATFORM_PAIR }}
+          path: ${{ runner.temp }}/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  manifest:
+    needs: [verify, docker]
+    if: needs.verify.outputs.dry_run != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Download the digests
+        uses: actions/download-artifact@v8
+        with:
+          path: ${{ runner.temp }}/digests
+          pattern: digests-*
+          merge-multiple: true
+      - uses: docker/setup-buildx-action@v4
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      # The version tag always; latest only for a final (not pre-release) version.
+      # flavor latest=false keeps the action from adding latest on its own.
+      - name: Image tags
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.IMAGE }}
+          flavor: latest=false
+          tags: |
+            type=raw,value=${{ needs.verify.outputs.version }}
+            type=raw,value=latest,enable=${{ needs.verify.outputs.is_prerelease == 'false' }}
+      - name: Create the multi-platform image
+        working-directory: ${{ runner.temp }}/digests
+        run: |
+          mapfile -t tags < <(jq -r '.tags[]' <<<"$DOCKER_METADATA_OUTPUT_JSON")
+          if ((${#tags[@]} == 0)); then
+            echo "::error::docker/metadata-action produced no tags"
+            exit 1
+          fi
+          shopt -s nullglob
+          digests=(*)
+          # One digest per platform of the docker job's matrix.
+          if ((${#digests[@]} != 2)); then
+            echo "::error::Expected 2 image digests (amd64, arm64), found ${#digests[@]}: ${digests[*]}"
+            exit 1
+          fi
+          args=()
+          for tag in "${tags[@]}"; do
+            args+=(--tag "$tag")
+          done
+          for digest in "${digests[@]}"; do
+            args+=("$IMAGE@sha256:$digest")
+          done
+          echo "docker buildx imagetools create ${args[*]}"
+          docker buildx imagetools create "${args[@]}"
+      - name: Check the image holds both platforms
+        env:
+          VERSION: ${{ needs.verify.outputs.version }}
+        run: |
+          ref="$IMAGE:$VERSION"
+          docker buildx imagetools inspect "$ref"
+          # Attestation manifests show up as unknown/unknown and are ignored.
+          platforms="$(docker buildx imagetools inspect "$ref" --format '{{json .Manifest}}' |
+            jq -r '.manifests[] | select(.platform != null) | "\(.platform.os)/\(.platform.architecture)"')"
+          status=0
+          for want in linux/amd64 linux/arm64; do
+            if grep -qxF "$want" <<<"$platforms"; then
+              echo "ok: $ref has $want"
+            else
+              echo "::error::$ref has no $want image"
+              status=1
+            fi
+          done
+          exit "$status"
+
+  assets:
+    needs: [verify, build]
+    if: needs.verify.outputs.dry_run != 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # gh release upload needs write access to the release; only this job has it.
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Attach the sdist and wheel to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.verify.outputs.tag }}
+        run: gh release upload "$TAG" dist/* --clobber --repo "$GITHUB_REPOSITORY"

crawl4tools-1.0.0b1/.gitignore

@@ -0,0 +1,36 @@
+# --- Project-internal files (never committed) ---
+/PROJECT.md
+/開発資料/
+/.patent-checker/
+/.claude/
+
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# --- Environment / secrets ---
+.env
+.env.*
+
+# --- Playwright / crawl4ai runtime ---
+.crawl4ai/
+
+# --- OS / editors ---
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp

crawl4tools-1.0.0b1/.python-version

@@ -0,0 +1 @@
+3.12

crawl4tools-1.0.0b1/Changelog.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Pre-release versions are written in PEP 440 form (for example 1.0.0b1).
+
+## [Unreleased]
+
+## [1.0.0b1] - 2026-09-25
+
+### Added
+
+- PyPI package `crawl4tools`
+- Docker Hub image `xhighhongo41/crawl4tools` for linux/amd64 and linux/arm64, published with each GitHub Release (beta versions are not tagged `latest`)
+- The direct-connection fallback now also covers a proxy that intercepts TLS: a TLS error, an error page generated by the proxy itself, or a bot challenge seen through the proxy; a refusal by the proxy itself is never bypassed
+- GitHub Actions CI: lint, type checks, unit tests on Python 3.11 and 3.12, a package build check, and a Docker build and smoke test
+
+### Changed
+
+- `crawl4server` now waits at most 5 seconds for requests in progress when stopped (`SIGINT`/`SIGTERM`, e.g. `docker stop`), then closes the remaining connections
+- `compose.yaml` pulls the published `xhighhongo41/crawl4tools` image instead of building it
+- The Docker base image is pinned to Debian 12 (bookworm)
+- Development status is now Beta
+
+## [0.4.0] - 2026-09-25
+
+### Added
+
+- English and Japanese messages for `crawl4cli`, `crawl4mcp`, and `crawl4server`: `--help` text, error messages, notes and progress lines on stderr, the MCP tools' descriptions and result text, the servers' startup/warning lines, and the web loader's JSON error responses
+- `--lang en|ja` option, `CRAWL4CLI_LANG`/`CRAWL4MCP_LANG`/`CRAWL4SERVER_LANG` environment variables, and a `lang` config file key (servers) to choose the message language, resolved as option > environment variable > config file
+
+### Changed
+
+- `crawl4cli` now follows the OS locale (`LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG`) to pick its default language; `crawl4mcp` and `crawl4server` still default to English regardless of the locale
+
+## [0.3.0] - 2026-09-24
+
+### Added
+
+- `crawl4server` command: serves the Open WebUI web loader and MCP on two ports of one process, sharing one headless browser and one concurrency limit
+- Open WebUI external web loader endpoint (`POST /crawl`, `GET /health`, optional bearer API key)
+- `CRAWL4SERVER_*` environment variables and a YAML/JSON config file (`--config`)
+- `Dockerfile` and `compose.yaml` for running `crawl4server` in a container
+- Page title in fetch results (web loader `metadata.title`, MCP structured page data `title`)
+
+### Changed
+
+- `starlette` and `uvicorn` are now direct dependencies; the empty `server` extra was removed
+
+## [0.2.0] - 2026-09-24
+
+### Added
+
+- `crawl4mcp` MCP server with `fetch` (return content directly) and `download` (save to files) tools
+- stdio and Streamable HTTP transports
+- Per-call URL limit (default 20) and server-wide concurrency limit (default 3), both configurable
+- Configuration via command-line options, `CRAWL4MCP_*` environment variables, or a YAML/JSON config file (`--config`)
+- `Fetcher.fetch`/`fetch_many` accept per-call options while sharing one engine
+
+## [0.1.0] - 2026-09-24
+
+### Added
+
+- `crawl4cli` command: download one or more URLs as Markdown, HTML, PDF, screenshot, MHTML, or raw source
+- PDF transcription to Markdown; non-HTML resources such as images are saved as they are
+- Error messages by cause (HTTP status, unknown host, refused connection, timeout, missing browser) and exit codes 0/1/2
+- Proxy support (`--proxy`) with a single retry over a direct connection when the proxy fails (`--no-fallback` to disable)
+- `--fit` to keep only the main content of a page, using crawl4ai's pruning content filter
+- Concurrent downloads of several URLs into a directory (`-d`, `-j`)
+- `CRAWL4CLI_*` environment variables for every option
+- Shared fetch engine (`crawl4tools.engine`) for the planned servers
+- `tools/check.sh` and `tools/release_check.sh` for development
+
+## [0.0.1] - 2026-09-23
+
+### Added
+
+- Project scaffolding (license, NOTICE, .gitignore, pyproject metadata)
+- README in English and Japanese
+- This Changelog
+
+No code is included in this release.
+
+[Unreleased]: https://github.com/xhighhongo41/crawl4tools/compare/v1.0.0b1...HEAD
+[1.0.0b1]: https://github.com/xhighhongo41/crawl4tools/compare/v0.4.0...v1.0.0b1
+[0.4.0]: https://github.com/xhighhongo41/crawl4tools/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/xhighhongo41/crawl4tools/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/xhighhongo41/crawl4tools/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/xhighhongo41/crawl4tools/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/xhighhongo41/crawl4tools/releases/tag/v0.0.1

crawl4tools-1.0.0b1/Dockerfile

@@ -0,0 +1,65 @@
+# crawl4tools server image
+#
+# Build:   docker build -t xhighhongo41/crawl4tools:<version> .
+# Run:     docker compose up -d   (pulls the published image unless built here)
+#
+# The image bundles Playwright's Chromium build (and its OS dependencies),
+# so no separate browser install step is needed at runtime. The final
+# process runs as the unprivileged "crawl" user, not root.
+
+# The plain "3.12-slim" tag now points at Debian 13 (trixie); Playwright's
+# `install --with-deps` has reports of misdetecting Debian 13, so pin to
+# bookworm until that is confirmed to work.
+FROM python:3.12-slim-bookworm
+
+ENV PYTHONUNBUFFERED=1 \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=never \
+    PLAYWRIGHT_BROWSERS_PATH=/ms-playwright \
+    CRAWL4_AI_BASE_DIRECTORY=/data \
+    HOME=/data
+
+# Pinned uv binary, copied straight from the official distroless image.
+COPY --from=ghcr.io/astral-sh/uv:0.12.15 /uv /usr/local/bin/uv
+
+WORKDIR /app
+
+# Copy only what hatchling's wheel build and `uv sync` need, so source-only
+# edits don't bust the dependency layer's cache.
+COPY pyproject.toml uv.lock README.md LICENSE NOTICE ./
+COPY src ./src
+
+# Install the locked, non-dev dependency set plus the project itself
+# (non-editable, so /app/src is not required at runtime) into /app/.venv,
+# built against the image's own interpreter.
+RUN UV_PYTHON=/usr/local/bin/python3 uv sync --frozen --no-dev --no-editable
+
+# Install Chromium and the OS libraries it needs (requires root; apt-get is
+# invoked by `--with-deps`). Drop the apt cache afterwards to keep the
+# layer small.
+RUN /app/.venv/bin/playwright install --with-deps chromium && \
+    rm -rf /var/lib/apt/lists/*
+
+# Non-root runtime user; its home doubles as crawl4ai's cache/DB directory
+# (CRAWL4_AI_BASE_DIRECTORY=/data above) and holds the download directory.
+RUN useradd --create-home --home-dir /data --uid 1000 crawl && \
+    mkdir -p /data/downloads && \
+    chown -R crawl:crawl /data /ms-playwright
+
+USER crawl
+WORKDIR /data
+
+ENV PATH=/app/.venv/bin:$PATH
+
+# Open WebUI external web loader (8766) and MCP Streamable HTTP (8765).
+EXPOSE 8766 8765
+
+# Assumes the default loader port (8766); override the healthcheck if
+# CRAWL4SERVER_LOADER_PORT is changed. No curl in the slim base image, so
+# the check is done with Python's stdlib instead.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD ["python", "-c", "import sys, urllib.request; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:8766/health', timeout=3).status == 200 else 1)"]
+
+ENTRYPOINT ["crawl4server"]
+CMD ["--host", "0.0.0.0", "--download-dir", "/data/downloads"]