https://github.com/stephenlclarke/container-compose
Docker Compose plugin for Apple's container CLI with Homebrew tap.
https://github.com/stephenlclarke/container-compose
apple-container compose compose-go containers docker-compose swift
Last synced: about 23 hours ago
JSON representation
Docker Compose plugin for Apple's container CLI with Homebrew tap.
- Host: GitHub
- URL: https://github.com/stephenlclarke/container-compose
- Owner: stephenlclarke
- License: apache-2.0
- Created: 2026-06-15T21:32:17.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-07-01T10:25:34.000Z (4 days ago)
- Last Synced: 2026-07-01T10:25:56.935Z (4 days ago)
- Topics: apple-container, compose, compose-go, containers, docker-compose, swift
- Language: Swift
- Homepage:
- Size: 3.52 MB
- Stars: 9
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
Awesome Lists containing this project
README
# container-compose
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://sonarcloud.io/summary/new_code?id=stephenlclarke_container-compose2)
[](https://github.com/stephenlclarke/container-compose/actions/workflows/codeql.yml?query=branch%3Amain)
`container-compose` is a standalone plugin that provides Docker Compose style
workflows for Apple's [`container`](https://github.com/apple/container) CLI
where the supported Compose surface maps to available runtime primitives.
The first implementation target is local-development Compose v2 compatibility
where [`container`](https://github.com/apple/container) has matching runtime
primitives. Compose file normalization uses `compose-go`, with Swift handling
runtime orchestration.
The CLI accepts the Docker Compose 5.2.0 command and option surface, including
help output. Help color-codes command, subcommand, and option support status:
green for supported, orange for partially supported, and red for not supported;
use `--ansi never` for plain output. Commands or option modes that do not yet
have backing `apple/container` functionality fail with an explicit
`unsupported compose feature` message.
The top-level help output is the quickest support overview. Run
`container compose COMMAND --help` for command-specific option support.
Current detailed gap examples:
- Supported `build` coverage includes Compose build args, additional contexts,
file/env build secrets with Docker-compatible ignored ownership metadata,
SSH forwarding, cache hints, labels, target stages, platforms, pull/no-cache,
builder selection, checks, provenance/SBOM attestations, extra hosts, build
network mode, Buildx-compatible isolation acceptance, privileged builds,
shared memory size, ulimits, `--print`, and service-context build ordering.
- Supported `up` coverage includes attach selection, dependency attachment,
exit-control flags, raw output flags, timestamps, watch mode, and the
attached terminal `--menu` shortcut surface. The menu path supports detach,
watch toggle, command-level `--watch` start, graceful stop, force stop
shortcuts, and exit-control flags; Docker Desktop-only shortcuts are
intentionally absent.
- Supported service mount coverage includes named volumes, bind mounts,
anonymous volumes, tmpfs mounts, long-form tmpfs options, `volumes_from`,
Docker-compatible bind `create_host_path` handling, and long-form
`volume.labels` preservation. Bind `propagation` values are preserved as
runtime mount options. Anonymous `volume.labels` are applied to the created
runtime volume; named service mount labels remain config metadata, matching
Docker Compose.
- Supported namespace-mode coverage includes `network_mode: none` and
`pid: host`. `network_mode: host` maps to the Stephen fork-backed
`container --network host` runtime path while avoiding Compose project network
attachment. Service/container namespace-sharing forms remain explicit runtime
gaps.
- Supported network-resource coverage includes top-level network `driver_opts`,
which are preserved in config output and passed to Apple network creation as
plugin-specific `--option key=value` values. Service network attachment
`driver_opts` support is currently limited to Docker-compatible MTU values
because Apple attachment options expose MTU but not arbitrary endpoint driver
options.
- Supported device coverage includes service `device_cgroup_rules`, which maps
to the fork-backed `container run/create --device-cgroup-rule` runtime path,
and service `devices`, which maps Docker Compose device entries to
fork-backed `container run/create --device` arguments for supported Linux VM
device paths such as `/dev/null` and `/dev/zero`. Device source paths and
explicit target paths must be absolute. GPU requests and arbitrary macOS
hardware passthrough remain explicit runtime gaps.
- Supported local Deploy metadata includes replicas, local job modes,
stop-first update delays, restart policy fields, CPU/memory reservation
hints, and Swarm `endpoint_mode` acceptance as Docker-compatible local
metadata.
- Partially supported commands: `attach` and `up`.
- Unsupported commands: `commit` and `publish`.
Long-running project loading, image pull/build, and non-interactive runtime
handoff steps emit Compose-owned progress on stderr so scriptable stdout output
stays clean. Use `--progress quiet` to suppress these rows, `--progress plain`
for log-friendly rows, or `--progress tty` for the animated terminal spinner.
`--progress json` emits newline-delimited JSON events for Compose-owned phases.
`--progress auto` uses the animated spinner when stderr is a terminal and plain
rows otherwise.
Use `container system version` to see the running `container` runtime source, branch lane, commit, compiled `containerization` ref, and pinned `container-builder-shim` image. Use `container compose version` to see the installed plugin lane, embedded `compose-go` version, and the `container` / `containerization` pins that package was built against.
## Project Repositories
The supported preview install is a matched Stephen fork-backed stack:
- [`container-compose`](https://github.com/stephenlclarke/container-compose): this plugin and its Swift/Go packaging workflow.
- [`container`](https://github.com/stephenlclarke/container): the fork-backed runtime and CLI installed beside the plugin.
- [`containerization`](https://github.com/stephenlclarke/containerization): the Swift runtime package pinned by the stack.
- [`container-builder-shim`](https://github.com/stephenlclarke/container-builder-shim): the BuildKit bridge image pinned by `container`.
Install and upgrade commands live in [INSTALL.md](INSTALL.md). Branch, tag, release-helper, and Homebrew lane policy lives in [BRANCHES.md](BRANCHES.md).
## Plugin Recognition
When installed correctly, `container help` lists `compose` under `PLUGINS`.
## Documentation
- [INSTALL.md](INSTALL.md): install, upgrade, verify, uninstall, recover bad installs, and diagnose runtime issues.
- [BRANCHES.md](BRANCHES.md): understand `main`, short-lived development branches, semantic tags, `CONTAINER_STACK_RELEASE.sh`, release assets, and Homebrew lane policy.
- [BUILD.md](BUILD.md): build, test, package, and run contributor validation from source.
- [DESIGN.md](DESIGN.md): understand the Swift/Go boundary and runtime adapter ownership.
- [STATUS.md](STATUS.md): get the current dependency pins, blockers, active gaps, and validation handoff.
- [CONTRIBUTING.md](CONTRIBUTING.md): prepare reviewable changes.
- [docs/parity/compose-cli-surface.md](docs/parity/compose-cli-surface.md): review local Docker Compose CLI surface parity and documented differences.
- [SUPPORT.md](SUPPORT.md): ask for help or report non-security issues.
- [SECURITY.md](SECURITY.md): report security issues.
## License
This project uses the Apache License, Version 2.0, matching the license used by
[`apple/container`](https://github.com/apple/container).