dockerfile.executorch

# ExecuTorch backend Dockerfile for RF-DETR C++ Inference.
#
# One of three backend Dockerfiles (dockerfile.onnxrt, dockerfile.executorch,
# dockerfile.trt); the backend is chosen by which file you pass to `-f`. This one
# builds the CPU-only ExecuTorch backend (`.pte` models), in either media flavour:
#
#   MEDIA_BACKEND   Image
#   ─────────────   ─────────────────────────────
#   ffmpeg (default) ExecuTorch + FFmpeg/SDL2/stb
#   opencv           ExecuTorch + OpenCV
#
# Build args:
#   MEDIA_BACKEND       ffmpeg (default) | opencv
#   DOCKER_BASE_IMAGE   base image for the builder and runtime stages
#   EXECUTORCH_VERSION  git tag of the ExecuTorch C++ runtime
#
# The version args default to the values in versions.env, the single source of
# truth for this project's pins. A Dockerfile cannot read that file, so the
# defaults below restate it and scripts/check_version_sync.sh (run by lint.yml)
# fails when the two drift.
#
# Examples:
#   docker build -f dockerfile.executorch -t rfdetr-et-ffmpeg .
#   docker build -f dockerfile.executorch -t rfdetr-et-opencv --build-arg MEDIA_BACKEND=opencv .
#
# Run (CPU-only, takes a .pte model exported with the xnnpack delegate):
#   docker run -v "$PWD/data:/data" -v "$PWD/exports:/exports" \
#     rfdetr-et-ffmpeg /exports/model.pte /data/dog.jpg /data/coco-labels-91.txt

# Keep in sync with versions.env — see scripts/check_version_sync.sh.
ARG MEDIA_BACKEND=ffmpeg
ARG DOCKER_BASE_IMAGE=ubuntu:24.04
ARG EXECUTORCH_VERSION=v1.4.0

# =============================================================================
# Build stage
# =============================================================================
FROM ${DOCKER_BASE_IMAGE} AS builder

ARG MEDIA_BACKEND
ARG EXECUTORCH_VERSION
ENV DEBIAN_FRONTEND=noninteractive

