docker-devkit 0.4.1__tar.gz → 0.4.2__tar.gz

{docker_devkit-0.4.1 → docker_devkit-0.4.2}/AGENTS.md

@@ -22,15 +22,15 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 | Module | Role |
 |---|---|
-| `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--dev`. |
-| `down.py` | `docker compose down`. Flags: `--volumes`/`-v` (also removes named volumes), `--gpu`. |
+| `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--dev`. Resolves `COMPOSE_PROFILES` (shell env over `.env`), rejects values naming profiles the compose files don't define, and forwards the selection as explicit `--profile` flags — compose ignores the variable whenever any flag is present, so forwarding is the only reliable path. |
+| `down.py` | `docker compose down`. Flags: `--volumes`/`-v` (also removes named volumes), `--gpu`. Activates every profile declared across the assembly (via `config --profiles`), so teardown covers containers from a prior bring-up under a different `COMPOSE_PROFILES` selection. |
 | `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per the resolved image manifest, writing the paired lock (one `NAME={prefix}/{ref}@sha256:…` entry per upstream-native `x-base-images` declaration, the mirror-prefixed form derived from `mirror.prefix`; `@digest`-pinned declarations pass through unresolved; digests resolve against the upstream reference). `--push` is the CI shape (push images + registry caches + digest-manifest shelving) and hard-requires `x-registry-cache`; the flag order mirrors the binding's run line (`--push`, `--targets`, `--gpu`), and `--targets` accepts both repeated flags and one space-joined value. Push mode reads its registry facts from the neutral `REGISTRY`/`REGISTRY_TOKEN`/`REGISTRY_USERNAME` environment — no `GITHUB_*` reads. |
 | `score_generate.py` | `generate-score` — deterministic Score-manifest generation from a consumer's `stack/score/` sources: `${ALL_CAPS}` placeholder expansion into tempdir-rendered workload copies, idempotent `score-compose`/`score-k8s` init (state preserved across runs), and a determinism suite (document sort, state-path normalisation, 0644 modes, LF newlines). Consumer policy — workloads, provisioners, patch templates, output paths, storage classes, publishes, tool versions — is declared in the consumer's root `docker-devkit.yaml` under `generate-score:` (`ScoreConfig`, model in `config.py`); `load_score_config()` reads it, `ensure_score_tools()` fetches the pinned score-compose/score-k8s release binaries (for CI staleness gates). Output and state paths resolve against the repo root: the compose half runs in `score_dir` (its `.score-compose` state stays there, gitignored), the k8s half runs in the configured `k8s_state` parent so the committed `.score-k8s` state lands in the generated tier. `--local` writes the k8s artifact to the configured gitignored local path with the local storage class. |
 | `config.py` | `DockerDevkitConfig` — the root `docker-devkit.yaml` schema: a required `requires` PEP 440 specifier plus optional `lifecycle` / `mirror` / `generate-score` sections, `extra="forbid"` on every model. `load_config(root)` is the single strictyaml entry point: parses the file (returns `None` when absent — the no-config → single-file-default path for `up`/`down`), then self-checks the installed docker-devkit version against `requires` (refuses loudly outside range; the `0.0.0.dev0` dev sentinel bypasses the check, not the field). The section models (`LifecycleConfig`, `MirrorConfig`, `ScoreConfig`) live here; `load_lifecycle_config` / `load_mirror_config` / `load_score_config` in their modules are thin wrappers over it. |
-| `lifecycle.py` | `LifecycleConfig` (model in `config.py`) — the `lifecycle:` section declaration (`files`: compose files in layering order with `{gpu}` templating; `dev_file`: optional dev overlay); `load_lifecycle_config()` (reads the `lifecycle:` section via `config.load_config`, `None` when the section or file is absent), `resolve_manifest()` / `require_manifest()` (the raising form) / `resolve_lock()` (the image manifest and its lock are a named pair — `workloads/images.yml` + `workloads/images.lock`), `enforce_bake_declaration()` (a manifest requires a declaration), `expand_compose_files()` (assembles the `-f` list; a `{gpu}` entry is dropped when the GPU resolves to `none`; `dev_file` appended when a dev overlay applies). |
+| `lifecycle.py` | `LifecycleConfig` (model in `config.py`) — the `lifecycle:` section declaration (`files`: compose files in layering order with `{gpu}` templating; `dev_file`: optional dev overlay); `load_lifecycle_config()` (reads the `lifecycle:` section via `config.load_config`, `None` when the section or file is absent), `resolve_manifest()` / `require_manifest()` (the raising form) / `resolve_lock()` (the image manifest and its lock are a named pair — `workloads/images.yml` + `workloads/images.lock`), `enforce_bake_declaration()` (a manifest requires a declaration), `expand_compose_files()` (assembles the `-f` list; a `{gpu}` entry is dropped when the GPU resolves to `none`; `dev_file` appended when a dev overlay applies); `enumerate_profiles()` (asks compose for every profile the assembly defines — `down`'s teardown set and `up`'s existence-check source). |
 | `detect_gpu.py` | `detect_gpu()` → `cuda`/`rocm`/`none` from host devices; the `Gpu` literal. |
 | `matrix.py` | `docker-build-matrix` — emit the CI build leg list as a bare JSON array on stdout (the binding's getter pipes it through its `matrix` verb, which composes the envelope and guards the empty case): one entry per variant × cohort cell, `targets` = that cell's explicitly-buildable services with dependents grouped with the base their `additional_contexts: target:` references pull in (one leg builds a whole dependency-closure group in a single bake invocation). The leg schema — `targets` (space-joined), `variant` (`common`/`cuda`/`rocm`, from the service-name suffix) — is named contract with the binding; renaming a key breaks its fanout YAML. The cross-compile cohort (services in `x-cross-compile-targets` or declaring `platforms:`) gets its own legs — per-arch builds are the QEMU-slow ones and parallelize away from native builds; a group spanning cohort membership is a loud error. Tagless services never become explicit targets (bake rejects a tagless target under `--push`) — they ride as in-invocation dependencies; a group spanning gpu variants is a loud error. |
-| `modes.py` | `resolve_auth_mode()` — validates `PUBLIC_URL` + `AUTH_MODE` from `.env`, rejecting `keycloak` over cleartext `http://`. |
+| `modes.py` | `resolve_compose_profiles()` — resolves `COMPOSE_PROFILES` (shell env over `.env`, comma-split, deduped) for `up` to forward; `parse_env_file()` — the shared `.env` reader. Carries no consumer-domain knowledge. |
 | `context_sha.py` | `compute_service_shas(repo_root, bake: BakeDocument)` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. The workload-tree root is derived as the single top-level directory containing every tagged service's Dockerfile (a bake graph spanning several top-level directories is a loud error); files under it that belong to no tagged service are excluded from every SHA rather than shared into all of them. |
 | `documents.py` | `BakeDocument` + `parse_bake(path)` — the typed bake-file model every consumer of bake data goes through (build, up, down, generate-score, the reference collectors). A field validator enforces at parse time that every `x-base-images` value is `path:tag` or `path@digest` (a `${…}` hole or a bare path is a validation error, killing the silent-unpinned `FROM` → `:latest` failure mode). `digest_pinned(reference)` is the shared tail test. |
 | `image_refs.py` | Image-reference collection, split by source. `declared_references(root)` enumerates bake `x-base-images` declarations from `workloads/images.yml` (parsed and validated via `BakeDocument`) — the single source consumer mirroring consumes. `stray_references(root, …globs)` scans Dockerfile `FROM`, Dockerfile `COPY --from=` (slash-bearing captures only, so build-stage names are skipped), and yaml `image:` lines — hand-written literal refs that bypass the declaration system — across the `workloads/` and `docker/` Dockerfile trees and the `stack/score/` + `score/` source trees; `unpinned_references(root)` polices exactly those strays (every slash-bearing reference must carry a tag, a digest, or a trailing `${build-arg}` suffix — consumer CIs fail on its result). `bake_base_image_refs(bake: BakeDocument)` adapts declarations to `ImageReference` pairs; `version_coupling_violations(root, couplings)` (each `VersionCoupling` names a pyproject-declared version and the `VersionSite` regexes that must restate it — bake `x-base-images` values or raw file text — so non-derivable couplings like uv `required-version` ↔ uv-base-image tag can't drift silently; the mechanism lives here, the registry in consumer repos' preflight) is unchanged. Remote digest resolution goes through `imagetools inspect`. Compose files are parsed by nothing in this package. |
