Deploy your first stack

This walkthrough deploys a one-service Nginx stack and shows where it lands on disk.

Deploying from the web UI: the Compose file goes in the editor, the variables it references go in the table below, and both are saved together as version 1.

1. Write the Compose file

services:
  web:
    image: docker.io/library/nginx:latest
    ports:
      - "8081:80"
    restart: unless-stopped

Tip

Use fully qualified image names (docker.io/library/nginx) if your host runs Podman, whose default registry resolution differs from Docker’s.

2. Deploy it

From the web UI

1. Click + STACK.
2. Name it my-web-server.
3. Paste the Compose file into the Monaco editor.
4. Click Deploy.

From the TUI

On the Stacks tab, press n, type my-web-server and Enter. Your editor ($VISUAL, $EDITOR, fallback vi) opens with a template: replace it, save and quit. The environment table opens next; press w to deploy.

Leaving the template unchanged cancels the creation.

From the CLI

kaio-cli stack deploy my-web-server ./compose.yml

3. Check it

kaio-cli stack ls
kaio-cli stack logs my-web-server --follow

The stack row shows an aggregated state (RUNNING, EXITED, PARTIAL or PAUSED), plus the CPU, RAM and network I/O of all its containers summed.

Nginx answers on http://localhost:8081.

4. Use it on that stack

A running stack gives you the rest of the tool:

kaio-cli stack logs my-web-server --follow
kaio-cli stack scan my-web-server
kaio-cli container ls
kaio-cli container shell <id>

stack logs merges every container of the stack into one stream, each line prefixed by its service. stack scan runs Trivy and the findings land on the image, container and stack rows you already read. container shell drops you inside the container, Ctrl-] to detach.

The same three are a click away in the web UI, and l, v and ! in the TUI.

Where the files live

data/
└── stacks/
    └── my-web-server/
        ├── compose.yml
        └── .env

The directory is derived from the database path, or set explicitly with KAIO_STACKS_DIR. Compose runs in that directory, which is why the project name, and therefore container names like my-web-server-web-1 and the my-web-server_default network, match the stack name.

Next steps

• Add environment variables to the stack
• Understand versions and rollback
• Scan the image for vulnerabilities