Build an image from source code¶

Most artifacts reference a container image you already built and pushed (imageUri). The alternative is to hand DataRobot your source code and let the platform build the image for you—no local docker build, no registry push, no credentials to manage. This is often called code to Workload.

Set imageBuildConfig on a container instead of imageUri, point it at your uploaded source with a codeRef, and trigger a build. When the build completes, the platform writes imageUri back onto the container for you.

For triggering builds and tracking their status, see Trigger and manage builds. For a worked example, see Tutorial: Build a Workload from source.

Source-to-image flow¶

The following diagram traces a build from your uploaded source to a running Workload.

flowchart LR
    S["<b>Source directory</b><br/><i>your project</i>"] --> C["<b>Catalog version</b><br/><i>uploaded snapshot</i>"]
    C --> R["<b>codeRef</b><br/><i>pointer on the artifact</i>"]
    R --> B["<b>Build</b><br/><i>image built and pushed</i>"]
    B --> I["<b>imageUri</b><br/><i>written to the container</i>"]
    I --> W["<b>Workload</b><br/><i>running endpoint</i>"] 

Each step is separately addressable: re-upload source without rebuilding, rebuild without redeploying, or deploy the same built image to more than one Workload.

This process requires a draft artifact of type service, agent, or mcp. Builds run only against draft artifacts of those types; locked artifacts are immutable, and other artifact types cannot use imageBuildConfig—a nim artifact, for example, always references a pre-built NVIDIA container image and is never eligible for a source build.

Select the source code with codeRef¶

A codeRef identifies a specific version of your source code that has already been uploaded to DataRobot. It is a pointer into the DataRobot catalog, produced when you upload a snapshot of your project directory.

Location within imageBuildConfig¶

codeRef is a field on the container, nested under imageBuildConfig:

spec.containerGroups[].containers[].imageBuildConfig.codeRef 

codeRef fields¶

A codeRef has the following shape:

"codeRef": {
  "type": "datarobot",
  "provider": "datarobot",
  "datarobot": {
    "catalogId": "68f0c1a2b3d4e5f607182930",
    "catalogVersionId": "68f0c1a2b3d4e5f607182931"
  }
} 

The following table describes each field.

Because catalogId and catalogVersionId are used to construct DataRobot API paths, both are validated strictly. Surrounding whitespace is trimmed, and the following errors are returned for malformed values:

Both IDs are also checked for existence when you create or update the artifact: the platform reads the catalog version as you, so a nonexistent ID—or one you cannot access—is rejected at that point rather than at build time.

Upload source and set the codeRef¶

Upload source and register the resulting codeRef through either interface: the CLI for a project directory already linked via dr artifact code init, or the REST API when scripting the upload directly.

# Link this project directory to an existing draft artifact
dr artifact code init ${ARTIFACT_ID}

# Upload the current contents and update the artifact's codeRef
dr artifact code sync 

# 1. Upload a zip of your project
curl -s -X POST "${DATAROBOT_ENDPOINT}/files/fromFile/" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -F "file=@source.zip" | tee /tmp/upload.json

export CATALOG_ID=$(jq -r '.catalogId' /tmp/upload.json)
export CATALOG_VERSION_ID=$(jq -r '.catalogVersionId' /tmp/upload.json)
export STATUS_ID=$(jq -r '.statusId' /tmp/upload.json) 

until [ "$(curl -s -o /dev/null -w '%{http_code}' \
  "${DATAROBOT_ENDPOINT}/status/${STATUS_ID}/" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}")" = "303" ]; do
  sleep 2
done 

curl -s -X PATCH "${DATAROBOT_ENDPOINT}/artifacts/${ARTIFACT_ID}" \
  -H "Authorization: Bearer ${DATAROBOT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "containerGroups": [{
        "containers": [{
          "name": "primary",
          "primary": true,
          "port": 8080,
          "imageBuildConfig": {
            "codeRef": {
              "datarobot": {
                "catalogId": "'${CATALOG_ID}'",
                "catalogVersionId": "'${CATALOG_VERSION_ID}'"
              }
            }
          }
        }]
      }]
    }
  }' 

Update the source on an existing artifact¶

