Docker implementation by Jrice1317 · Pull Request #1219 · conda/constructor

Jrice1317 · 2026-04-22T19:32:48Z

Description

Summary

This PR adds Docker output support to constructor via two new opt-in flows:

Flow 1: Dockerfile generation (`installer_type: docker`)

Generates a multi-stage Dockerfile alongside the .sh installer and stages both
into a named output directory. No Docker CLI required — the output can be used
directly or customized before building.

Output structure:

{output_dir}/<name>-<version>-<platform>/
Dockerfile
<name>-<version>-<platform>.sh

Usage:

installer_type: docker
docker_base_image: "debian:13.4-slim@sha256:..."

The generated Dockerfile uses a two-stage build: Stage 1 runs the .sh installer
in batch mode and cleans up build artifacts (.a files, __pycache__, optionally
pkgs/). Stage 2 copies the finished environment into a clean final image and
runs conda init.

Flow 2: Portable image tarball (`docker_image: tar`)

Builds a Docker image from the generated Dockerfile using docker buildx and
exports it as a portable .tar file via docker save. Requires the Docker CLI
to be installed on the host. The target platform must be Linux.

Output:

{output_dir}/<name>-<version>-<platform>-docker.tar

Usage:

docker_image: tar
docker_base_image: "debian:13.4-slim@sha256:..."

New schema keys

Key	Description
`docker_base_image`	Required for all Docker features. Base image reference.
`docker_image`	Set to `tar` to build and export a portable image tarball. Can be used standalone without `installer_type: docker`.
`docker_tag`	Optional tag for the built image. Defaults to `name:version`.
`docker_labels`	Additional OCI labels. `title` and `version` are set automatically.

Platform support

Target platform must be linux-* for all Docker features.
No host-level restriction for Dockerfile-only output.
docker_image: tar additionally requires the Docker CLI on the host.

Notes

docker_image is designed to be extendable. Additional output formats
(gz, zst) are defined in the schema but not yet implemented.
The .sh installer is always built first and reused as the Docker build
context, keeping the two outputs consistent.
The feature is intended to support Dockerfile generation from any host when targeting Linux, but CI currently validates the Docker flows on Linux only because we do not yet have a cross-platform --platform linux-* test matrix for macOS/Windows hosts.

Changes

New:

constructor/docker_build.py: Handles Docker output by rendering template and optionally building portable image
constructor/dockerfile_template.tmpl: Template used to generate Dockerfile
examples/dockerfile/construct.yaml: Example for installer_type: docker flow
examples/docker_image/construct.yaml: Example for docker_image: tar flow

Updated:

constructor/_schema.py: Adds docker to installer_type and adds docker_base_image, docker_tag, docker_labels
constructor/main.py: Adds docker to installer types
tests/test_examples.py: Adds test_dockerfile_generation and test_docker_image_build to cover both flows

Checklist - did you ...

Add a file to the news directory (using the template) for the next release's release notes?
Add / update necessary tests?
Add / update outdated documentation?

lrandersson · 2026-05-19T18:50:19Z

+        }
+      ],
+      "default": null,
+      "description": "If set, builds a docker image using the Dockerfile generated by constructor and saves it as a portable tarball either uncompressed or compressed. ``<name>-<version>-<platform>-<arch>-docker.tar`` will be created in the output docker directory.",


Is the format <name>-<version>-<platform>-<arch> true?
From what I could see in the code it looks like:

tag = info.get("docker_tag", f"{info['name'].lower()}:{info['version']}")

lrandersson · 2026-05-19T18:55:59Z

+    The labels `org.opencontainers.image.title` and `org.opencontainers.image.version`
+    are set automatically from `name` and `version`.
+    """
+    docker_image: Literal["tar", "gz", "zst"] | None = None


Should we add explicit NotImplementedError for those values that are not yet implemented? I see in the PR it says:

(gz, zst) are defined in the schema but not yet implemented.

Good catch!

lrandersson

Well done Jaida! In the future I think we should split these large PRs into smaller separate ones (to simplify review) If the comments are addressed from Marco I approve!

marcoesters

Good changes - a few more issues to address.

marcoesters · 2026-05-21T13:53:10Z

+    The labels `org.opencontainers.image.title` and `org.opencontainers.image.version`
+    are set automatically from `name` and `version`.
+    """
+    docker_image: Literal["tar", "gz", "zst"] | None = None


We shouldn't allow inputs we don't support. It's okay to only allow "tar" for now. Also, should we call it docker_image_format? I feel like that's more descriptive.

