container

A Docker / Podman container as a service. Useful when:

  • the upstream you want isn't in our blessed catalog,
  • a blessed version doesn't expose a config knob you need,
  • you're matching production exactly.

Manifest knobs

[services.broker]
type = "container"
image = "redpandadata/redpanda:v25.1.6"
command = ["redpanda", "start", "--smp", "1"]
ports = ["9092"]
env = { REDPANDA_MODE = "dev-container" }
volumes = ["./data:/var/lib/redpanda"]

The orchestrator drives the container via the host's container CLI (docker or podman — whichever is on PATH). It doesn't bundle one; the user installs Docker Desktop / OrbStack / Podman separately.

Lifecycle

  • Pulls the image lazily on first start (idempotent).
  • Spawns the container under a deterministic name (unibench-<project-slug>-<service>) so the orchestrator can find it again across daemon restarts.
  • Healthcheck defaults to docker exec on a configured command, or TCP on a port if specified.
  • Stops with docker stop (10s grace) on unibench stop.

Common gotchas

  • No Docker on PATH. The healthcheck fails before reaching the container itself; the known-issues catalog covers this signature.
  • Volume paths. Relative paths are anchored at the project root. Use absolute paths to mount things outside the project.
  • Port collisions. Static ports = ["9092"] will collide if another project uses the same port. Switch to ports = ["auto:9092"] to let the orchestrator allocate the host-side port and inject it as $<NAME>_PORT for dependents.

Escape hatch

If you need a full multi-container topology, drop down to compose instead.