Deploy a Docker Compose Project¶

Prerequisite: Docker Compose is installed on the target device.

This guide walks through deploying a Docker Compose project on a device using the qbee-agent Compose integration. You will upload a compose file, commit it as desired state, and let the agent converge the device to match. The example uses a single PostgreSQL service, but the same steps apply to any Compose project.

Step 1 — Open the Docker Compose configuration¶

In the Qbee console, select your device, group, or tag from the Devices page, then click the Configure tab. In the configuration menu on the left, select Docker compose.

Expected outcome: The Docker Compose configuration form loads. If no projects have been defined on this level, the form is empty.

Step 2 — Add a project and name it¶

Click + to add a project. Enter a project name, for example postgres-project. The project name is the identifier Docker Compose uses to namespace the project's containers, networks, and volumes on the device.

Expected outcome: The new project appears in the form, ready for a compose file.

Step 3 — Upload the compose file¶

Upload a Docker Compose YAML file. For this example:

services:
  postgres:
    image: postgres:16
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: yourpassword

The compose file follows the standard Docker Compose format. If you need to parameterize values at converge time, upload a templated file and supply template parameters instead of hardcoding them (see secrets and parameters).

Expected outcome: The compose file is attached to the project and shown in the configuration.

Pinning image tags

Avoid using latest in production. Pin to a specific version (for example, postgres:16) so that the same desired state produces the same result on every device, every poll.

Step 4 — Save and commit¶

Click Save settings at the bottom of the form to stage the configuration. The Commit changes button in the top right turns red to indicate uncommitted changes. Click it, optionally enter a commit message, and click Commit.

Expected outcome: A notification confirms the commit was successful. The agent will pick up the new desired state on its next poll.

Yellow dot in the menu

A yellow dot next to the bundle name in the left-side menu means there are uncommitted changes. The Commit changes button turns red when changes are staged but not committed.

Step 5 — Verify the project is running¶

Within one polling cycle the agent pulls the images and starts the project. To verify, open the device in the console and check the device inventory tab. The containers from the compose project should appear in the list with a status of running.

Alternatively, open a remote console on the device and run:

docker compose ls

Expected outcome: The postgres-project project appears in the output.

Project not running?

If the containers do not appear, verify that Docker Compose is installed on the device with docker compose version. If the agent failed to apply the project, verify that the compose file is valid by running docker compose -f <file> config on the device, and check the audit log to confirm the agent has converged since the commit.

Done¶

You have deployed a Docker Compose project using desired-state configuration. The agent will continue to enforce this state on every convergence cycle: if containers stop or are removed, the agent recreates them.

What Next?¶

I want to...	Go to
Deploy a single container instead	Deploy a Docker Container
Use Podman	Podman
Walk through a more detailed example	Docker Compose tutorial
Build a CI/CD pipeline for containers	CI/CD with Docker
Use clean, pre-conditions, or skip-restart	FAQ