@@ -42,11 +42,13 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 placeframe's shape lives in placeframe's `docker-devkit.yaml`, not in this package: a `lifecycle` section with `files` = `compose.yml`, `compose.postgres.yml`, `compose.{gpu}.yml` (in layering order) and `dev_file` = `compose.dev.yml`.
 
+Profile-gated services are selected solely by `COMPOSE_PROFILES`; the verbs hold no built-in profile names. `up` fails loudly on a selection naming undefined profiles (the silent alternative is a stack that comes up minus its gated services); `down` ignores the selection and enumerates everything defined, since teardown must cover prior bring-ups under other selections.
+
 `--quiet-pull` suppresses compose's per-layer progress (CUDA images carry hundreds of layers) while still surfacing pull totals. `--gpu auto` resolves to `cuda`/`rocm`/`none` from host devices and selects the matching `compose.<gpu>.yml`; override only to reproduce a CI environment or test the CPU-only path.
 
 ## File and env conventions the commands assume
 
-- `.env` (required) — carries `PUBLIC_URL` and `AUTH_MODE`; `modes.py` reads it and rejects `keycloak` over cleartext `http://`.
+- `.env` (required) — carries `COMPOSE_PROFILES` (the sole service selector `up`/`down` consult) plus whatever variables the consumer's compose files interpolate.
 - `workloads/images.lock` (required in every repo, checked in) — third-party and base-image pins, written by `build`: one `NAME={prefix}/{ref}@sha256:…` entry per manifest declaration. `up`/`down` refuse without it; consumers satisfy it with a committed lock filling the `${…_IMAGE:?err}` holes. The lock sits beside its manifest as the resolved pair.
 - `workloads/images.yml` (where a local build graph exists, required) — the image manifest and buildx-bake description; its top-level `x-cross-compile-targets` list (optional) is the set of services excluded from the default target list because they need per-arch treatment, opt-in via `--targets`. `build` reads exactly one manifest: `workloads/images.yml`. `buildx bake` resolves the manifest's relative paths against its invocation cwd, so `build` always invokes from the repo root.
 - the compose layers declared in the `lifecycle:` section of `docker-devkit.yaml`; the GPU one is picked by `detect_gpu()` (or the `--gpu` override).

