cs-image-system-docker-runtime-plugin 0.1.6__py3-none-any.whl

cs_image_system/docker_runtime/docker_runtime_models.py

@@ -0,0 +1,110 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The docker runtime's model (stage 103): the daemon's address, the
+repository builds are tagged into, the state manager its roots use."""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from cs_image_system.contract.constants import DEFAULT, VCT
+from cs_image_system.contract.fields import fk_field
+from cs_image_system.contract.model_config import CSIS_MODEL_CONFIG
+from pydantic.dataclasses import dataclass  # stage 23: validation at construction
+
+from cs_image_system.base.models.container_builder import ContainerBuilderModel
+from .docker_names import repository_name
+
+log = logging.getLogger(__name__)
+
+DOCKER: str = "docker"
+
+
+@dataclass(kw_only=True, config=CSIS_MODEL_CONFIG)
+class DockerContainerBuilderModel(ContainerBuilderModel):
+    """Any daemon that speaks the Docker Engine API (Docker Engine, Docker
+    Desktop, OrbStack, colima, Podman's API service), reached through the
+    ``docker`` CLI the ``executable`` entry names and the daemon address
+    ``host`` or ``context`` gives. Nothing here is a credential: TLS
+    material is a path (``tls_cert_path``, docker's ``DOCKER_CERT_PATH``)
+    and ``host`` may be an ENC marker when the address itself is private."""
+    type = DOCKER
+    # the cfg/executables.yml entry every docker call on this runtime runs
+    # through, as the GCE runtime names its gcloud (stage 63 item 14)
+    executable: str | None = "docker"
+    # where this runtime's builds are tagged: `<repository>:<final name>`
+    # and the series' floating `<repository>:<prefix>`; default
+    # `csis/<runtime name>`, made a valid repository name
+    repository: str | None = None
+    # DOCKER_CERT_PATH and DOCKER_TLS_VERIFY for a `tcp://` host
+    tls_cert_path: str | None = None
+    tls_verify: bool = False
+    state_configuration: str = fk_field(target=VCT.STATE_BACKEND_MODEL,
+                                        default=DEFAULT,
+                                        metadata={
+                                            "description": "The state manager this runtime's roots use",
+                                            "required": True,
+                                        })
+
+    @classmethod
+    def csis_name(cls) -> str:
+        return DOCKER
+
+    def get_repository(self) -> str:
+        return repository_name(self.repository or f"csis/{self.name}")
+
+    def get_host_plain(self) -> str | None:
+        """The daemon address, an ENC marker opened (never logged)."""
+        host = self.host
+        if not host:
+            return None
+        from cs_image_system.base.encryption import decrypt_marker, is_marker
+        return decrypt_marker(host) if is_marker(host) else str(host)
+
+    def daemon_environment(self) -> dict[str, str]:
+        """The environment a docker CLI (packer's docker plugin, ansible's
+        docker connection, the system's own calls) reaches THIS daemon
+        with: ``DOCKER_HOST`` or ``DOCKER_CONTEXT``, and the TLS pair when
+        declared. Empty when the runtime names no address: the daemon the
+        caller's environment names. A ``host`` that is an ENC marker stays
+        the marker here (an ``ExecutableModel`` opens it when it runs and
+        the runner script renders it as a `decrypt` call); ``process_environment``
+        is the opened form for the system's own calls."""
+        env: dict[str, str] = {}
+        if self.host:
+            # the loader opens a marker into a value that remembers its
+            # ciphertext; `emit` gives the ciphertext back (stage 49)
+            from cs_image_system.base.encryption import emit
+            env["DOCKER_HOST"] = str(emit(self.host))
+        elif self.context:
+            env["DOCKER_CONTEXT"] = str(self.context)
+        if self.tls_cert_path:
+            env["DOCKER_CERT_PATH"] = str(self.tls_cert_path)
+        if self.tls_verify:
+            env["DOCKER_TLS_VERIFY"] = "1"
+        return env
+
+    def process_environment(self) -> dict[str, str]:
+        """The caller's environment with the daemon's on top."""
+        env = dict(os.environ)
+        env.update(self.daemon_environment())
+        host = self.get_host_plain()
+        if host:
+            env["DOCKER_HOST"] = host
+        return env
+
+    def where(self) -> str:
+        """How the daemon is addressed, for messages (never the plain host
+        of an ENC marker)."""
+        if self.host:
+            from cs_image_system.base.encryption import emit, is_marker
+            return "host (encrypted)" if is_marker(emit(self.host)) else f"host {self.host}"
+        if self.context:
+            return f"context {self.context}"
+        return "the environment's daemon"
+
+    def self_to_client_config(self) -> dict[str, Any]:
+        return {"environment": self.daemon_environment(), "repository": self.get_repository()}

cs_image_system/docker_runtime/main.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+
+from cs_image_system.base.basic.abstract_plugin_metadata import AbstractPluginMetadata
+from .docker_runtime_builders import DOCKER_RUNTIME, DockerCLIVersionChecker, DockerContainerBuilder
+from .docker_runtime_models import DockerContainerBuilderModel
+
+log = logging.getLogger(__name__)
+
+
+class DockerRuntimePluginMetadata(AbstractPluginMetadata):
+    def __init__(self) -> None:
+        super().__init__("1", "3.13",
+                         {DOCKER_RUNTIME: [
+                             DockerContainerBuilderModel,
+                             DockerContainerBuilder,
+                             DockerCLIVersionChecker,
+                         ]},
+                         {DockerContainerBuilderModel: DockerContainerBuilder})
+
+
+def initialize():
+    log.debug("Initializing docker runtime plugin")
+    return DockerRuntimePluginMetadata()

cs_image_system_docker_runtime_plugin-0.1.6.dist-info/METADATA

@@ -0,0 +1,268 @@
+Metadata-Version: 2.5
+Name: cs-image-system-docker-runtime-plugin
+Version: 0.1.6
+Summary: The docker runtime type: a durable host's container daemon as a place where images bake and instances run
+Project-URL: Repository, https://github.com/infrastructurebuilder/cs-image-system-3
+Project-URL: Documentation, https://github.com/infrastructurebuilder/cs-image-system-3/blob/develop/docs/OPERATIONS.md
+Project-URL: Package README, https://github.com/infrastructurebuilder/cs-image-system-3/blob/develop/packages/docker-runtime-plugin/README.md
+Author-email: Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: cs-image-system-base==0.1.6
+Requires-Dist: cs-image-system-contract==0.1.6
+Requires-Dist: cs-image-system-hashicorp-utils==0.1.6
+Requires-Dist: pydantic>=2.13
+Requires-Dist: python-hcl2>=8.1
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2026 Mykel Alvis <mykelalvis@infrastructurebuilder.org>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# cs-image-system-docker-runtime-plugin
+
+The `docker` runtime type (stage 103): a durable host running a daemon that
+speaks the Docker Engine API, as a place where images bake and instances
+run. Docker Engine, Docker Desktop, OrbStack, colima and Podman's API
+service all qualify; the system reaches the daemon through the `docker` CLI
+the tree's `cfg/executables.yml` names and the address the runtime declares
+(`host`, a `DOCKER_HOST` URL, or `context`, a docker context), never through
+a cloud API. containerd with nerdctl has no Docker API and is not a target.
+
+A container runtime is the third kind of runtime beside the two clouds. It
+differs from them in three ways the design records as decisions:
+
+- **No init system.** An image this runtime bakes carries the keepalive
+  `sleep infinity` as its command and runs under `--init`; the launch work
+  is done by `exec` after the container is created. Services that need
+  systemd are not supported on this runtime, and an image test that checks
+  an enabled service does not apply here.
+- **Images live in the daemon's store.** A build is its image id
+  (`sha256:...`), and its names are tags: `<repository>:<final name>` and
+  the series' floating `<repository>:<prefix>`, which a child image bakes
+  from when its parent is deferred (the daemon has no "newest image matching
+  a pattern" query; the tag is that query). A label is fixed when an image
+  is built, so what the core stamps afterwards (the parent bound after the
+  bake, the fingerprint, a release) is carried by tags that MOVE:
+  `<repository>:<short id>--<key>--<value>`, one per key.
+- **POSIX accounts only.** Access is through the daemon (`docker exec -u`);
+  whoever can reach the daemon is root on the host. An OPA group on a docker
+  runtime is refused at validation; enrolling `sftd` in a container is a
+  later stage.
+
+## What it registers
+
+| Class | `csis_name()` | `csis_classifier()` | Role |
+|---|---|---|---|
+| `DockerContainerBuilderModel` ([docker_runtime_models.py](src/cs_image_system/docker_runtime/docker_runtime_models.py)) | `docker` | `VCT.CONTAINER_BUILDER_MODEL` (folded into the runtime namespace by the loader) | The runtime's declaration: `host` or `context`, `repository`, `machine_types`, `networking`, `state_configuration`, `executable`. |
+| `DockerContainerBuilder` ([docker_runtime_builders.py](src/cs_image_system/docker_runtime/docker_runtime_builders.py)) | `docker` | `VCT.RUNTIME_BUILDER` | Every runtime hook, answered against the daemon through the CLI. |
+| `DockerCLIVersionChecker` (same file) | `docker` | `VCT.VERSION_CHECKER` | `docker --version` for the `docker` entry of `cfg/executables.yml`. |
+
+Entry points: `cs_image_system.plugins.runtime` → `docker`, and (stage 103
+item 15) `cs_image_system.bootstrap` → `docker`, the container-host section of
+the bootstrap interview ([bootstrap.py](src/cs_image_system/docker_runtime/bootstrap.py)):
+
+| Class / function | Role |
+|---|---|
+| `docker_section()` → `Section` | The interview's "Container host" section. Wanted where the tree declares a docker runtime. It reads the runtime from the raw `cfg/` (never loading it, never printing an address: a `host` may be an `ENC[age:...]` marker) and asks two questions, which runtime and *can CI reach its daemon* (default yes for an `ssh://` host or for none declared, no for a socket, a context, a `tcp://` host or a marker). |
+
+The section has no terraform module, because a daemon is a host somebody runs.
+Its render says what remains by hand (the daemon and its host, the network,
+CI's ssh key and `known_hosts` line, or, when CI cannot reach the daemon, to
+name the runtime in `GUARD_RUNTIME`) and its audit lines are all BY HAND or
+READ. The two secrets it concerns, `DOCKER_HOST_SSH_KEY` and
+`DOCKER_HOST_KNOWN_HOSTS`, are among the GitHub section's, set by its script
+from files.
+
+## Models
+
+### `DockerContainerBuilderModel`
+
+Extends the core's `ContainerBuilderModel` (`host`, `context`, `networking`,
+`machine_types`) and the runtime model every runtime shares
+(`default_machine_type`, `default_image_builder`, `credentials`, `ephemeral`,
+`retention_keep`, ...).
+
+| Field | Default | Meaning |
+|---|---|---|
+| `host` | none | The daemon's address as a `DOCKER_HOST` URL: `unix:///var/run/docker.sock`, `ssh://user@host`, `tcp://host:2376`. May be an `ENC[age:...]` marker when the address itself is private. Declare `host` or `context`, not both. |
+| `context` | none | A docker context name (`docker context ls`), set as `DOCKER_CONTEXT`. |
+| `executable` | `docker` | The `cfg/executables.yml` entry whose `binary` every docker call on this runtime runs through; `validate` version-checks it. |
+| `repository` | `csis/<runtime name>` | Where this runtime's builds are tagged, made a valid repository name (lowercase). |
+| `tls_cert_path`, `tls_verify` | none, false | `DOCKER_CERT_PATH` and `DOCKER_TLS_VERIFY` for a `tcp://` host: TLS material by PATH, never a value. |
+| `networking.network` | `bridge` | The network the bake container (and, later, every instance) joins, by name; referenced, never created or changed. No subnets, no zones. |
+| `machine_types` | `{}` | A map from a name to `{cpus, memory}` (`--cpus 2`, `--memory 4g`). When any are declared, `default_machine_type` must name one. |
+| `state_configuration` | the default state manager | The state manager this runtime's roots use; a tree with no cloud declares `local`. |
+
+Nothing in the model is a credential.
+
+## The builder
+
+### The image query
+
+The daemon answers the keys `name` (a repository), `version` (a tag),
+`publisher` (a registry namespace; `library` is Docker Hub's and is
+dropped), `architecture` (a platform, `x86_64` → `linux/amd64`) and
+`native.image` (a reference verbatim). The release catalog's `docker` block
+gives every family one (`almalinux:{version}`, `debian:{version}`, ...). The
+query PULLS the reference and records its digest reference
+(`<repository>@sha256:...`) as the identifier, so a vendor moving a tag shows
+as a move. An entry's `image_id` pins a digest reference; a tag is refused
+there, because a tag moves.
+
+### Bakes
+
+`packer_source_type()` is `docker`, HashiCorp's docker plugin. The source
+block starts the build container from the parent image (`pull = false`: the
+query pulled every vendor image, and our own builds are local), named
+`csis-bake-<runtime>-<image>` so ansible reaches it by name, under `--init`,
+on the runtime's network, with its machine type's limits, with `/run` a
+tmpfs so the step runner never lands in the image; it `commit`s the result
+with the lineage tags as `LABEL` instructions and `CMD ["sleep",
+"infinity"]`. The runtime adds a `docker-tag` post-processor to the build
+(the final name and the floating tag, in the repository), and the manifest
+records the committed image id as the build id. The ansible provisioner
+connects with `ansible_connection=docker ansible_host=<container name>`,
+passed as `--extra-vars`, the way packer's provisioner documents for its
+docker builder. Bakes run as `root`; the settle step installs `sudo` and
+`python3` when the vendor image lacks them, because every later step is
+written for a cloud image's unprivileged user. No cloud-init wait, no
+session agent.
+
+Every tool a bake runs (packer, the docker CLI, ansible's docker connection)
+gets the runtime's `DOCKER_HOST` or `DOCKER_CONTEXT` in its environment
+(`tool_environment()`), so a bake on a remote daemon reaches that daemon.
+
+### Names
+
+A build's final name is written as a tag: `image_name_as_made` replaces what
+a tag cannot carry with `-`; `image_name_problem` refuses a name longer than
+128 characters once made (the cut would fall where the timestamp is). A
+label key carries no whitespace and no `=`.
+
+### Images in the store
+
+`query_images` lists every image labelled `csis_series`, its lineage facts
+read from its labels as built with the movable tags' values on top;
+`inventory` adds every container and volume, with the `csis_config` label
+each carries. `dispose_image` removes a build and every tag with it, and is
+REFUSED while a container was created from it. `retag_image` moves the
+per-key tags; `release_commands` moves `<repository>:<series>--<model>`.
+
+### Instances
+
+The instance hooks (power state, identity, verification, sessions,
+relabel) are the next branch of stage 103; on this branch they answer as the
+core's defaults do ("cannot").
+
+## Example configuration
+
+```yaml
+runtime_builders:
+  - name: docker-local
+    type: docker
+    context: orbstack                 # or host: unix:///var/run/docker.sock
+    executable: docker
+    repository: csis/local
+    default_machine_type: small
+    default_image_builder: pckr-docker-ans
+    machine_types:
+      small: { cpus: 1, memory: 1g }
+      medium: { cpus: 2, memory: 4g }
+    networking:
+      network: bridge
+    state_configuration: local-state
+
+image_builders:
+  - name: pckr-docker-ans
+    type: packer-docker
+    runtime: docker-local
+    executable: packer
+    required_plugins:
+      - name: docker
+        source: github.com/hashicorp/docker
+        version: '>= 1.0.0'
+      - name: ansible
+        source: github.com/hashicorp/ansible
+        version: '>= 1.0.0'
+```
+
+## Prerequisites and integration
+
+- A daemon that speaks the Docker Engine API, reachable from the machine
+  that runs the system: `docker version` against the runtime's `host` or
+  `context` must answer (preflight says so in one line per daemon).
+- The `docker` CLI, declared in `cfg/executables.yml` (`version: ">=24"`
+  is the floor the system runs with); `--init` needs the daemon's
+  `docker-init`, which every supported daemon ships.
+- `packer` with the `docker` and `ansible` plugins (`required_plugins` of
+  the image builder), and `ansible-playbook` on the machine that bakes:
+  ansible's docker connection runs the local `docker` CLI against the same
+  daemon.
+- Podman's API service works as the daemon (proved 2026-11-01 against Podman
+  5.8.2 rootless on AlmaLinux 10, through `docker` over ssh; the setup and what
+  differed are in [docs/OPERATIONS.md](../../docs/OPERATIONS.md), "Podman as
+  the daemon"). A rootless Podman user needs `/etc/subuid` and `/etc/subgid`
+  ranges. Podman Desktop's machine on macOS works too, rootful and beside
+  OrbStack (proved 2026-11-01 with Podman 5.8.9; `just
+  test-podman-desktop-cycle`, which skips when no machine runs; Podman 6
+  dropped Intel Macs, so on one the proof lasts until June 2027).
+- The posix identity plugin for the groups an instance image activates; an
+  OPA group is refused on this runtime.
+- A tree whose only runtime is docker declares a `local` state manager; a
+  tree with clouds may put the docker roots in its default manager, and
+  then needs that cloud's session for them.
+
+## Configuration reference
+
+See [Models](#models) for every field of the runtime, and the image
+builder's reference in the [packer plugin](../packer-plugin/README.md) for
+`type: packer-docker`. An OS builder's `runtimes[]` entry on a docker
+runtime takes the usual keys; its `query` may use `name`, `version`,
+`publisher`, `architecture` and `native.image`, and its `image_id` is a
+digest reference. `output_image_name` (stage 105) is the tag prefix.
+
+## What it tests and verifies
+
+- `validate` version-checks the `docker` executable and refuses a query key
+  the daemon cannot answer, a label key it cannot carry, a build name longer
+  than a tag, a `default_machine_type` that names no declared machine type,
+  and a runtime that declares both `host` and `context`.
+- `preflight` runs `docker version` against each docker runtime's daemon
+  and prints whether it answers.
+- The unit tests ([tests/](tests/)) pin the names module (tags, repository
+  names, movable tags), the query translation, the model's environment and
+  the packer source and post-processor shapes without a daemon; the
+  system's stage 103 tests drive a dry `run --all` over an overlay of the
+  frozen fixture and check the emitted docker sources.
+- `just test-docker-bake`, a leg of `just full-test`, bakes an AlmaLinux 10
+  and a Debian 12 base image and an instance image on the local daemon,
+  checks the lineage and the tags, disposes them, and skips loudly without
+  docker.
+- The bootstrap section is tested without a daemon: its discovery and
+  wanting, the reach rule (an `ssh://` host or none declared is reachable;
+  a socket, a context, `tcp://` and a marker are not), the quiet interview
+  of the `standard-docker` starter, the guard default in a tree with a
+  runtime CI cannot reach, and that no address or marker reaches the
+  generated README.
+
+## When it fails
+
+| Symptom | Cause | Remedy |
+|---|---|---|
+| `the configuration cannot load: docker runtime X: the daemon at ... cannot be reached` | The daemon is not running, or `host`/`context` names the wrong one. | Start it (OrbStack, Docker Desktop, the engine on the host) or fix the address; `preflight` shows which daemon answers. |
+| `executable 'docker' is not declared in cfg/executables.yml` | The runtime's `executable` names no entry. | Declare `- name: docker` with its `binary`. |
+| `image_id '...' is not a digest reference` | An entry pins a tag. | Pin `<repository>@sha256:<digest>` (`docker image inspect --format '{{index .RepoDigests 0}}'`). |
+| `image ... is in use by container(s) ...` at disposal | A container stands on the build. | Decommission the container first; the image is never pulled from under it. |
+| An ansible step cannot reach the container | The bake ran against a daemon other than the one the local `docker` CLI uses. | The runtime's `host`/`context` is what both read; check `DOCKER_HOST` is not also set in the shell to something else. |
+| The bootstrap says `docker.runtime: ... -- no default can be derived` under `--quiet` | The tree declares no runtime of type `docker`, or the section was kept from an earlier interview of a tree that had one. | Declare the runtime, or answer `want_docker: no`. |
+| `parent: lineage=<id> tag=series:<name>` in the state query on a Podman daemon | A release before 2026-11-01 compared `RepoTags` as written; Podman spells them `docker.io/<repository>:<tag>`. | Take a later release; nothing on the daemon needs repairing, the movable tags were there. |
+| `a docker tag is at most 128 characters` at validate | A declared `output_image_name` is too long once the timestamp is appended. | Shorten it. |
+
+## Related
+
+- [docs/OPERATIONS.md](../../docs/OPERATIONS.md), [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md)
+- [packer-plugin](../packer-plugin/README.md) (`type: packer-docker`), [posix-identity-plugin](../posix-identity-plugin/README.md)

cs_image_system_docker_runtime_plugin-0.1.6.dist-info/RECORD

@@ -0,0 +1,13 @@
+cs_image_system/docker_runtime/__init__.py,sha256=GAFRNaGWQxXquHOlCzxan4LkPZ9_NsiyswknxdPcX0c,122
+cs_image_system/docker_runtime/bootstrap.py,sha256=rn3Ci6hgs13PXIYalrW0knLwDUfbxYgsBRwGphjKzGg,6851
+cs_image_system/docker_runtime/docker_names.py,sha256=pH7mHa75R8kL3kmqqeZVlWILflomyNV03DT92K16FKc,5277
+cs_image_system/docker_runtime/docker_packer_source.py,sha256=ADQYwaYAA_vUzZIOINCKbniyi2o5QTGLEMbI4gKJ5b8,6357
+cs_image_system/docker_runtime/docker_provider_specific_image.py,sha256=IQ6zketZo5XIcyFH_2uHekszaxMgpEze9v-pWM88Px4,1648
+cs_image_system/docker_runtime/docker_runtime_builders.py,sha256=Kr13HhOLNbIlLc2mcgp7bY959nstPNiwnKduv-71II8,31201
+cs_image_system/docker_runtime/docker_runtime_models.py,sha256=UsEqPB6R1PEW2XsGYaGVAuM250aBXhjObIIH5xdTe5U,4918
+cs_image_system/docker_runtime/main.py,sha256=FoqLjpfeRfD-GXagLWWJvzBJ1gubjVEpEE5JvLcjwXM,987
+cs_image_system_docker_runtime_plugin-0.1.6.dist-info/METADATA,sha256=zajsQAZWvfUxxK4IXqj1RmA4r8vaXbiP3hAKtUWsV2c,15653
+cs_image_system_docker_runtime_plugin-0.1.6.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cs_image_system_docker_runtime_plugin-0.1.6.dist-info/entry_points.txt,sha256=RoyG2hCucc51toGWDkj303RuYGeHCCSymuMOtAqB8XA,184
+cs_image_system_docker_runtime_plugin-0.1.6.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cs_image_system_docker_runtime_plugin-0.1.6.dist-info/RECORD,,

cs_image_system_docker_runtime_plugin-0.1.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cs_image_system_docker_runtime_plugin-0.1.6.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[cs_image_system.bootstrap]
+docker = cs_image_system.docker_runtime.bootstrap:docker_section
+
+[cs_image_system.plugins.runtime]
+docker = cs_image_system.docker_runtime.main:initialize

cs_image_system_docker_runtime_plugin-0.1.6.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.