Deploy a Docker Container¶

Prerequisite: Docker is installed on the target device. The agent uses whatever Docker version is present on the system.

This guide walks through deploying a Docker container on a device using desired-state configuration. You will define a container as part of the desired state, commit it, and let the agent converge the device to match. The example uses a PostgreSQL image, but the same steps apply to any Docker image.

Step 1 — Open the Docker 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.

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

Step 2 — Add a container definition¶

Click + to add a container and enter the basic definition:

Field	Value
Name	`postgres`
Image	`postgres:16.14`
Arguments	`-p 5432:5432 -e POSTGRES_PASSWORD=$(POSTGRES_PASSWORD)`

The Name is an arbitrary label used to identify the container in the configuration and inventory. The Image is the image reference Docker will pull, including a tag if you want to pin a specific version. The Arguments are passed to the Docker command line when starting the container; here they publish the Postgres port and pass the password environment variable. The $(POSTGRES_PASSWORD) placeholder is replaced at converge time with the secret value defined in the next step.

Click Save settings at the bottom of the form.

Expected outcome: The container definition appears in the form with the fields you entered.

Pinning image tags

Avoid using latest or major-version-only tags such as postgres:16 in production — these are reassigned on every new release and can cause fleet devices to run different versions over time. Use a fully-pinned tag (for example, postgres:16.14) so that the same desired state produces exactly the same result on every device, every poll.

Step 3 — Define the secret¶

The Postgres image requires POSTGRES_PASSWORD to initialize the database. Hardcoding the password in the configuration exposes it to anyone who can read the configuration. Instead, define it as a secret and reference it from the container arguments.

Navigate to Configure and select the same level (or a parent) as the container definition.
Open the Parameters bundle.
Under Secrets, add POSTGRES_PASSWORD as the key and your desired password as the value.
Click Save settings.

At converge time, the agent substitutes the secret value into the $(POSTGRES_PASSWORD) placeholder in the Arguments field before starting the container. The secret value never appears in the configuration or in the device logs.

Expected outcome: The secret appears in the parameters list. Its value is redacted and cannot be retrieved later.

Step 4 — Commit¶

Click Commit changes in the top right, 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.

Step 5 — Verify the container is running¶

Within one polling cycle the agent pulls the image and starts the container. To verify, open the device in the console and check the device inventory tab. The postgres container should appear in the list with a status of running.

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

docker ps

Expected outcome: The postgres container appears in the output with status Up.

Container not running?

If the container exits immediately, check the logs from the inventory tab or with docker logs postgres. The most common cause is a missing or invalid environment variable. If the agent did not pull the image, verify that the device can reach the registry and that the agent has converged since the commit (check the audit log for the commit event).

Done¶

You have deployed a Docker container using desired-state configuration. The agent will continue to enforce this state on every convergence cycle: if the container stops or is removed, the agent restarts or recreates it.

What Next?¶

I want to...	Go to
Deploy a multi-service stack with Docker Compose	Deploy a Docker Compose Project
Use Podman instead of Docker	Podman
Pull images from a private registry	FAQ
View container status in the inventory	Inventory
Access a running container	Remote Access