Skip to main content

Using Containers

Atmos natively supports container components — stack-scoped, persistent containers. One component is one service. Atmos owns the image artifact (build/push/pull) and an optional long-running named container lifecycle (up/ps/logs/exec/restart/stop/rm/down), discovered by labels derived from the canonical component instance address — not from local state files.

For the complete command reference, see the atmos container documentation.

This is different from the ephemeral type: container workflow step, which is docker run --rm and workflow-scoped. The component is declarative, addressable infrastructure; the step is procedural sequencing.

Stack Configuration​

Container component config uses first-class sections (image, build, run) — consistent with the container workflow step, NOT nested under vars:

components:
  container:
    api:
      composition: storefront            # composition membership (optional)
      image: localhost:5001/api:latest
      build:                             # build the image
        context: app
        dockerfile: Dockerfile
        tags:
          - localhost:5001/api:latest
      run:                               # run configuration
        command: ./api
        ports:
          - host: 8080
            container: 80
        mounts:
          - source: .
            target: /workspace
      env:                               # component env (resolved with secrets)
        PORT: "8080"

Inheritance (metadata.inherits), catalogs, mixins, and deep-merge work exactly like other component kinds — define abstract base components with shared run/build defaults and inherit them.

Lifecycle​

atmos container build api -s dev      # build the image from `build`
atmos container up api -s dev         # create/start the long-running container (build-on-missing)
atmos container list                  # all container components + running state
atmos container ps api -s dev         # show running state
atmos container logs api -s dev       # stream logs
atmos container exec api -s dev -- sh # run a command inside the container
atmos container down api -s dev       # stop + rm

Each instance is named and labeled from its canonical address <stack>/container/<component> (e.g., atmos-dev-container-api), so lifecycle commands discover it by label — there are no local state files.

atmos container list shows a running/stopped/unknown indicator for each container component.

Compositions​

A composition groups components into a system. Declare membership with the composition field; the top-level compositions section declares the closed set of services:

compositions:
  storefront:
    description: Storefront system
    services: [api, worker, database]

Run atmos composition validate storefront -s dev to see which services are fulfilled vs. not provided in a stack.