Point the codeRef at a newer catalogVersionId and trigger a new build. Two behaviors are worth knowing:

• The previous imageUri is retained. Changing the codeRef does not clear the image the artifact already has, so the last successfully built image stays deployable until a new build completes. It is stale, not gone.
• The build pointer is cleared. The build block on the container is dropped when the codeRef changes, because the recorded build no longer describes the current source.

What codeRef does not support¶

The following capabilities are common in build systems but are not supported by codeRef; each has a documented workaround.

Choose how the Dockerfile is obtained¶

imageBuildConfig.dockerfile is a discriminated union on the source field. Pick provided when you want full control of the image, and generated when you would rather not write a Dockerfile at all.

Option 1: Use a provided Dockerfile¶

Set dockerfile.source to provided to build from a Dockerfile that's already part of your uploaded source:

"imageBuildConfig": {
  "dockerfile": {
    "source": "provided",
    "path": "./Dockerfile"
  }
} 

The path is normalized before lookup, so ./docker/Dockerfile.prod and docker/Dockerfile.prod are equivalent. Matching is on the full relative path, not the filename, so a Dockerfile in a subdirectory is found only if path names that subdirectory.

If the file is not present in the catalog version when the build runs, the trigger fails with 422:

Dockerfile '<path>' not found in catalog <catalogId> version <catalogVersionId>.
Either upload a Dockerfile or use a generated dockerfile configuration. 

Your image must still meet the platform's container requirements—linux/amd64, non-root, a port between 1024 and 65535, an HTTP server, a readiness endpoint, and graceful SIGTERM handling.

Option 2: Use a generated Dockerfile¶

Set dockerfile.source to generated to have the platform write the Dockerfile for you:

"imageBuildConfig": {
  "dockerfile": {
    "source": "generated",
    "executionEnvironmentId": "67ab469cecdca772287de644",
    "executionEnvironmentVersionId": "6a216fca4244d434c38a2bd5",
    "entrypoint": ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8080"]
  }
} 

The platform inspects your uploaded source, detects the project type, and writes a Dockerfile that installs your locked dependencies on top of the base image from the execution environment version.

Supported project types for generated Dockerfiles¶

Detection is by filename at the root of the uploaded source. A lockfile is mandatory in both cases—builds install exactly what the lockfile pins, so that a build is reproducible.

Detection checks for the Python files first. If a project's root has both a Python and a Node config—for example, a full-stack repo with a pyproject.toml/uv.lock backend and a package.json/package-lock.json frontend—the Python path always wins and the Node config is ignored, with no warning. Use a provided Dockerfile if you need to build the Node side of a project like this.

Not supported for generated Dockerfiles: requirements.txt and pip, Poetry, Yarn, pnpm, and non-Python/Node languages. Use a provided Dockerfile for anything outside the table.

If detection fails, the build trigger returns 422 with a message that names the fix:

基本イメージを選択する¶

For generated Dockerfiles, the base image comes from the execution environment version you name—the same mechanism used for custom models, jobs, applications, and notebooks. Any execution environment version works—DataRobot-published environments and your own custom environments alike—as long as the version resolves to an image.

The execution environment version must have a sourceDockerImageUri or an imageId. If it has neither, the build trigger fails with 422:

Execution environment version has neither sourceDockerImageUri nor imageId.
Cannot determine the base image for the generated Dockerfile. 

Known limitations of custom base images¶

The generated Dockerfile installs dependencies and nothing else—there is no apt-get step and no OS-level branching. A minimal base image can therefore build a package set that a DataRobot-published environment handles without trouble.

Builds also fetch a fallback uv binary from a public container registry, which requires outbound network access from the build environment.

Generated image layout¶

Knowing the layout helps when you write entrypoint and debug a container that starts but does not serve:

Dependencies are installed from the lockfile as-is. Editing pyproject.toml without re-running uv lock does not fail the build—it silently installs the old lock. Re-run uv lock and re-sync whenever you change dependencies.

Build inputs the API does not expose¶

The following inputs are common in a Docker build but are either unsupported or fully managed by the platform, with no user-facing control.

次のステップ¶

Configuring codeRef and the Dockerfile source is only the first step; the following resources cover triggering the build, diagnosing it, and the artifact lifecycle around it.