{docker_devkit-0.4.1 → docker_devkit-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.4.1
+Version: 0.4.2
 Summary: Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly
 License-File: LICENSE
 License-File: NOTICE

{docker_devkit-0.4.1 → docker_devkit-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docker-devkit"
-version = "0.4.1"
+version = "0.4.2"
 description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [

{docker_devkit-0.4.1 → docker_devkit-0.4.2}/src/docker_devkit/down.py

@@ -10,12 +10,12 @@ from .context_sha import compute_service_shas
 from .documents import parse_bake
 from .lifecycle import (
     enforce_bake_declaration,
+    enumerate_profiles,
     expand_compose_files,
     load_lifecycle_config,
     resolve_lock,
     resolve_manifest,
 )
-from .modes import resolve_auth_mode
 
 ENV_FILE = Path(".env")
 
@@ -44,8 +44,6 @@ def down(
     if gpu == "auto":
         gpu = detect_gpu()
 
-    resolve_auth_mode(ENV_FILE)
-
     if manifest is not None:
         os.environ.update(compute_service_shas(root, parse_bake(manifest)))
 
@@ -55,15 +53,11 @@ def down(
         raise RuntimeError("No compose files declared; a builds-only repo has no stack to tear down")
 
     files_args = " ".join(f"-f {compose_file}" for compose_file in compose_files)
-    command = (
-        "docker compose "
-        f"{files_args} "
-        f"--project-directory {root} "
-        "--profile keycloak "  # Always include so any keycloak containers from a previous AUTH_MODE=keycloak run get torn down
-        "--env-file .env "
-        f"--env-file {lock_file} "
-        "down --remove-orphans"
-    )
+    # Every profile declared across the assembly, so teardown covers containers from a prior
+    # bring-up under a different COMPOSE_PROFILES selection
+    compose_prefix = f"docker compose {files_args} --project-directory {root} --env-file .env --env-file {lock_file}"
+    profile_flags = "".join(f"--profile {profile} " for profile in enumerate_profiles(compose_prefix))
+    command = f"{compose_prefix} {profile_flags}down --remove-orphans"
 
     if volumes:
         command += " -v"

{docker_devkit-0.4.1 → docker_devkit-0.4.2}/src/docker_devkit/lifecycle.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 from pathlib import Path
 
+from bashrun.bash import bash_output
+
 from .config import LifecycleConfig, load_config
 from .detect_gpu import Gpu
 
@@ -48,3 +50,8 @@ def expand_compose_files(config: LifecycleConfig | None, gpu: Gpu, *, include_de
     if include_dev and config.dev_file is not None:
         files.append(Path(config.dev_file))
     return files
+
+
+def enumerate_profiles(compose_prefix: str) -> list[str]:
+    output = bash_output(f"{compose_prefix} config --profiles")
+    return [line.strip() for line in output.splitlines() if line.strip()]

docker_devkit-0.4.2/src/docker_devkit/modes.py

@@ -0,0 +1,24 @@
+from os import environ
+from pathlib import Path
+
+
+def resolve_compose_profiles(env_file: Path) -> list[str]:
+    file_values = parse_env_file(env_file)
+    raw_profiles = environ.get("COMPOSE_PROFILES") or file_values.get("COMPOSE_PROFILES", "")
+    profiles: list[str] = []
+    for entry in raw_profiles.split(","):
+        profile = entry.strip()
+        if profile and profile not in profiles:
+            profiles.append(profile)
+    return profiles
+
+
+def parse_env_file(path: Path) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for raw_line in path.read_text().splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        result[key.strip()] = value.strip().strip("'\"")
+    return result

{docker_devkit-0.4.1 → docker_devkit-0.4.2}/src/docker_devkit/up.py

@@ -11,13 +11,14 @@ from .context_sha import compute_service_shas
 from .documents import parse_bake
 from .lifecycle import (
     enforce_bake_declaration,
+    enumerate_profiles,
     expand_compose_files,
     load_lifecycle_config,
     resolve_lock,
     resolve_manifest,
 )
 from .mirror import enforce_mirrored, load_mirror_config
-from .modes import parse_env_file, resolve_auth_mode
+from .modes import parse_env_file, resolve_compose_profiles
 
 ENV_FILE = Path(".env")
 
@@ -66,8 +67,6 @@ def up(
     if gpu == "auto":
         gpu = detect_gpu()
 
-    auth_mode = resolve_auth_mode(ENV_FILE)
-
     mirror_config = load_mirror_config(root)
     if mirror_config is not None:
         enforce_mirrored(parse_env_file(lock_file))
@@ -83,10 +82,20 @@ def up(
         raise RuntimeError("No compose files declared; a builds-only repo has no stack to bring up")
 
     files_args = " ".join(f"-f {compose_file}" for compose_file in compose_files)
-    profile_flag = "--profile keycloak " if auth_mode == "keycloak" else ""
-    compose_args = f"{files_args} {profile_flag}--project-directory {root} --env-file .env --env-file {lock_file}"
-
-    up_command = f"docker compose {compose_args} up"
+    # compose ignores COMPOSE_PROFILES whenever a --profile flag is present, so the selection is
+    # resolved here and forwarded as explicit flags
+    compose_prefix = f"docker compose {files_args} --project-directory {root} --env-file .env --env-file {lock_file}"
+    profiles = resolve_compose_profiles(ENV_FILE)
+    if profiles:
+        defined = enumerate_profiles(compose_prefix)
+        unknown = [profile for profile in profiles if profile not in defined]
+        if unknown:
+            raise RuntimeError(
+                f"COMPOSE_PROFILES selects unknown profile(s) {unknown}; "
+                f"profiles defined by the compose files: {defined}"
+            )
+    profile_flags = "".join(f"--profile {profile} " for profile in profiles)
+    up_command = f"{compose_prefix} {profile_flags}up"
     if not build:
         # tree-<sha> tags are content-addressed and may not be pushed, so pull only what is missing locally
         up_command += " --pull missing"

docker_devkit-0.4.2/tests/test_modes.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+
+import pytest
+
+from docker_devkit.modes import resolve_compose_profiles
+
+
+class TestResolveComposeProfiles:
+    def test_reads_from_env_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.delenv("COMPOSE_PROFILES", raising=False)
+        env_file = tmp_path / ".env"
+        env_file.write_text("COMPOSE_PROFILES=tunnel-ngrok\n", encoding="utf-8")
+
+        assert resolve_compose_profiles(env_file) == ["tunnel-ngrok"]
+
+    def test_shell_environment_overrides_file(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        env_file = tmp_path / ".env"
+        env_file.write_text("COMPOSE_PROFILES=tunnel-ngrok\n", encoding="utf-8")
+        monkeypatch.setenv("COMPOSE_PROFILES", "tunnel-rathole")
+
+        assert resolve_compose_profiles(env_file) == ["tunnel-rathole"]
+
+    def test_splits_commas_strips_whitespace_and_drops_empties(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.delenv("COMPOSE_PROFILES", raising=False)
+        env_file = tmp_path / ".env"
+        env_file.write_text('COMPOSE_PROFILES=" keycloak , , tunnel-ngrok ,"\n', encoding="utf-8")
+
+        assert resolve_compose_profiles(env_file) == ["keycloak", "tunnel-ngrok"]
+
+    def test_deduplicates_preserving_first_occurrence(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.delenv("COMPOSE_PROFILES", raising=False)
+        env_file = tmp_path / ".env"
+        env_file.write_text("COMPOSE_PROFILES=keycloak,tunnel-ngrok,keycloak\n", encoding="utf-8")
+
+        assert resolve_compose_profiles(env_file) == ["keycloak", "tunnel-ngrok"]
+
+    def test_absent_yields_empty(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.delenv("COMPOSE_PROFILES", raising=False)
+        env_file = tmp_path / ".env"
+        env_file.write_text("PUBLIC_URL=https://example.dev\n", encoding="utf-8")
+
+        assert resolve_compose_profiles(env_file) == []
+
+    def test_empty_value_yields_empty(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.delenv("COMPOSE_PROFILES", raising=False)
+        env_file = tmp_path / ".env"
+        env_file.write_text("COMPOSE_PROFILES=\n", encoding="utf-8")
+
+        assert resolve_compose_profiles(env_file) == []

docker_devkit-0.4.1/src/docker_devkit/modes.py

@@ -1,39 +0,0 @@
-from os import environ
-from pathlib import Path
-from urllib.parse import urlparse
-
-VALID_AUTH_MODES = ("keycloak", "disabled")
-DEFAULT_AUTH_MODE = "keycloak"
-
-
-def resolve_auth_mode(env_file: Path) -> str:
-    file_values = parse_env_file(env_file)
-    public_url = environ.get("PUBLIC_URL") or file_values.get("PUBLIC_URL")
-    auth_mode = environ.get("AUTH_MODE") or file_values.get("AUTH_MODE", DEFAULT_AUTH_MODE)
-
-    if not public_url:
-        raise RuntimeError("PUBLIC_URL is required; set it in .env")
-    if auth_mode not in VALID_AUTH_MODES:
-        raise RuntimeError(f"AUTH_MODE={auth_mode!r} is invalid; expected one of {list(VALID_AUTH_MODES)}")
-
-    scheme = urlparse(public_url).scheme
-    if scheme not in ("http", "https"):
-        raise RuntimeError(f"PUBLIC_URL={public_url!r} must use http:// or https://")
-    if scheme == "http" and auth_mode == "keycloak":
-        raise RuntimeError(
-            f"AUTH_MODE=keycloak with PUBLIC_URL={public_url!r} is rejected: OAuth credentials must "
-            f"not flow in cleartext. Use https:// (e.g. via ngrok), or set AUTH_MODE=disabled."
-        )
-
-    return auth_mode
-
-
-def parse_env_file(path: Path) -> dict[str, str]:
-    result: dict[str, str] = {}
-    for raw_line in path.read_text().splitlines():
-        line = raw_line.strip()
-        if not line or line.startswith("#") or "=" not in line:
-            continue
-        key, _, value = line.partition("=")
-        result[key.strip()] = value.strip().strip("'\"")
-    return result