# Stacks

Apple's `container` CLI runs one container at a time. There is no docker-compose equivalent — no way
to declare "a database, then an app that waits for it, wired together." Managing a multi-container app
means dozens of manual commands and hand-copied IP addresses.

**Stacks** are Runbay's answer: compose-style orchestration built for Apple's runtime.

## What a Stack does

- **Dependency ordering** — start the database before the app that needs it.
- **Health-check gating** — wait until PostgreSQL is actually ready before starting the web tier,
  not just until its container exists.
- **Auto-injected direct IPs** — each container's dedicated IP is resolved and injected into
  dependents (for example, a `DATABASE_URL` pointed at `192.168.64.5:5432`), so there's no localhost
  confusion and no manual copy-paste.

The whole system is verified end-to-end against the live daemon — `Runbay --selftest-stack`
runs a 13-step deploy-and-teardown every time, so orchestration isn't just theoretical.

## Built-in templates

Eight templates ship in the app, ready to deploy from the Stacks browser:

| Template         | Stack                                             |
|------------------|---------------------------------------------------|
| `postgresql-dev` | PostgreSQL, tuned for local development           |
| `lemp`           | Linux + Nginx + MySQL/MariaDB + PHP               |
| `mern`           | MongoDB + Express + (React) + Node                |
| `django`         | Django + PostgreSQL                               |
| `rails`          | Rails + PostgreSQL                                |
| `wordpress`      | WordPress + MySQL                                 |
| `monitoring`     | A monitoring stack                                |
| `ai-ollama`      | Local AI with Ollama                              |

Open the **Stacks** item in the sidebar, pick a template, review the containers it will create, and
deploy. The direct IPs are wired for you.

## Importing a docker-compose file

Already have a `compose.yml`? Open or drag it into Runbay. The importer parses it with a
hand-rolled YAML reader (zero dependencies) and shows you a review sheet **before** anything deploys.

The rule is: **nothing is silently dropped.** Every key that doesn't map cleanly onto Apple's runtime
surfaces as an explicit warning you read and accept. Compose features Apple's framework doesn't have
become visible decisions, not quiet omissions. Once you accept, the compose file deploys as a Stack
and behaves like any other — dependency ordering, health gating, injected IPs.

Migrating from Docker or OrbStack? Compose projects are bridged straight into this importer — see the
[migration guide](migration.md).

## Notes and honest limits

- **macOS 15:** direct-IP injection between containers depends on container-to-container networking,
  which Apple only supports on macOS 26. On macOS 15 the app is honest about the degraded story.
- Prefer **arm64 images** in your stacks; `linux/amd64` emulation can segfault JIT-heavy workloads.

Next: wire your stack's containers into a coding agent with the [agent setup guide](agent-setup.md),
or keep them alive across crashes with the [supervisor](supervisor.md).