> ## Documentation Index > Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL. > Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other. > Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking. > Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify. # Docker Compose Architecture and Deployment Model > Learn how Docker Compose workloads run inside the Compose Runtime on EVE-OS, how the compose agent manages stacks, and how to deploy Compose app images. ## Introduction Docker Compose is a standard tool for defining and running multi-container applications. A `compose.yaml` file declares the services, networks, volumes, and dependencies that make up an application stack. Edge Infrastructure Services supports Docker Compose as a first-class workload type, allowing you to deploy and manage multi-container applications on nodes alongside VMs and single-container apps. ## Architecture Docker Compose workloads on EVE-OS (Edge Virtualization Engine) run inside a dedicated **Compose Runtime** environment. The Compose Runtime is itself an application instance: a QCOW2 image that provides an isolated virtualized environment where the Docker engine and compose agent run. The **compose agent** (also called the Z-Agent or `zrun-agent`) runs inside the Compose Runtime and manages the lifecycle of Docker Compose stacks on behalf of Edge Infrastructure Services. It receives compose files and credentials through patch envelopes (Runtime Bundles) and handles deployment, updates, and lifecycle events for the containers in the stack. Key architectural properties: * **Isolation**: containers in the compose stack run inside the Compose Runtime VM, not directly on the EVE-OS host. This separates the application stack from the node platform. * **Networking**: the Compose Runtime connects to the node through two virtual interfaces. One handles application traffic (connected to a public or local network instance) and the other handles management traffic between the compose agent and Edge Infrastructure Services. * **Multiple stacks**: multiple Docker Compose applications can co-exist within a single Compose Runtime instance. ![Docker Compose topology showing the Compose Runtime VM on a node, with the compose agent, Docker engine, and compose stacks inside, connected via virtual network interfaces to Edge Infrastructure Services and external networks.](https://mintcdn.com/zededa/nH470gZ2VKSQBZu8/new-ui/infrastructure-services/applications/images/docker_compose_topology.png?fit=max\&auto=format\&n=nH470gZ2VKSQBZu8\&q=85\&s=f8424b36973ee08e510178aaef93168d) ## Deployment Model Deploying a Docker Compose workload involves two layers: 1. **Deploy the Compose Runtime**: deploy the Compose Runtime app image as an application instance on the target node. The Compose Runtime provides the environment where compose stacks run. See [Deploy an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-instance.md) for the full procedure. 2. **Deploy Docker Compose apps**: create a Docker Compose type edge app in Marketplace > My Library, either by pasting the Compose YAML or by selecting a Docker Compose TAR image from Infrastructure > Workloads > Build > App Images, and deploy it as an application instance to the same node where the Compose Runtime is running. Edge Infrastructure Services delivers the compose file to the compose agent, which brings up the defined services. See [Deploy a Docker Compose Application](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-a-docker-compose-application.md). ## Docker Compose App Images When you add a Docker Compose app image in Infrastructure > Workloads > Build > App Images: * The image format is set to **RAW** automatically. You do not select a format. * There is no architecture selector. Docker Compose apps are architecture-independent at the image definition level. * You provide the compose file as a **TAR archive** (`*.tar`). The TAR file bundles the `compose.yaml` and any related files into a single archive that Edge Infrastructure Services uploads to the datastore. The TAR file approach supports complex configurations that include multiple files alongside the compose definition. For simpler single-file configurations, package the `compose.yaml` in a TAR archive before uploading. For the full procedure for creating a Docker Compose app image, see [Add a Docker Compose Image](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/add-a-docker-compose-image.md). ## Lifecycle Management Docker Compose application instances support the same lifecycle actions as other app types in the console: **Start**, **Stop**, **Restart**, **Update**, and **Purge & Update**. (The ZEDEDA API and ZCLI call Start and Stop *activate* and *deactivate*.) Each action applies to the whole compose stack managed by the compose agent. See [Deploy a Docker Compose Application](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-a-docker-compose-application.md#control-the-running-stack) for how each action maps to a Docker Compose command. The following operations are **not available** for Docker Compose instances: * **Attach Patch Envelope**: patch envelopes cannot be attached to Docker Compose application instances from the Actions menu. * **VM Options** (vTPM, VMM Overhead): these settings do not apply to Docker Compose workloads. ## Delivering Compose Files and Credentials Docker Compose files and container registry credentials are delivered to the compose agent through **patch envelopes** (Runtime Bundles). Patch envelopes use encryption to protect the contents in transit. This mechanism provides: * **Secure configuration delivery**: the compose file is transmitted encrypted and delivered to the compose agent only when the patch envelope is in the Active state. * **Credential protection**: container registry credentials (usernames, passwords, tokens) are included in the patch envelope and never stored in plaintext on the node. * **Dynamic updates**: updating a patch envelope with a new compose file or updated credentials triggers the compose agent to apply the changes to the running stack. For information on creating and managing patch envelopes, see [Update Applications with Runtime Bundles](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/update-applications-with-runtime-bundles.md). ## Key Features * **Integrated observability**: logs and metrics from compose stacks are accessible from the application instance detail page and from **Infrastructure > Monitor > Logs**, filtered to the Compose Runtime instance. * **Separation of concerns**: the Compose Runtime isolates the compose stack from the EVE-OS host, providing a clean boundary between the platform and the application. * **Lifecycle consistency**: compose stacks follow the same lifecycle state model (Online, Halted, Error, and so on) as other application types in Edge Infrastructure Services. * **Multi-stack support**: a single Compose Runtime can host multiple compose application instances, each managed independently. ## Next Steps This article is part of the Docker Compose setup series. 1. **Docker Compose Overview (you are here).** 2. [Add a Compose Runtime Image](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/add-a-compose-runtime-image.md): add the base runtime image and create the Edge App bundle with network interfaces. 3. [Deploy the Compose Runtime Application](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-compose-runtime.md): deploy the Compose Runtime as an application instance on your node. 4. [Attach an Existing ZFS Pool to the Compose Runtime](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/attach-existing-zfs-pool-to-compose-runtime.md): ZFS variant only. Configure the pool import and dataset discovery. 5. [Compose App Instance Control Overview](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/compose-app-instance-control-overview.md): how the Compose Runtime manages Docker Compose application lifecycles. 6. [Add a Docker Compose Image](https://zededa.mintlify.site/new-ui/infrastructure-services/build-and-library/add-a-docker-compose-image.md): create the Docker Compose app image that runs inside the Compose Runtime. 7. [Deploy a Docker Compose Application](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-a-docker-compose-application.md): deploy the Docker Compose app as an application instance on the node that runs the Compose Runtime. 8. [Troubleshoot Docker Compose](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/troubleshooting-docker-compose.md): diagnose issues with the Compose Runtime or Docker Compose application instances.