Docker implementation

.pre-commit-config.yaml

@@ -17,8 +17,6 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
-    rev: v0.15.13
     rev: 5e2fb545eba1ea9dc051f6f962d52fe8f76a9794  # frozen: v0.15.13
     hooks:
       # Run the linter.

CONSTRUCT.md

@@ -236,6 +236,7 @@ The type of the installer being created. Possible values are:
 - `pkg`: macOS GUI installer built with Apple's `pkgbuild`
 - `exe`: Windows GUI installer built with NSIS
 - `msi`: Windows GUI installer built with Briefcase and WiX (experimental)
+- `docker`: generates a `Dockerfile` or image of the installation environment.
 
 The default type is `sh` on Linux and macOS, and `exe` on Windows. A special
 value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well
@@ -427,7 +428,8 @@ is `${HOME}/<NAME>` (or, if `HOME` is not set, `/opt/<NAME>`). On Windows,
 this is used only for "Just Me" installations; for "All Users" installations,
 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 using the flag `--build-arg PREFIX=/path/to/prefix`.
 
 ### `default_prefix_domain_user`
 
@@ -690,6 +692,42 @@ freeze_base:
         message: "This base environment is frozen and cannot be modified."
 ```
 
+### `docker_base_image`
+
+Required for Docker-related features.
+
+Base image to use for Docker builds and generated Dockerfiles. This can be any valid docker image reference, including a tag and/or digest.
+
+For example: `debian:13.4-slim@sha256:abc123...`.
+
+### `docker_tag`
+
+Tag to use for the Docker image.
+
+If not provided, defaults to `<name>:<version>`.
+
+Has no effect unless `docker_image_format` is specified.
+
+### `docker_labels`
+
+Additional labels to add to the Docker image.
+
+The labels `org.opencontainers.image.title` and `org.opencontainers.image.version`
+are set automatically from `name` and `version`.
+
+### `docker_image_format`
+
+Build and export a Docker image as a portable tarball.
+
+This feature only takes effect when both `installer_type: docker` and `docker_base_image` are set.
+
+The image is built using the Dockerfile generated by constructor and saved to the output directory.
+
+Currently, the only supported output format is `tar`. Additional formats, such as `gz` or `zst`, may be supported in the future.
+
+The output filename will be:
+``<name>-<version>-<platform>-<arch>-docker.tar``.
+
 
 ## Available selectors
 - `aarch64`

constructor/_schema.py

@@ -43,6 +43,7 @@ class InstallerTypes(StrEnum):
     MSI = "msi"
     PKG = "pkg"
     SH = "sh"
+    DOCKER = "docker"
 
 
 class PkgDomains(StrEnum):
@@ -405,6 +406,7 @@ class ConstructorConfiguration(BaseModel):
     - `pkg`: macOS GUI installer built with Apple's `pkgbuild`
     - `exe`: Windows GUI installer built with NSIS
     - `msi`: Windows GUI installer built with Briefcase and WiX (experimental)
+    - `docker`: generates a `Dockerfile` or image of the installation environment.
 
     The default type is `sh` on Linux and macOS, and `exe` on Windows. A special
     value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well
@@ -597,7 +599,8 @@ class ConstructorConfiguration(BaseModel):
     this is used only for "Just Me" installations; for "All Users" installations,
     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 using the flag `--build-arg PREFIX=/path/to/prefix`.
     """
     default_prefix_domain_user: NonEmptyStr | None = None
     """
@@ -865,6 +868,42 @@ class ConstructorConfiguration(BaseModel):
             message: "This base environment is frozen and cannot be modified."
     ```
     """
+    docker_base_image: Annotated[str, Field(min_length=1)] | None = None
+    """
+    Required for Docker-related features.
+
+    Base image to use for Docker builds and generated Dockerfiles. This can be any valid docker image reference, including a tag and/or digest.
+
+    For example: `debian:13.4-slim@sha256:abc123...`.
+    """
+    docker_tag: NonEmptyStr | None = None
+    """
+    Tag to use for the Docker image.
+
+    If not provided, defaults to `<name>:<version>`.
+
+    Has no effect unless `docker_image_format` is specified.
+    """
+    docker_labels: dict[NonEmptyStr, NonEmptyStr] = {}
+    """
+    Additional labels to add to the Docker image.
+
+    The labels `org.opencontainers.image.title` and `org.opencontainers.image.version`
+    are set automatically from `name` and `version`.
+    """
+    docker_image_format: Literal["tar"] | None = None
+    """
+    Build and export a Docker image as a portable tarball.
+
+    This feature only takes effect when both `installer_type: docker` and `docker_base_image` are set.
+
+    The image is built using the Dockerfile generated by constructor and saved to the output directory.
+
+    Currently, the only supported output format is `tar`. Additional formats, such as `gz` or `zst`, may be supported in the future.
+
+    The output filename will be:
+    ``<name>-<version>-<platform>-<arch>-docker.tar``.
+    """
 
 
 def fix_descriptions(obj):

constructor/data/construct.schema.json

@@ -246,7 +246,8 @@
         "exe",
         "msi",
         "pkg",
-        "sh"
+        "sh",
+        "docker"
       ],
       "title": "InstallerTypes",
       "type": "string"
@@ -609,7 +610,7 @@
         }
       ],
       "default": null,
-      "description": "Set default install prefix. On Linux, if not provided, the default prefix is `${HOME}/<NAME>` (or, if `HOME` is not set, `/opt/<NAME>`). On Windows, this is used only for \"Just Me\" installations; for \"All Users\" installations, use the `default_prefix_all_users` key. If not provided, the default prefix is `%USERPROFILE%\\<NAME>`. Environment variables will be expanded at install time.",
+      "description": "Set default install prefix. On Linux, if not provided, the default prefix is `${HOME}/<NAME>` (or, if `HOME` is not set, `/opt/<NAME>`). On Windows, this is used only for \"Just Me\" installations; for \"All Users\" installations, use the `default_prefix_all_users` key. If not provided, the default prefix is `%USERPROFILE%\\<NAME>`. Environment variables will be expanded at install time. If creating a docker output, the default is `/opt/<NAME>` and can be overridden during the Docker build process using the flag `--build-arg PREFIX=/path/to/prefix`.",
       "title": "Default Prefix"
     },
     "default_prefix_all_users": {
@@ -640,6 +641,61 @@
       "description": "Set default installation prefix for domain users. If not provided, the installation prefix for domain users will be `%LOCALAPPDATA%\\<NAME>`. By default, it is different from the `default_prefix` value to avoid installing the distribution into the roaming profile. Environment variables will be expanded at install time. Windows only.",
       "title": "Default Prefix Domain User"
     },
+    "docker_base_image": {
+      "anyOf": [
+        {
+          "minLength": 1,
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Required for Docker-related features.\nBase image to use for Docker builds and generated Dockerfiles. This can be any valid docker image reference, including a tag and/or digest.\nFor example: `debian:13.4-slim@sha256:abc123...`.",
+      "title": "Docker Base Image"
+    },
+    "docker_image_format": {
+      "anyOf": [
+        {
+          "const": "tar",
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Build and export a Docker image as a portable tarball.\nThis feature only takes effect when both `installer_type: docker` and `docker_base_image` are set.\nThe image is built using the Dockerfile generated by constructor and saved to the output directory.\nCurrently, the only supported output format is `tar`. Additional formats, such as `gz` or `zst`, may be supported in the future.\nThe output filename will be: ``<name>-<version>-<platform>-<arch>-docker.tar``.",
+      "title": "Docker Image Format"
+    },
+    "docker_labels": {
+      "additionalProperties": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "default": {},
+      "description": "Additional labels to add to the Docker image.\nThe labels `org.opencontainers.image.title` and `org.opencontainers.image.version` are set automatically from `name` and `version`.",
+      "propertyNames": {
+        "minLength": 1
+      },
+      "title": "Docker Labels",
+      "type": "object"
+    },
+    "docker_tag": {
+      "anyOf": [
+        {
+          "minLength": 1,
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "description": "Tag to use for the Docker image.\nIf not provided, defaults to `<name>:<version>`.\nHas no effect unless `docker_image_format` is specified.",
+      "title": "Docker Tag"
+    },
     "environment": {
       "anyOf": [
         {
@@ -866,7 +922,7 @@
         }
       ],
       "default": null,
-      "description": "The type of the installer being created. Possible values are:\n- `sh`: shell-based installer for Linux or macOS\n- `pkg`: macOS GUI installer built with Apple's `pkgbuild`\n- `exe`: Windows GUI installer built with NSIS\n- `msi`: Windows GUI installer built with Briefcase and WiX (experimental)\nThe default type is `sh` on Linux and macOS, and `exe` on Windows. A special value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well as `sh` on Linux and `exe` on Windows.",
+      "description": "The type of the installer being created. Possible values are:\n- `sh`: shell-based installer for Linux or macOS\n- `pkg`: macOS GUI installer built with Apple's `pkgbuild`\n- `exe`: Windows GUI installer built with NSIS\n- `msi`: Windows GUI installer built with Briefcase and WiX (experimental)\n- `docker`: generates a `Dockerfile` or image of the installation environment.\nThe default type is `sh` on Linux and macOS, and `exe` on Windows. A special value of `all` builds _both_ `sh` and `pkg` installers on macOS, as well as `sh` on Linux and `exe` on Windows.",
       "title": "Installer Type"
     },
     "keep_pkgs": {