I agree, and we don't allow inputs we don't support and"tar" is the only one allowed because we reject anything outside of tar with a NotImplementedError. gz and zst are left intentionally as placeholders to document the planned formats so the research isn't lost and users understand the direction. The other compressions including bz2 may be used as well, but they would need to be used manually. Eventually, constructor could handle this, but I think it's better suited for a different PR. Is this wording better?

docker_image: Literal["tar", "gz", "zst"] | None = None """ If set, builds a docker image using the Dockerfile generated by constructor and saves it as a portable file. Currently, only ``tar``(uncompressed) is supported. Additional formats (``gz``, ``zst``) are planned for future releases. ``<name>-<version>-<platform>-docker.<extension>`` will be created in the output directory. """

As far as the docker_image_format, it is more descriptive, but I think docker_image communicates that the user is opting into having the image built, which feels right — the name is the feature toggle, not just a format selector. docker_image_format reads more like a sub-option for something already enabled.

marcoesters · 2026-05-21T13:57:14Z

+    docker_image: Literal["tar", "gz", "zst"] | None = None
+    """
+    If set, builds a docker image using the Dockerfile generated by constructor and saves it as a portable tarball either uncompressed or compressed.
+    ``<name>-<version>-<platform>-<arch>-docker.tar`` will be created in the output docker directory.


Suggested change

``<name>-<version>-<platform>-<arch>-docker.tar`` will be created in the output docker directory.

``<name>-<version>-<platform>-<arch>-docker.<extension>`` will be created in the output docker directory.

marcoesters · 2026-05-21T14:07:00Z

+        name=info["name"],
+        version=info["version"],
+        labels=info.get("docker_labels", {}),
+        init_cmd="$PREFIX/bin/mamba shell" if has_mamba else "$PREFIX/bin/python -m conda",


This is still assuming that either mamba or conda must be in the base environment. This is not necessarily true. We need to implement the same has_conda check as for mamba. Also note that mamba v1 uses a different init command than mamba v2.

Good catch. Moving this to the template and adding a v1 fallback

marcoesters · 2026-05-21T14:07:34Z

    use the `default_prefix_all_users` key. If not provided, the default prefix
    is `%USERPROFILE%\\<NAME>`. Environment variables will be expanded at
-    install time.
+    install time. If creating a Docker output, the default is `/opt/<NAME>` and can be overridden during the Docker build process.


This should mention which variable to use to override it.

marcoesters · 2026-05-21T14:51:33Z

+            "Install Docker Buildx to proceed, or "
+            "use `installer_type: docker` in construct.yaml to "
+            "generate the Dockerfile without building the image."


Presumably, this is already the case. The correct remedy is to remove docker_image.

marcoesters · 2026-05-21T14:55:07Z

This file is nearly identical to dockerfile. You could use Jinja and an environment variable to consolidate the two.

The overlap is intentional. One solely tests generating the Dockerfile, while the other tests building the docker image without needing the installer_type: docker set. If I use a single file, then it would make the tests a little chaotic and harder to read, but if you have something specific in mind to handle both options, while maintaining clarity in the tests, then I'm all ears.

marcoesters · 2026-05-21T15:02:40Z

+    yaml = YAML()
+    with open(input_path / "construct.yaml") as f:
+        config = yaml.load(f)


config only appears to be used to read values from construct.yaml here. I think for testing, it's okay to hard-code what we expect to be in the final Dockerfile. That would also allow you to use Jinja to consolidate the test files.

I'd rather keep reading from construct.yaml. If the example is updated without updating the test, reading from config keeps them in sync automatically.

marcoesters · 2026-05-21T15:05:56Z

+        if installer.suffix == ".sh":
+            installer_stem = installer.stem


Just to be clear, this does not mean we have an SH installer in output_path directly, right? The SH installer only exists in output_path / "installer" and nowhere else? Can we test this to ensure that the SH installer isn't duplicated anywhere else?

marcoesters · 2026-05-21T15:06:15Z

+    assert f"FROM {config['docker_base_image']}" in dockerfile_text
+
+    for key, value in config.get("docker_labels", {}).items():
+        assert f'{key}="{value}"' in dockerfile_text


Suggested change

assert f'{key}="{value}"' in dockerfile_text

assert f'LABEL {key}="{value}"' in dockerfile_text

Right?

Yes, this is more precise.

marcoesters · 2026-05-21T16:18:36Z

+COPY {{ installer_filename }} /tmp/installer.sh
+
+RUN sh /tmp/installer.sh -b -p "${PREFIX}" && \
+    rm -f "${PREFIX}/uninstall.sh" && \


Suggested change

rm -f "${PREFIX}/uninstall.sh" && \

uninstall.sh is not produced by constructor. This is an extra file that should just not be included in the first place.

uninstall.sh is written to the prefix by the installer script when it runs. The rm -f handles it cleanly.

Jrice1317 requested a review from a team as a code owner April 22, 2026 19:32

conda-bot added this to 🔎 Review Apr 22, 2026

github-project-automation Bot moved this to 🆕 New in 🔎 Review Apr 22, 2026

conda-bot added the cla-signed [bot] added once the contributor has signed the CLA label Apr 22, 2026

Jrice1317 marked this pull request as draft April 22, 2026 19:45

Jrice1317 changed the title ~~Docker implementation~~ Docker implementation [skip windows] May 6, 2026

Jrice1317 added 16 commits May 6, 2026 09:10

Add payload accessibility

81dfce0

First pass

749abd4

Revert shar changes

d60e4b3

Fix logic with building on non-native platforms

c3524ba

Add mamba logic

df67edf

Require base image to be provided in construct.yaml

b71c8f9

Update docker_build.py

ec455fa

Use existing vars in template

1fd5f98

Add docker as installer type

5028672

Add example construct.yaml for tests

487d802

Add test

c46044a

Add clean command

ae648a5

Call proper docker command in test

539500c

Fix pre-commit errors

43ca213

Add docstring to beginning of file

0bf8de5

Use schema vars properly

9f20cbe

Jrice1317 force-pushed the docker-implementation branch from 9fa7db8 to 9f20cbe Compare May 6, 2026 16:10

Jrice1317 added 7 commits May 6, 2026 09:40

Use correct image name in test

65f9fd8

Update docs

4fd0868

Add news file

8b10804

Do not generate file extension .docker

01a9982

Fix typos

d86ee52

Always use sh for docker

5784073

Pre-commit fix

b2ff9d5

Jrice1317 added 15 commits May 15, 2026 07:06

Be more descriptive

c1876f5

Be more generalized

c0ab7cb

Use multiline block

963126c

Refine logic

40475f9

Move check to main if docker installed for building image

9fea3d4

Change docker_build to docker_image

1720895

Expand tests

8735a9a

Pre-commit fixes

56957c2

Change logic

ceb9a3c

Update docs

511ade6

Fix whitespace in template

c10fe4d

Remove redundant logic and improve wording

f50394f

Fix test

9ba611f

Update docs

c0b7fd3

Make tests linux only

3fec340

Jrice1317 marked this pull request as ready for review May 19, 2026 13:32

lrandersson reviewed May 19, 2026

View reviewed changes

Jrice1317 added 6 commits May 20, 2026 08:15

Remove restriction on docker_tag and apply code review suggestions

15413f2

Add cross-build support to tests

1b534dc

Update the docs

6998d3d

Fix typo

c0e7735

Add output for debugging

2a6c4cc

Add docker buildx check to utils

0b5ce84

Jrice1317 requested a review from lrandersson May 20, 2026 22:16

lrandersson previously approved these changes May 21, 2026

View reviewed changes

github-project-automation Bot moved this from 🆕 New to ✅ Approved in 🔎 Review May 21, 2026

marcoesters reviewed May 21, 2026

View reviewed changes

Apply code review suggestions and update docs

e75758d

Jrice1317 dismissed lrandersson’s stale review via e75758d May 22, 2026 00:47

	``<name>-<version>-<platform>-<arch>-docker.tar`` will be created in the output docker directory.
	``<name>-<version>-<platform>-<arch>-docker.<extension>`` will be created in the output docker directory.

		if installer.suffix == ".sh":
		installer_stem = installer.stem

	assert f'{key}="{value}"' in dockerfile_text
	assert f'LABEL {key}="{value}"' in dockerfile_text

Conversation

Jrice1317 commented Apr 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary

Flow 1: Dockerfile generation (installer_type: docker)

Flow 2: Portable image tarball (docker_image: tar)

New schema keys

Platform support

Notes

Changes

New:

Updated:

Checklist - did you ...

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lrandersson left a comment

Choose a reason for hiding this comment

Uh oh!

marcoesters left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcoesters May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Jrice1317 commented Apr 22, 2026 •

edited

Loading

Flow 1: Dockerfile generation (`installer_type: docker`)

Flow 2: Portable image tarball (`docker_image: tar`)

marcoesters May 21, 2026 •

edited

Loading