This repository serves as the Docker image pack center for GPUStack Runner. It provides a collection of Dockerfiles to build images for various inference services across different accelerated backends.

• Onboard Services
• Directory Structure
• Dockerfile Convention
• Docker Image Naming Convention
• Integration Process

The following table lists the supported accelerated backends and their corresponding inference services with versions.

The pack skeleton is organized by backend:

pack
├── {BACKEND 1}
│   └── Dockerfile
├── {BACKEND 2}
│   └── Dockerfile
├── {BACKEND 3}
│   └── Dockerfile
├── ...
│   └── Dockerfile
└── {BACKEND N}
    └── Dockerfile

Each Dockerfile follows these conventions:

• Begin with comments describing the package logic in steps and usage of build arguments (ARGs).
• Use ARG for all required and optional build arguments. If a required argument is unused, mark it as (PLACEHOLDER).
• Use heredoc syntax for RUN commands to improve readability.

# Describe package logic and ARG usage.
#
ARG PYTHON_VERSION=...                                 # REQUIRED
ARG CMAKE_MAX_JOBS=...                                 # REQUIRED
ARG {OTHERS}                                           # OPTIONAL
ARG {BACKEND}_VERSION=...                              # REQUIRED
ARG {BACKEND}_ARCHS=...                                # REQUIRED
ARG {BACKEND}_{OTHERS}=...                             # OPTIONAL
ARG {SERVICE}_BASE_IMAGE=...                           # REQUIRED
ARG {SERVICE}_VERSION=...                              # REQUIRED
ARG {SERVICE}_{OTHERS}=...                             # OPTIONAL
ARG {SERVICE}_{FRAMEWORK}_VERSION=...                  # REQUIRED
ARG {SERVICE}_{FRAMEWORK}_{OTHERS}=...                 # OPTIONAL

# Stage Bake Runtime
FROM {BACKEND DEVEL IMAGE} AS runtime
SHELL ["/bin/bash", "-eo", "pipefail", "-c"]
ARG TARGETPLATFORM
ARG TARGETOS
ARG TARGETARCH
ARG ...
RUN <<EOF
    # TODO: install runtime dependencies
EOF

# Stage Install Service
FROM {BACKEND}_BASE_IMAGE AS {service}
SHELL ["/bin/bash", "-eo", "pipefail", "-c"]
ARG TARGETPLATFORM
ARG TARGETOS
ARG TARGETARCH
ARG ...
RUN <<EOF
    # TODO: install service and dependencies
EOF

WORKDIR /
ENTRYPOINT [ "tini", "--" ]

The Docker image naming convention is as follows:

• Multi-architecture image names: {NAMESPACE}/{REPOSITORY}:{TAG}.
• Single-architecture image tags: {BACKEND}{BACKEND_VERSION%.*}[-{BACKEND_VARIANT}]-{SERVICE}{SERVICE_VERSION}-{OS}-{ARCH}.
• Multi-architecture image tags: {BACKEND}{BACKEND_VERSION%.*}[-{BACKEND_VARIANT}]-{SERVICE}{SERVICE_VERSION}[-dev].
• All names adn tags must be lowercase.

• NAMESPACE: gpustack
• REPOSITORY: runner

1. Build single architecture images for OS/ARCH, e.g. gpustack/runner:cann8.1-910b-vllm0.9.2-linux-amd64.
2. Combine single-architecture images into a multiple architectures image, e.g. gpustack/runner:cann8.1-910b-vllm0.9.2-dev.
3. After testing, rename the multi-architecture image to the final tag, e.g. gpustack/runner:cann8.1-910b-vllm0.9.2.

To add support for a new accelerated backend:

1. Create a new directory under pack/ named with the new backend.
2. Add a Dockerfile in the new directory following the Dockerfile Convention.
3. Update pack.yml to include the new backend in the build matrix.
4. Update matrix.yml to include the new backend and its variants.
5. Update _RE_DOCKER_IMAGE in runner.py to recognize the new backend.
6. [Optional] Update tests if necessary.

To add support for a new inference service:

1. Modify the Dockerfile of the relevant backend in pack/{BACKEND}/Dockerfile to include the new service.
2. Update pack.yml to include the new service in the build matrix.
3. Update matrix.yml to include the new service.
4. Update _RE_DOCKER_IMAGE in runner.py to recognize the new service.
5. [Optional] Update tests if necessary.

Copyright (c) 2025 The GPUStack authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at LICENSE file for details.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.