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

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

Description

This PR adds Docker output support to constructor, generating a ready-to-use Dockerfile and optionally building the resulting image via installer_type: docker and docker_build: true in the construct.yaml.

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/docker_build/construct.yaml: Example construct.yaml used for testing

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_docker_build to cover Dockerfile generation, image build and smoke test

Notes:

When docker_build is True, the user can start using the resulting portable image by running the command docker load -i <image_name>
Verified RuntimeError is raised when base_image is not provided

RuntimeError: Base image for Dockerfile not specified. Please set 'docker_base_image' in construct.yaml, e.g.:
 docker_base_image: debian:13.4-slim@sha256:4ffb3a1511099754cddc70eb1b12e50ffdb67619aa0ab6c13fcd800a78ef7c7a

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?

marcoesters · 2026-05-12T21:25:50Z

+    """
+    Base image to use for docker builds when `installer_type` includes `docker` or `docker_build` is True.
+    Should be a specific image reference. For reproducibility, please specify a SHA256 digest.
+    For example: `debian:13.4-slim@sha256:abc123...`. If the digest is not provided, a warning will be shown.


The example is great, but reproducibility is not the primary concern here either, it's supply chain security. I would overall do don't think it's constructor's responsibility to decide or advise on the user's security model though, even if it's just a warning. Warnings show up in GitHub Action summaries and can introduce unwanted noise.

So, remove the SHA256 warning altogether? Or just rephrase it to be neutral?

Base image to use for docker builds when `installer_type` includes `docker` or `docker_build` is True. Should be a specific image reference. For example: `debian:13.4-slim@sha256:abc123...`.

I would remove this altogether, so remove "Should be...", but definitely keep the example as is.

marcoesters · 2026-05-12T21:26:57Z

+    """
+    If `True`, builds a docker image using the Dockerfile generated by constructor and saves it as a portable tarball.
+    ``<name>-<version>-<platform>.tar`` will be created in the output docker directory.
+    Requires `docker_base_image` to be specified.


The base image should be a mandatory parameter in any case.

I'm not sure I'm following here as the base image being required is already enforced. Is saying Requires `docker_base_image` to be specified. misleading?

I would call it redundant since all Docker parameters require the base image to be set.

Ahh, it is true it's required, but I think it's helpful for those who don't know the code and just look at the schema.

I think the right place to declare that is with docker_base_image, not docker_build (or why in docker_build and not the other docker options?). You could write in docker_base_image that this is a required parameter to make it very explicit.

marcoesters · 2026-05-12T21:27:38Z

+    The labels `org.opencontainers.image.title` and `org.opencontainers.image.version` are
+    set automatically from `name` and `version`.
+    """
+    docker_build: bool = False


Given that Docker provides several output formats, I would rather choose something that is extendable. It's okay if we don't support all formats right now, we can disclose that.

Can you please clarify what you have in mind here? Are you suggesting we do something like docker_output: tarball in place of docker_build: True?

Correct, that's what I suggest. The available options should correspond verbatim to the same option Docker supports (uncompressed, etc.).

marcoesters · 2026-05-12T21:28:47Z

            message: "This base environment is frozen and cannot be modified."
    ```
    """
+    docker_base_image: Annotated[str, Field(min_length=1)] | None = None


Instead of prefixing all fields with docker_*, would it make more sense to make docker its own key with all other properties being a subkey? I know that's not our current convention, so I'm not 100% sure about that.

I agree it could be cleaner, but unless we can do a broader refactor, I think docker_* keeps things consistent with how it's handled today.

