Adapt A Workload Image

Use this guide when turning a Den starter container into a workload image for a specific service, lab job, or internal tool.

Choose A Support Level

Start by classifying the workload:

  • runnable today: application container built from den:dev.

  • prototype-ready: VM appliance or lab gateway that integrates workload packages into the Den system generation.

  • blueprint: kiosk, POS, GPU, HPC scheduler, or provider cloud image work that needs platform support Den does not have yet.

Do not present a blueprint workload as supported until the missing platform pieces are implemented and smoke-tested.

Start From The Den Base Image

Build the local Den OCI base image:

ct run oci-image

Use it as the first line in the application Dockerfile:

FROM den:dev

Create application environments under /opt/app so the Den runtime under /opt/den stays separate from the workload.

Install Application Dependencies

Use conda inside the image build:

RUN conda create \
      --yes \
      --prefix /opt/app \
      --override-channels \
      --channel conda-forge \
      python=3.12 \
      <packages> && \
    conda clean --all --force-pkgs-dirs --yes

Put /opt/app/bin first:

ENV PATH=/opt/app/bin:/opt/den/bin:/run/current-system/sw/bin:/bin:/usr/bin:/sbin:/usr/sbin

Build And Run

docker build --platform linux/arm64 -t <image>:local <context>
docker run --rm <image>:local

Use linux/arm64 for a linux-aarch64 Den base image and linux/amd64 for a linux-64 Den base image.

For a network service:

docker run --rm -p 8080:8080 <image>:local

For a batch job that writes output:

mkdir -p build/example-output
docker run --rm \
  -v "$PWD/build/example-output:/output" \
  <image>:local

When To Use A Den Package Instead

Use a Den package in den-forge/recipes/ when the workload must be part of the booted system itself:

  • it needs a systemd unit in the Den VM,

  • it owns rootfs files or symlinks,

  • it must participate in Den generations and rollback,

  • it should be published as part of a Den release train.

That path is an OS integration task, not the default application-container starter path.

Verify The Image

Use the fastest check that covers the changed surface:

Change

Smoke

Den base image changed

ct run oci-smoke

application Dockerfile changed

docker build --platform <matching-platform> ...

HTTP service changed

curl http://127.0.0.1:<port>/healthz

batch job changed

docker run --rm <image>:local

booted VM integration changed

ct run boot-systemd-smoke

If the workload must run inside a booted Den VM through Docker or Podman, treat that as a future container-host feature. It needs a runtime package, kernel and cgroup validation, and a dedicated smoke test before the docs should present it as supported.