container-compose

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

container-compose

★ 50 Open GitHub ↗

Implementation of Docker Compose for Apple containers - fork of https://github.com/Mcrich23/Container-Compose

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Container-Compose

Originally forked from [Mcrich23/Container-Compose](https://github.com/Mcrich23/Container-Compose), but has diverged.

Container-Compose brings (limited) Docker Compose support to [Apple Container](https://github.com/apple/container), allowing you to define and orchestrate multi-container applications on Apple platforms using familiar Compose files. This project is not a Docker or Docker Compose wrapper but a tool to bridge Compose workflows with Apple's container management ecosystem.

### Coverage Report

[Compose feature coverage report](https://full-chaos.github.io/container-compose/)

## Documentation

Full documentation lives in [`docs/`](./docs/):

- [**Quickstart**](./docs/quickstart.md) — up and running in 2 minutes
- [**CLI Reference**](./docs/cli-reference.md) — every subcommand and flag
- [**Tutorials**](./docs/tutorials/) — paired walkthroughs for the working samples in [`Sample Compose Files/`](./Sample%20Compose%20Files/)
- [**Feature Parity**](./docs/feature-parity.md) — tiered split of compose-spec coverage gaps
- [**Upstream / Fork Status**](./docs/upstream-fork-status.md) — what we depend on from `full-chaos/container` and what's pending in `apple/container`

## Features

- **Compose file support:** Parse and interpret `docker-compose.yml` files to configure Apple Containers.
- **Apple Container orchestration:** Launch and manage multiple containerized services using Apple’s native container runtime.
- **Environment configuration:** Support for environment variable files (`.env`) to customize deployments.
- **Service dependencies:** Specify service dependencies and startup order.
- **Volume and network mapping:** Map data and networking as specified in Compose files to Apple Container equivalents.
- **Extensible:** Designed for future extension and customization.

## Known Limitations

Container-Compose translates compose-spec to `apple/container`. Some Docker-specific features have no Apple equivalent yet.

Most common pitfalls:

- **Docker socket mounts** (Traefik / Watchtower / Portainer) do not work — there is no Docker daemon on the host.
- **macOS 15 (Sequoia)** requires manual DNS setup; macOS 26 (Tahoe) is recommended.
- **Many resource limits** (`shm_size`, `pids_limit`, `oom_*`, `cpuset`, `blkio_*`, etc.) are warn-skipped — only `cpus` and `memory` apply.

See [Limitations and Gotchas](./docs/guides/limitations-and-gotchas.md) for the full list.
## Getting Started

### Prerequisites

- A Mac running macOS with Apple Container support (macOS Sonoma or later recommended)
- Git
- [Xcode command line tools](https://developer.apple.com/xcode/resources/) (for building, if building from source)

Build it from source:

1. **Clone the repository:**

```sh
   git clone https://github.com/full-chaos/container-compose.git
   cd container-compose
   ```

2. **Build the executable:**

> *Note: Ensure you have Swift installed (or the required toolchain).*

```sh
   make build
   ```

3. **(Optional)**: Install globally

```sh
   make install
   ```

### Source build with extended features (opt-in)

The default `Package.swift` pin (`full-chaos/container#tier2-fork-patches`) carries
the runtime surface needed for production use. Source-build users who want
**fork-forward features** still pending in `apple/container` upstream can swap the
pin to the active development branch:

```swift
.package(url: "https://github.com/full-chaos/container", branch: "dev"),
```

What `dev` adds: richer network IPAM (CHAOS-1334), rebased onto newer
`apple/containerization`, plus the same fork-only feature set. Not distributed via
Homebrew — source build only. Branch:
<https://github.com/full-chaos/container/tree/dev>. See
[Upstream / Fork Status](./docs/upstream-fork-status.md#51-opt-in-full-chaoscontainerdev-for-fork-forward-features)
for the complete tradeoff matrix.

### Usage

After installation, simply run:

```sh
container-compose up
```

You may need to provide a path to your `docker-compose.yml` and `.env` file as arguments.

## Native API server (optional)

The HTTP daemon exposes a Container REST API over a Unix domain socket at `~/.container-compose/api.sock`. It is optional — Container-Compose's CLI commands (`up`, `down`, `ps`, etc.) work without the daemon. The daemon is only needed for ecosystem tooling that wants to talk to Container-Compose over HTTP (e.g., reverse proxies, observability collectors, dashboards). The daemon runs in the foreground by default; users wanting background services can use `&`, `nohup`, or `tmux`.

### Starting the daemon

```sh
container-compose serve
```

Press Ctrl-C or send SIGTERM (`kill -TERM <pid>`) to gracefully shut down.

To bind to a non-default socket path:

```sh
container-compose serve --socket /tmp/container-compose.sock
```

### Checking daemon status

Use `system status` to verify the daemon is reachable:

```sh
container-compose system status
```

Exit code 0 means the daemon is running and responsive; exit code 1 means it is not. This makes status suitable for shell scripts:

```sh
if container-compose system status >/dev/null; then
    echo "daemon is up"
fi
```

### Verifying the API

The daemon's `/_ping` endpoint confirms the HTTP layer is responsive:

```sh
curl --unix-socket "$HOME/.container-compose/api.sock" http://localhost/_ping
```

```
{"ok":true,"server":"container-compose","version":"0.11.0"}
```

### Idempotence

Running `container-compose serve` a second time while the daemon is already up detects the existing socket, prints a friendly message, and exits cleanly with status 0 — safe to invoke from setup scripts.

For architectural rationale, see [`docs/plans/native-api-server.md`](docs/plans/native-api-server.md).

## Contributing

Contributions are welcome! Please open issues or submit pull requests to help improve this project.

1. Fork the repository.
2. Create your feature branch (`git checkout -b feat/YourFeature`).
3. Commit your changes (`git commit -am 'Add new feature'`).
4. Add tests to you changes.
5. Push to the branch (`git push origin feature/YourFeature`).
6. Open a pull request.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Support

If you encounter issues or have questions, please open an [Issue](https://github.com/full-chaos/container-compose/issues).

---

Happy Coding! 🚀

container-compose

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README