Add a Compose Runtime Image

​

Introduction

The Compose Runtime is a virtual machine image that runs the Docker Engine and the compose agent on a node. Before you can deploy Docker Compose applications, the Compose Runtime must exist as an edge app in your enterprise library. The recommended path is to import a ZEDEDA-published Compose Runtime edge app from the Marketplace. It arrives with its image, its two network interfaces, and its configuration template already defined. If you received the Compose Runtime as a QCOW2 file instead, add the image to the image library and create the edge app yourself. The edge app is what you select when deploying the Compose Runtime as an application instance. If the edge app does not define network interfaces, the deployment wizard shows “No network interfaces defined in the application manifest” and you cannot complete the deployment.

​

Prerequisites

• You have the SysManager or SysAdmin role in your enterprise. See Manage Roles.
• If you add the image yourself: the Compose Runtime QCOW2 file, or its SHA-256 hash, file size, and datastore path if uplinking from an existing datastore, and a configured datastore to store the image.

​

Choose a Runtime Variant

ZEDEDA publishes the Compose Runtime in two variants. Both run the same Docker Engine and compose agent, and both are deployed the same way. They differ only in whether the runtime can attach an existing ZFS storage pool. Each variant is published in more than one size. The size sets the default CPU, memory, and storage of the runtime VM. Choose the size that matches your node’s capacity. The ZFS variant needs one additional drive on the edge app and two configuration files that you edit before deployment. After you complete this page, see Attach an Existing ZFS Pool to the Compose Runtime for those steps.

​

Import the Compose Runtime From the Marketplace

This is the recommended path. The imported edge app includes the runtime image, the two required network interfaces, and the configuration template.

1. In the sidebar, select Marketplace.
2. Select Edge Apps.
3. In the search field, enter zed-compose-runtime.
4. Open the variant and size you chose in the preceding section. The card shows the runtime version, for example 3.0.0.
5. Select Add to library.

The edge app appears in Marketplace > My Library under the Edge Apps filter tab. You can deploy it as it is. Continue to Deploy the Compose Runtime Application. If you need to change the sizing, drives, or configuration template before deploying, open the edge app in My Library, select Duplicate, and then select Duplicate & Configure. The edge app wizard opens pre-filled with the imported settings. The sections that follow describe each wizard step. The ZFS variant always needs this step, because you must add the pool drive and edit the configuration template.

​

Add the Compose Runtime Image Yourself

Use this section only if you received the Compose Runtime as a QCOW2 file rather than importing it from the Marketplace.

​

Open the image type selector

1. In the sidebar, navigate to Infrastructure > Workloads > Build > App Images.
2. Select New App Image.
3. On the Add Edge App Image screen, select Compose Runtime.

​

Complete image details

1. Select QCOW2. This is the only format available for the Compose Runtime type.
2. Select the CPU architecture the image targets: AMD 64 for x86-64 nodes, or ARM 64 for ARM 64-bit nodes.
3. Select Next.

​

Provide storage details

To upload the QCOW2 file from your computer:

1. In the Add Image Via field, select Upload.
2. In the Image Path field, enter a file name for the image.
3. Select Choose File and select the QCOW2 file.
4. In the Data Store field, select the datastore where the uploaded image is stored.
5. Select Next.

To reference an image already stored in a datastore:

1. In the Add Image Via field, select Uplink manually.
2. In the SHA256 field, enter the 64-character hexadecimal SHA-256 hash of the image file.
3. In the Image Size field, enter the file size and select the unit.
4. In the Datastores field, select the datastore where the image is stored.
5. Enter the Image Relative URL: the path to the image within the datastore.
6. Select Next.

​

Complete general information and add the image

1. In the Name field, enter a unique identifier using alphanumeric characters and hyphens (for example, compose-runtime-amd64). The name must be at least three characters.
2. In the Title field, enter a display name.
3. Optionally, enter a Description.
4. Select Add Image.

Edge Infrastructure Services uploads the file or begins uplinking. The image status changes to Ready when the process completes.

​

Create the Compose Runtime Edge App

The edge app defines the manifest that the deployment wizard reads, including the network interfaces and drives. If you imported the runtime from the Marketplace and selected Duplicate & Configure, the wizard opens pre-filled and you can review each step rather than entering values from scratch. For the full wizard reference, see Import Edge Applications.

​

Open the edge app creation wizard

1. In the sidebar, navigate to Marketplace > My Library.
2. Select the + floating action button and then select Edge Apps.
3. Select Virtual Machine as the application type.

​

Configure identity

1. In the Name field, enter a unique identifier (for example, compose-runtime).
2. In the Title field, enter a display name.
3. Optionally, enter a Description.
4. In the Deployment Type field, select Compose Runtime.
5. Select Next.

​

Configure resources

The Resources & CPU step sets the runtime VM’s resources. The Compose Runtime is a VM, so it requires dedicated CPU and memory.

