DIAL App Builder Python configuration

This reference documents App Builder Python 0.1.0 inputs and outputs for platform engineers configuring Code App builds. It assumes familiarity with the builder's role in an App Controller Job. The settings below configure source preparation, not the running application.

Version scope

Environment reads are defined in the Python entrypoint and validation. Directory defaults come from the image. The shell entrypoint also reads PROFILE and TEMPLATES_DIR.

The release README omits TARGET_DIR, TEMPLATES_DIR, and ALLOWED_PACKAGES. They are included here because the released image and code use them.

Source and profile

Variable	Default	Description
`DIAL_BASE_URL`	Empty string in the image	Required Core base URL, such as `http://dial-core:8080/`. Source metadata and file requests use this URL.
`SOURCES`	Empty string in the image	Required DIAL source folder, such as `files/<BUCKET>/sources/`. The metadata result must have `nodeType: FOLDER`.
`PROFILE`	Empty string in the image	Required template profile. The release supplies `python-pip`.
`TARGET_DIR`	`/sources` in the image	Directory receiving downloaded project files. The Python module requires this environment variable when run outside the image.
`TEMPLATES_DIR`	`/templates` in the image	Directory receiving the profile's Dockerfile template. It must be writable before the shell entrypoint runs.

Metadata requests use /v1/metadata/<SOURCES> with recursive=true and follow nextToken. File requests use /v1/<FILE_URL>. HTTP errors fail preparation; a non-folder source raises AppValidationException. See download implementation.

Credentials

Variable	Default	Description
`API_KEY`	Empty string in the image	When non-empty, sent to Core as the `api-key` header.
`JWT`	Empty string in the image	When non-empty, sent as `Authorization: Bearer <TOKEN>`.

When both are non-empty, the builder sends both headers. In controller-managed builds, credentials are placed in a Kubernetes Secret and referenced by the preparation container. See credential injection and build environment.

Source validation

Variable	Default	Description
`ALLOWED_PACKAGES`	Empty list when unset or empty	Whitespace-separated allowed requirement names. App Controller fills it from `app.allowed-python-packages` and `app.additional-allowed-python-packages`.

The bundled python-pip validation applies these rules:

The root of TARGET_DIR must contain app.py.
requirements.txt is created when missing. Blank lines and lines beginning with # are ignored.
Each remaining line must parse as a Python requirement and its name must match an entry in ALLOWED_PACKAGES.
Requirement URLs are rejected.
Lines beginning with -, including pip options and references to other requirement files, are rejected.

An empty allowlist permits an empty requirements file but rejects any declared package. Validation does not import app.py, check its app object, run tests, or install dependencies. Source: validation implementation.

Image-builder output contract

Output	Consumer
`TARGET_DIR` with the downloaded sources and `requirements.txt`	Image build context
`TEMPLATES_DIR/Dockerfile`	Dockerfile selected by the image builder
Successful process exit	Allows the Kubernetes Job to start its main build container

App Controller mounts the directories at /sources and /templates in both containers. Its default Kaniko arguments are --context=/sources and --dockerfile=/templates/Dockerfile. It adds --destination=<IMAGE> and --build-arg=BASE_IMAGE=<RUNTIME_IMAGE>; see build Job construction.

The generated Dockerfile installs Uvicorn 0.31.0 and the project requirements. Its entrypoint is:

uvicorn app:app --host 0.0.0.0 --port 8080

This command belongs to the generated application image. It is not the command used to run the preparation image.

Controller integration example

The following fragment supplies a pinned preparation image and selects the default application runtime. It is merged with the controller's bundled app settings:

app:
  docker-registry: <REGISTRY_HOST>/<REPOSITORY_PREFIX>
  dial-base-url: http://dial-core:8080/
  template-image: epam/ai-dial-app-builder-python:0.1.0
  default-runtime: python3.11
  runtimes:
    "[python3.11]":
      image: python:3.11-slim
      profile: python-pip

The base-image tag selects a Python minor version rather than an immutable image. A deployment can replace it with an approved digest. The source folder and credentials are supplied per build, not embedded in this shared configuration.

Troubleshooting

Failure	What to check
Template copy fails before Python starts	`PROFILE` must name a directory shipped in the preparation image; `TEMPLATES_DIR` must be writable.
`Sources path must be a folder`	`SOURCES` must point to a DIAL folder, not an individual source file.
`Missing entrypoint file: app.py`	The source folder must contain `app.py` at its root.
Forbidden package, requirement URL, or pip option	The exact requirement and the controller's effective `ALLOWED_PACKAGES`.
Source download fails	Core URL, network access from the build Job, and access to the source folder with the supplied credentials.
Preparation succeeds but image build fails	Dependency resolution, runtime compatibility, registry access, and image-builder logs.
Built application fails at startup	`app.py` must import successfully and expose the ASGI object `app`. Source validation does not establish this.

Version scope​

Source and profile​

Credentials​

Source validation​

Image-builder output contract​

Controller integration example​

Troubleshooting​

Further reading​