Also, please volunteer me if/when we can do a schema refactor. (:

Sticking with the current schema is a fair choice. A schema refactor would constitute a major breaking change that I don't foresee ourselves doing unless we absolutely have to.

marcoesters · 2026-05-12T21:29:51Z

+    docker_tag: NonEmptyStr | None = None
+    """
+    Tag to use for the docker image.
+    If not provided, it will default to `<name>:<version>`.


Do we need to provide a default here? docker build runs with a tag, too.

Will this require docker_build (or whatever successor you choose) to be set?

I don't think we should. It's handled in the script, but I could add something like Has no effect if `docker_build` or `docker_output` is not set.

I actually wrote the opposite of what I meant to write: docker build runs without a tag, too. So, tagging the image isn't necessarily required for it to work. Definitely disclose in the schema when that option has no effect for the docker installer type.

To clarify, it is highly suggested that a tag be used with docker build. The only thing is that it is not required for the user to come up with that tag because it will default to miniconda3:25.1.1 for example. Please let me know if that default is sufficient or if something like miniconda3-25.1.1:linux-arm64 would be better.

Not sure if there's a limit on characters for the tag name, but the latter is definitely more descriptive. 😄

marcoesters · 2026-05-12T22:02:27Z

+
+LABEL org.opencontainers.image.title="{{ name }}"
+LABEL org.opencontainers.image.version="{{ version }}"
+{%- if labels %}


I don't think the if is needed. If labels is empty, the loop just won't run.

marcoesters · 2026-05-12T22:03:48Z

+    if docker_build and osname == "win":
+        sys.exit(
+            "Error: 'docker_build' is not supported on Windows. "
+            "Run the build on Linux or macOS instead."
+        )
+    if docker_build and itype in ("pkg", "exe"):
+        sys.exit(
+            "Error: 'docker_build' is not compatible with installer_type 'pkg' or 'exe'. "
+            "Use installer_type: 'sh', 'docker', or omit installer_type."
+        )


Instead of erroring out, we should just ignore those.

marcoesters · 2026-05-12T22:06:16Z

+            info["_outpath"] = abspath(join(output_dir, get_output_filename(info))).replace(
+                ".docker", ".sh"
+            )


Aren't you already doing this in the build function?

You're right. I'll remove it from docker_build.py and keep the path handling here so it's consistent with how the other installer types manage _outpath.

marcoesters · 2026-05-12T22:12:24Z

+
+@pytest.mark.skipif(sys.platform.startswith("win"), reason="Unix only")
+@pytest.mark.skipif(not shutil.which("docker"), reason="Docker not available")
+def test_docker_build(tmp_path):


This test doesn't test the labels.

marcoesters · 2026-05-12T22:13:51Z

+        ),
+        "win": ("exe",),
+    }
+    all_allowed = set(sum(os_allowed.values(), ("all", "docker")))


We only allow Docker for Linux platforms and can only build them on Linux and macOS.

Does this mean I could do

os_allowed = { "linux": ("sh", "docker"), "osx": ( "sh", "pkg", ), "win": ("exe",), }

and it would cover all the bases since constructor handles the cross-platform checks for us?

I had this originally, but wasn't sure how to test the cross-platform check properly

That would add docker to the all list for Linux, which may not be what you want. The platform here is actually the CLI argument, so cross-platform checks are done automatically. You may just need to write:

if itype == "docker" and osname == "linux": return (itype,) elif ...

lrandersson · 2026-05-14T13:08:39Z

@Jrice1317 I'd be happy to do a review once the items from Marco have been resolved, it'll also help me understand the changes better

Co-authored-by: Marco Esters <mesters@anaconda.com>

…constructor into docker-implementation

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 7 commits May 6, 2026 15:39

Regenerate schema

15a8b1f

Add docker_build to schema

a5704bb

Make whitespace adjustments

8db9e96

Fix logic regarding base image requirement

6d1d118

Make image portable

f65ecf3

Update wording

989fb30

Update docs

7338b72

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

Jrice1317 added 3 commits May 8, 2026 11:45

Revert to using one path

120d135

Revert back to docker load

be48dd1

Add output

18b7001

Jrice1317 marked this pull request as ready for review May 8, 2026 23:01

marcoesters reviewed May 12, 2026

View reviewed changes

Apply suggestions from code review

583191d

Co-authored-by: Marco Esters <mesters@anaconda.com>

Jrice1317 requested a review from marcoesters May 14, 2026 15:44

Jrice1317 added 2 commits May 14, 2026 13:58

Update logic

b047963

Merge branch 'docker-implementation' of https://github.com/Jrice1317/…

80ee0a7

…constructor into docker-implementation

Jrice1317 marked this pull request as draft May 14, 2026 22:47

Jrice1317 added 11 commits May 14, 2026 15:48

Change wording in schema

2dbe4eb

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

Conversation

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

Uh oh!

Description

Changes

New:

Updated:

Notes:

Checklist - did you ...

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jrice1317 May 13, 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!

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!

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!

Jrice1317 May 14, 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!

Choose a reason for hiding this comment

Uh oh!

Jrice1317 May 14, 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!

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!

lrandersson commented May 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Jrice1317 commented Apr 22, 2026 •

edited

Loading

Jrice1317 May 13, 2026 •

edited

Loading

Jrice1317 May 14, 2026 •

edited

Loading

Jrice1317 May 14, 2026 •

edited

Loading