# === shared:toolchain ===
RUN apt-get update && apt-get install -y --no-install-recommends \
        cmake \
        ninja-build \
        clang-18 \
        pkg-config \
        wget \
        ca-certificates \
        git \
    && rm -rf /var/lib/apt/lists/*
# === /shared:toolchain ===

# === shared:media-dev-packages ===
RUN if [ "$MEDIA_BACKEND" = "opencv" ]; then \
        apt-get update && apt-get install -y --no-install-recommends libopencv-dev \
        && rm -rf /var/lib/apt/lists/*; \
    else \
        apt-get update && apt-get install -y --no-install-recommends \
            libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libsdl2-dev \
        && rm -rf /var/lib/apt/lists/*; \
    fi
# === /shared:media-dev-packages ===

# NOTE: this runs BEFORE `COPY . .` on purpose. It does not use the repo source, and the
# build takes ~10 minutes, so keeping it above the COPY lets Docker reuse the cached layer
# across source edits instead of rebuilding ExecuTorch every time a .cpp changes.
#
# Build the C++ runtime from source and install it to /opt/executorch; the deps facade then
# resolves it with find_package(executorch CONFIG) via EXECUTORCH_ROOTDIR. There is no
# distro or registry package for it.
#
# Two things this step must get right:
#  1. ExecuTorch's configure runs operator codegen through PYTHON_EXECUTABLE, and
#     tools/cmake/Codegen.cmake does `import torchgen` — so the interpreter needs
#     torch installed. A bare python3 fails. Only torchgen is used, so the CPU
#     wheel is enough, and the whole venv is discarded in the runtime stage.
#  2. Up to v1.3.1, upstream installed extension_evalue_util with
#     DESTINATION ${CMAKE_BINARY_DIR}/lib instead of ${CMAKE_INSTALL_LIBDIR}, so
#     the library never reached the prefix and its exported target kept an
#     absolute build-tree path. find_package then hard-failed once the build tree
#     was gone — even though this project never links that target. Fixed upstream
#     in the default v1.4.0; the sed stays for older EXECUTORCH_VERSION overrides.
#     (The sed body is single-quoted so the shell does not expand ${...}.)
#  3. EXECUTORCH_BUILD_KERNELS_OPTIMIZED is required, not a tuning knob: .pte files
#     from rfdetr >= 1.9.1 call aten::linear.out, which only the optimized kernel
#     set registers. Without it the program fails at load.
#  4. build-essential is required even though the project itself builds with
#     clang+ninja: ExecuTorch pulls in third-party/flatcc as an ExternalProject
#     that configures with the "Unix Makefiles" generator and does not inherit
#     CMAKE_C_COMPILER, so it needs make and cc on PATH or it fails at configure.
#
# Built with the same clang-18 as the project to keep one C++ runtime/ABI.
RUN apt-get update && apt-get install -y --no-install-recommends \
        python3 python3-venv build-essential \
    && rm -rf /var/lib/apt/lists/* && \
    python3 -m venv /tmp/et-venv && \
    /tmp/et-venv/bin/pip install --no-cache-dir --quiet \
        --retries 10 --timeout 120 \
        --index-url https://download.pytorch.org/whl/cpu torch && \
    /tmp/et-venv/bin/pip install --no-cache-dir --quiet \
        --retries 10 --timeout 120 pyyaml setuptools && \
    git clone --depth 1 --branch "${EXECUTORCH_VERSION}" \
        https://github.com/pytorch/executorch.git /tmp/executorch && \
    git -C /tmp/executorch submodule update --init --recursive --depth 1 && \
    sed -i 's|DESTINATION ${CMAKE_BINARY_DIR}/lib|DESTINATION ${CMAKE_INSTALL_LIBDIR}|' \
        /tmp/executorch/extension/evalue_util/CMakeLists.txt && \
    cmake -S /tmp/executorch -B /tmp/executorch/cmake-out -G Ninja \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_C_COMPILER=/usr/bin/clang-18 \
        -DCMAKE_CXX_COMPILER=/usr/bin/clang++-18 \
        -DCMAKE_INSTALL_PREFIX=/opt/executorch \
        -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
        -DEXECUTORCH_BUILD_EXTENSION_MODULE=ON \
        -DEXECUTORCH_BUILD_EXTENSION_TENSOR=ON \
        -DEXECUTORCH_BUILD_EXTENSION_DATA_LOADER=ON \
        -DEXECUTORCH_BUILD_EXTENSION_NAMED_DATA_MAP=ON \
        -DEXECUTORCH_BUILD_KERNELS_OPTIMIZED=ON \
        -DEXECUTORCH_BUILD_XNNPACK=ON \
        -DEXECUTORCH_ENABLE_LOGGING=ON \
        -DEXECUTORCH_BUILD_TESTS=OFF \
        -DEXECUTORCH_BUILD_EXAMPLES=OFF \
        -DPYTHON_EXECUTABLE=/tmp/et-venv/bin/python && \
    cmake --build /tmp/executorch/cmake-out --parallel && \
    cmake --install /tmp/executorch/cmake-out && \
    rm -rf /tmp/executorch /tmp/et-venv

# === shared:workspace-copy ===
WORKDIR /workspace
COPY . .
# === /shared:workspace-copy ===

# Offline googletest: gtest is resolved via FetchContent unconditionally
# (CMakeLists.txt), which git-clones github.com at configure time. When
# third_party/googletest/ (gitignored) is present in the build context, point
# FetchContent at it and skip the clone — see docs/docker.md. (The ExecuTorch
# from-source build above has its own github.com/pytorch and PyPI requirements;
# this only removes the gtest clone.)
RUN GTEST_FLAG=""; \
    if [ -d third_party/googletest ]; then \
        GTEST_FLAG="-DFETCHCONTENT_SOURCE_DIR_GTEST=/workspace/third_party/googletest"; \
    fi; \
    cmake -S . -B build -G Ninja \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_C_COMPILER=/usr/bin/clang-18 \
        -DCMAKE_CXX_COMPILER=/usr/bin/clang++-18 \
        -DUSE_ONNX_RUNTIME=OFF \
        -DUSE_TENSORRT=OFF \
        -DUSE_EXECUTORCH=ON \
        -DEXECUTORCH_ROOTDIR=/opt/executorch \
        -DUSE_OPENCV=$([ "$MEDIA_BACKEND" = opencv ] && echo ON || echo OFF) \
        $GTEST_FLAG \
    && cmake --build build --parallel

# =============================================================================
# Runtime stage
# =============================================================================
FROM ${DOCKER_BASE_IMAGE} AS runtime

ARG MEDIA_BACKEND
ENV DEBIAN_FRONTEND=noninteractive

# === shared:runtime-media ===
RUN if [ "$MEDIA_BACKEND" = "opencv" ]; then \
        apt-get update && apt-get install -y --no-install-recommends libopencv-dev \
        && rm -rf /var/lib/apt/lists/*; \
    else \
        apt-get update && apt-get install -y --no-install-recommends \
            libavcodec60 libavformat60 libavutil58 libswscale7 libx264-164 libsdl2-2.0-0 \
        && rm -rf /var/lib/apt/lists/*; \
    fi
# === /shared:runtime-media ===

# === shared:runtime-tail ===
COPY --from=builder /workspace/build/inference_app /usr/local/bin/inference_app
RUN ldconfig
ENTRYPOINT ["inference_app"]
CMD ["--help"]
# === /shared:runtime-tail ===