### Install compose2pod

Source: https://github.com/modern-python/compose2pod/blob/main/README.md

Install the core package or the version with YAML support.

```bash
pip install compose2pod            # core: reads compose as JSON
pip install compose2pod[yaml]      # optional: read YAML directly (adds PyYAML)
```

--------------------------------

### Example of malformed extra_hosts configuration

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-14.06-extra-hosts-equals-separator.md

An example of the configuration format that previously resulted in silent corruption due to incorrect separator handling.

```yaml
extra_hosts:
  - "somehost=162.242.195.82"     # Compose's own documented form
```

--------------------------------

### Example service configuration with hostname

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-08.01-service-hostname.md

A sample YAML configuration showing the use of the hostname key within a service definition.

```yaml
keydb:
  image: .../keydb-for-ci:x86_64_v6.3.0
  hostname: keydb-test-server-0
  restart: always
```

--------------------------------

### Podman Pod Creation Command

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-11.03-pod-dns-sysctls.md

Example command demonstrating how pod-level DNS and sysctl flags are rendered onto the podman create line.

```bash
podman pod create --name test-pod --dns "1.1.1.1" --dns "8.8.8.8" \
  --dns-search "corp.internal" --sysctl "net.core.somaxconn=1024"
```

--------------------------------

### Conflicting Host Configuration Example

Source: https://github.com/modern-python/compose2pod/blob/main/planning/audits/2026-07-13-docs-and-gate-audit.md

Demonstrates a scenario where a service not in the dependency closure causes an UnsupportedComposeError due to host conflict.

```yaml
services:
  app:   {image: i, extra_hosts: ["db:1.2.3.4"]}
  other: {image: i, hostname: db}          # not in app's closure; never started
```

--------------------------------

### Informational CLI Note

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-08.07-runtime-variable-interpolation.md

Example of the informational stderr message displayed when variables are referenced at runtime.

```text
compose2pod: note: script references variables at run time: API_KEY, DATABASE_URL
```

--------------------------------

### Define environment variables in Compose

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-08.07-runtime-variable-interpolation.md

Example of a service configuration using a variable reference that requires runtime resolution.

```yaml
services:
  app:
    environment:
      API_KEY: ${API_KEY}
```

--------------------------------

### Example of rejected YAML key

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-14.09-yaml-12-booleans.md

Shows how PyYAML's boolean resolution causes a valid Docker Compose file to be rejected when 'on' is used as a key.

```yaml
environment:
  on: 1                    # docker compose: renders `on: 1`, runs fine
```

```text
compose2pod: error: ... key True must be a string
```

--------------------------------

### Example Compose File with Named Volumes

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-08.04-named-volumes.md

A standard Compose file structure using a named volume for database persistence, which previously caused errors in compose2pod.

```yaml
services:
  db:
    volumes:
      - calutrondb:/var/lib/postgresql/data
volumes:
  calutrondb:
    driver: local
```

--------------------------------

### Example of Compose extension fields with YAML anchors

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-04.01-extension-fields.md

A standard Compose file structure utilizing an x- prefixed extension field to define reusable configuration via YAML anchors.

```yaml
x-application-defaults: &application-defaults
  build:
    context: .
    dockerfile: ./Dockerfile
services:
  application:
    <<: *application-defaults
    ...
```

--------------------------------

### Validate ulimits input

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-14.05-extends-merge-policy.md

Example of the gate rejecting a list-based ulimits input.

```python
$ validate({"app": {"ulimits": ["nofile=2"]}})     -> 'ulimits' must be a mapping
```

--------------------------------

### Postgres Initialization Log Output

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-14.04-healthy-gating-flake.md

Log sequence showing the temporary server listening on a Unix socket before the actual TCP listener is established.

```text
[36] listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"   <- temp server, socket ONLY
[36] database system is ready to accept connections                  <- `pg_isready -U postgres` returns 0 HERE
[37] shutting down                                                   <- temp server stops
     PostgreSQL init process complete; ready for start up.
[1]  listening on IPv4 address "0.0.0.0", port 5432                  <- TCP only appears NOW
[1]  database system is ready to accept connections                  <- for real
```

--------------------------------

### Define environment variable interpolation in Compose

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-08.06-variable-interpolation.md

Example of using Compose-spec syntax for environment variable injection.

```yaml
services:
  app:
    environment:
      LLM_MODEL: ${LLM_MODEL}
```

--------------------------------

### Example of silent boolean corruption

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-14.09-yaml-12-booleans.md

Demonstrates how PyYAML incorrectly resolves 'on' and 'yes' as booleans instead of strings.

```yaml
environment:
  SSL: on
  DEBUG: yes
```

```text
podman run ... -e "SSL=true" -e "DEBUG=true"      # docker: -e SSL=on -e DEBUG=yes
```

--------------------------------

### Verify pod-level options in integration test

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-13.02-grow-integration-scenarios.md

Checks DNS, sysctl, and extra host configurations by inspecting system files within the container.

```bash
grep 9.9.9.9 /etc/resolv.conf && grep 1024 /proc/sys/net/core/somaxconn && grep external-svc:10.0.0.9 /etc/hosts
```

--------------------------------

### Initialize StoreKind Instances

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-10.03-configs.md

Specific configurations for secrets and configs using the StoreKind dataclass.

```python
# secrets.py — prefix="" preserves the exact current store names
SECRET = StoreKind(
    label="secret",
    top_key="secrets",
    prefix="",
    sources=frozenset({"file", "environment"}),
    default_target=lambda n: n,
    require_absolute_target=False,
)
# configs.py
CONFIG = StoreKind(
    label="config",
    top_key="configs",
    prefix="config-",
    sources=frozenset({"file", "environment", "content"}),
    default_target=lambda n: f"/{n}",
    require_absolute_target=True,
)
```

--------------------------------

### CLI Usage Syntax

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-03.01-compose2pod-extraction.md

Standard command-line interface syntax for executing compose2pod.

```bash
compose2pod --target NAME --image IMG [FILE]
            [--project-dir DIR] [--command CMD] [--pod-name NAME]
            [--artifact SRC:DST]... [--allow-exit-code N]...
            [--format auto|json|yaml]
```

--------------------------------

### Derive Consumers from Registry

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-09.08-service-key-registry.md

Demonstrates how validation and emission logic iterate over the SERVICE_KEYS registry instead of using hardcoded lists.

```python
for key, spec in SERVICE_KEYS.items():
    if key in svc:
        flags += spec.emit(svc[key])  # emit;  or  spec.validate(name, key, svc[key])
```

--------------------------------

### Generated Podman Secret Lifecycle Script

Source: https://github.com/modern-python/compose2pod/blob/main/planning/changes/2026-07-10.02-secrets.md

Example of the generated shell script commands for creating, mounting, and cleaning up pod-namespaced secrets.

```sh
trap 'podman pod rm -f test-pod ... ; podman secret rm test-pod-db_password test-pod-api_key >/dev/null 2>&1 || true' EXIT
podman pod create --name test-pod
podman secret create test-pod-db_password "/builds/proj/db_pw.txt"
printf '%s' "${API_KEY-}" | podman secret create test-pod-api_key -
...
podman run -d ... --secret source=test-pod-db_password,target=db_password ...
```