Atmos Container Components

Use this skill for first-class Atmos containers. A container component is a stack-scoped service: one component maps to one container, with image build/push/pull and optional persistent runtime.

Related Skills

Need	Load
Grouping services into systems	atmos-compositions
Workflow `container` steps	atmos-workflows
Lifecycle hooks around components	atmos-hooks
Local cloud/API emulators	atmos-emulator
Secret and env migration	atmos-secrets

Component Shape

Define containers under components.container in stack manifests.

components:
  container:
    api:
      image: ghcr.io/acme/api:latest
      build:
        context: services/api
        dockerfile: Dockerfile
        tags:
          - ghcr.io/acme/api:latest
      run:
        ports:
          - host: 8080
            container: 8080
        command: ./api
      env:
        LOG_LEVEL: info
      composition: app

Container components can participate in hooks, compositions, workflows, and stack-specific config the same way other Atmos component types do.

Commands

Command	Purpose
`atmos container build <name> -s <stack>`	Build the component image
`atmos container push <name> -s <stack>`	Push the image to its registry
`atmos container pull <name> -s <stack>`	Pull the image
`atmos container run <name> -s <stack>`	Run one foreground container
`atmos container up <name> -s <stack>`	Create/start the persistent container
`atmos container down <name> -s <stack>`	Stop and remove the persistent container
`atmos container ps -s <stack>`	Show running state
`atmos container list -s <stack>`	List container components and state
`atmos container logs <name> -s <stack>`	Show logs
`atmos container exec <name> -s <stack> -- <cmd>`	Execute inside the container

atmos container also supports attach, restart, start, stop, and rm. Use --dry-run to preview operations.

Workflow Steps

Use the workflow container step type when a workflow should build, run, push, or operate a container as part of orchestration. Use components.container when the container is a reusable stack-scoped component with persistent lifecycle.

Migrating from Docker Compose

When replacing docker compose with Atmos containers, translate one Compose service at a time into components.container.<service>. Keep multi-service grouping with composition, not by collapsing several services into one container component.

Docker Compose field	Atmos container mapping
`services.<name>.image`	`components.container.<name>.image`
`build.context`, `build.dockerfile`	`build.context`, `build.dockerfile`
`ports`	`run.ports`
`environment`, `env_file`	`env`, stack `vars`, or `secrets.vars` with `!secret`
`command`, `entrypoint`	`run.command` or the supported runtime command fields
`volumes`	runtime mount settings supported by the container component
`depends_on`	workflow/composition ordering, readiness checks, `wait`, or `wait-all`
Compose project name	shared `composition: <name>` across related container components

Migration process:

Inventory Compose services and split long-lived services into separate container components.
Move shared .env values into stack vars, component env, declared secrets, or !secret references.
Use composition: <name> so former Compose services validate and run as one system.
Replace docker compose up/down/logs/exec/ps with the matching atmos container commands.
Use workflow container, wait, wait-all, and explicit dependencies for startup order instead of Compose-only depends_on assumptions.
Prefer first-class components.container for Atmos-managed services. Keep a native Compose file only when the project must remain compatible with external Compose tooling.

Operational Guidance

Use stack names to isolate container instances.
Prefer declared image, build, run, and env blocks over ad hoc shell docker commands.
Use composition when a container fulfills a named service in a system.
Use hooks for pre/post actions such as scans, artifact publication, or store writes.
Use registry auth skills such as atmos-aws-ecr when pushing to private registries.

SKILL.md