1. Under Sizing, select a preset (for example, Small or Typical), or select Custom and set vCPUs, Memory, and Storage.
2. In the Persistence Storage Size field, set the size of the dedicated disk that stores the runtime’s own persistent container state, such as Docker volumes created by Compose applications. This field appears because you selected Compose Runtime as the deployment type, and it is separate from Storage. Set it to match your VM drive size (for example, 10 GB), because the default might be larger than smaller nodes can hold. When the runtime deploys, a persistent data volume of this size is created, and its data survives upgrades of the runtime software. This disk is not the same as an attached ZFS pool, which is an existing volume that the ZFS variant imports rather than creates.
3. For VM Mode, select HVM. The Compose Runtime image is an HVM-compatible QCOW2 image.
4. Select Next.

​

Configure drives

The Drives step attaches the Compose Runtime image and any data disks to the edge app.

1. In the first drive, keep the source as From Image and select the Compose Runtime image in the Image field.
2. Set Max Size to match your image size (for example, 10 GB).
3. To give the runtime an additional blank data disk that belongs to the instance, select Add Drive, select Empty Disk, and set its Max Size. Leave Purge on Update off so that the disk survives a purge.
4. For the ZFS variant, select Add Drive and configure the second drive as described in Attach an Existing ZFS Pool to the Compose Runtime. That drive references the existing pool volume by its Volume Label rather than by an image. Skip this step for the standard variant.
5. Select Next.

Data disks must come after the boot image in the drive list. While instances of the edge app exist, you can add or remove data disks only at the end of the list.

​

Configure interfaces

This is the step that determines whether the deployment wizard can proceed. The Compose Runtime requires exactly two virtual network interfaces.

1. Confirm that Configure network interfaces is on.
2. For the first interface, set Name to eth0 and set Type to Virtual Network, not Direct Attach. This interface handles application traffic and makes container services reachable through the Switch virtual network.
3. Under Outbound Rules, add a rule with Host / IP set to 0.0.0.0/0 and Action set to Allow, so that the containers can reach the outside network.
4. Select Add Interface.
5. For the second interface, set Name to eth1 and set Type to Virtual Network. This interface handles internal traffic between the Compose Runtime and Edge Infrastructure Services through the Local air-gapped virtual network.
6. Select Next.

​

Add a configuration template

The configuration template defines the fields that appear in the Custom Config step of the deployment wizard, including the Compose Runtime SSH credentials and optional static IP settings. Without this template, the deployment wizard does not prompt for those values. The template is provided with the Compose Runtime image distribution and is already present on edge apps imported from the Marketplace. Do not author it from scratch. The ZFS variant’s template contains two additional files, zvol-mounts.sh and zvol-mounts.conf, that you must edit before deployment. See Attach an Existing ZFS Pool to the Compose Runtime.

1. Confirm that Include custom configuration template is on.
2. Enter the Configuration Name (for example, compose-runtime-config).
3. Set the Delimiter to match the placeholder format used in the template (for example, ###).
4. Paste the configuration template provided with your Compose Runtime image distribution, or review the pre-filled template if you duplicated an imported edge app.
5. Select Next.

​

Complete developer info and create

1. Confirm or enter the Name and Email on the Developer Info step.
2. Select Next to review the configuration.
3. On the Review step, verify the identity, sizing (including Persistence Storage Size), drives, and interfaces. Confirm that two virtual network interfaces, eth0 and eth1, are listed. For the ZFS variant, confirm that a second drive with the ZFS pool’s volume label is listed.
4. Select Create Edge App.

​

Verify the Configuration

1. Navigate to Marketplace > My Library.
2. Locate the Compose Runtime edge app.
3. Open the app and confirm that the Interfaces tab shows two interfaces, eth0 and eth1, and that the Drives tab shows the runtime image first, followed by any data disks.
4. If you added the image yourself, navigate to Infrastructure > Workloads > Build > App Images and confirm that the Compose Runtime image status is Ready.

If either verification fails, the deployment wizard does not function correctly. Resolve image status errors before proceeding, and re-create the edge app if the interfaces are missing.

​

Next Steps

This article is part of the Docker Compose setup series. The next step is deploying the Compose Runtime as an application instance on your node.

1. Docker Compose Overview: background on the architecture and deployment model.
2. Add a Compose Runtime Image (you are here).
3. Deploy the Compose Runtime Application: deploy the edge app as an application instance.
4. Attach an Existing ZFS Pool to the Compose Runtime: ZFS variant only. Configure the pool import and dataset discovery.
5. Compose App Instance Control Overview: how the Compose Runtime manages Docker Compose application lifecycles.
6. Add a Docker Compose Image: create the Docker Compose app image that runs inside the Compose Runtime.
7. Deploy a Docker Compose Application: deploy the Docker Compose app as an application instance on the node that runs the Compose Runtime.
8. Troubleshoot Docker Compose: diagnose issues with the Compose Runtime or Docker Compose application instances.