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
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.
Relative build.context, build.dockerfile, and run.mounts[].source resolve against the
component's own directory — components.container.base_path (default components/container) joined
with component:/metadata.component, the same mechanism Terraform/Helmfile/Kubernetes/Helm use —
not the directory atmos is invoked from. A component declaring source: is auto-provisioned into a
workdir (same JIT support as other component types), and that workdir becomes the anchor instead.
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.
1---2name: atmos-container3description: Atmos container components: components.container, Docker Compose migration, build/run/push/pull/up/down/list/ps/logs/exec, stack-scoped persistent containers, container workflow steps, compositions, and hooks4---56# Atmos Container Components78Use this skill for first-class Atmos containers. A container component is a stack-scoped service:9one component maps to one container, with image build/push/pull and optional persistent runtime.1011## Related Skills1213| Need | Load |14|---|---|15| Grouping services into systems | [atmos-compositions](../atmos-compositions/SKILL.md) |16| Workflow `container` steps | [atmos-workflows](../atmos-workflows/SKILL.md) |17| Lifecycle hooks around components | [atmos-hooks](../atmos-hooks/SKILL.md) |18| Local cloud/API emulators | [atmos-emulator](../atmos-emulator/SKILL.md) |19| Secret and env migration | [atmos-secrets](../atmos-secrets/SKILL.md) |2021## Component Shape2223Define containers under `components.container` in stack manifests.2425```yaml26components:27 container:28 api:29 image: ghcr.io/acme/api:latest30 build:31 context: services/api32 dockerfile: Dockerfile33 tags:34 - ghcr.io/acme/api:latest35 run:36 ports:37 - host: 808038 container: 808039 command: ./api40 env:41 LOG_LEVEL: info42 composition: app43```4445Container components can participate in hooks, compositions, workflows, and stack-specific config46the same way other Atmos component types do.4748Relative `build.context`, `build.dockerfile`, and `run.mounts[].source` resolve against the49component's own directory — `components.container.base_path` (default `components/container`) joined50with `component:`/`metadata.component`, the same mechanism Terraform/Helmfile/Kubernetes/Helm use —51not the directory `atmos` is invoked from. A component declaring `source:` is auto-provisioned into a52workdir (same JIT support as other component types), and that workdir becomes the anchor instead.5354## Commands5556| Command | Purpose |57|---|---|58| `atmos container build <name> -s <stack>` | Build the component image |59| `atmos container push <name> -s <stack>` | Push the image to its registry |60| `atmos container pull <name> -s <stack>` | Pull the image |61| `atmos container run <name> -s <stack>` | Run one foreground container |62| `atmos container up <name> -s <stack>` | Create/start the persistent container |63| `atmos container down <name> -s <stack>` | Stop and remove the persistent container |64| `atmos container ps -s <stack>` | Show running state |65| `atmos container list -s <stack>` | List container components and state |66| `atmos container logs <name> -s <stack>` | Show logs |67| `atmos container exec <name> -s <stack> -- <cmd>` | Execute inside the container |6869`atmos container` also supports `attach`, `restart`, `start`, `stop`, and `rm`. Use `--dry-run` to70preview operations.7172## Workflow Steps7374Use the workflow `container` step type when a workflow should build, run, push, or operate a75container as part of orchestration. Use `components.container` when the container is a reusable76stack-scoped component with persistent lifecycle.7778## Migrating from Docker Compose7980When replacing `docker compose` with Atmos containers, translate one Compose service at a time81into `components.container.<service>`. Keep multi-service grouping with `composition`, not by82collapsing several services into one container component.8384| Docker Compose field | Atmos container mapping |85|---|---|86| `services.<name>.image` | `components.container.<name>.image` |87| `build.context`, `build.dockerfile` | `build.context`, `build.dockerfile` |88| `ports` | `run.ports` |89| `environment`, `env_file` | `env`, stack `vars`, or `secrets.vars` with `!secret` |90| `command`, `entrypoint` | `run.command` or the supported runtime command fields |91| `volumes` | runtime mount settings supported by the container component |92| `depends_on` | workflow/composition ordering, readiness checks, `wait`, or `wait-all` |93| Compose project name | shared `composition: <name>` across related container components |9495Migration process:96971. Inventory Compose services and split long-lived services into separate container components.982. Move shared `.env` values into stack vars, component env, declared secrets, or `!secret`99 references.1003. Use `composition: <name>` so former Compose services validate and run as one system.1014. Replace `docker compose up/down/logs/exec/ps` with the matching `atmos container` commands.1025. Use workflow `container`, `wait`, `wait-all`, and explicit dependencies for startup order103 instead of Compose-only `depends_on` assumptions.1046. Prefer first-class `components.container` for Atmos-managed services. Keep a native Compose105 file only when the project must remain compatible with external Compose tooling.106107## Operational Guidance108109- Use stack names to isolate container instances.110- Prefer declared `image`, `build`, `run`, and `env` blocks over ad hoc shell `docker` commands.111- Use `composition` when a container fulfills a named service in a system.112- Use hooks for pre/post actions such as scans, artifact publication, or store writes.113- Use registry auth skills such as `atmos-aws-ecr` when pushing to private registries.
cloudposse