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 fromden: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 |
|
application Dockerfile changed |
|
HTTP service changed |
|
batch job changed |
|
booted VM integration changed |
|
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.