Add a Docker Compose as an Edge App Type

Updated

Introduction

This article describes how to add Docker Compose as an edge application type. All the types are described in the Manage an Edge Application article. This is a series of articles. You will likely follow them in this order.

  1. Edge Application Overview
  2. Manage an Edge App Image 
  3. Manage an Edge Application
  4. Deploy an Application Instance

Prerequisites

Configure the Identity

  1. Log in to the ZEDEDA GUI.
  2. Hover over Marketplace on the left panel.
  3. Select Edge Apps from the options.
  4. Click on the + icon to create a new edge app.
  5. Select Docker Compose as the Edge App Type.
  6. Continue on to the identity details.
     

 

Identity details

  1. Fill in the following: 
    • Name: This value can't be changed later.
    • Title: This value is for flexibility. You can change it at any time. 
    • Description: You can use this to help other admins understand the purpose of the app or any important details about the app.
  2. Category: Select the category that best describes the app. If no category describes the app, you can type one of your own and that category is created.
  3. Select the Deployment Type: 
    • Standalone: Runs the application independently on the edge device without relying on any external cloud services.
  4. Select the Container Registry Datastore. Specify the location(s) where the agent using the credentials can access the Docker images referenced in your compose.yaml file.

    IMPORTANT:  If you have not specified a repository, ZEDEDA Cloud will pull images from Docker Hub even if you did not explicitly configure Docker Hub as a datastore. If a datastore has not been provided, the agent will perform a fetch without any prior authentication procedure. Similarly, if you have provided a datastore with empty login credentials, authentication will be skipped.
     
  5. Add a License: Helps users understand the terms under which they can use, modify, or distribute the application. It can also affect how the application interacts with other components in the ZEDEDA ecosystem.
  6. Click Next.

 

Configure the Definitions

After configuring the identity details, configure the definitions. You are filling out the configuration manifest with all of the necessary details so ZEDEDA Cloud will know how to set up and run the instructions in your Docker Compose edge application.

  1. Click Import File.
  2. Select one of the following file types:
    • YAML (.yaml or .yml): This is the plain-text file used to define a Docker Compose application. This file, which is written in YAML format, describes the services, networks, volumes, and other configurations for your multi-container application. The Compose Runtime will parse the YAML file to understand how to deploy and manage your containers. You must load this functionality into ZEDEDA Cloud via the Marketplace. For a list of limitations on the characters that are not allowed in your YAML file, see YAML special character limitations.
       
    • Tar (.tar): A TAR file is an archive format that can bundle multiple files together. You should choose this option if you will be deploying multiple edge apps on one edge node. You will need to package your compose.yaml file, edge apps, and other related files into a single TAR archive file. This approach can be useful for organizing your app definition or if your workflow involves distributing the configuration as a single file. ZEDEDA will need to unpack this TAR file to access the compose.yaml file within.

       

 

YAML file type definitions

When configuring a Docker Compose application to be deployed to a managed edge node, you could include definitions for the following basic configuration options in your compose.yaml file. These are just hypothetical examples:

  • Services:
    • image: The most crucial definition, specifying the Docker image to be used for each container. This tells the edge node what software to run. For example: 
      image: your-registry.io/your-app:latest or 
      image: ubuntu:20.04
    • container_name: Not recommended due to logging infrastructure.
    • restart (often always or unless-stopped): Defines the restart policy for the containers. always means the container will always restart if it stops, and unless-stopped means it will restart unless it was explicitly stopped by the user. This is important for ensuring the application's reliability on the edge.
  • Networking:
    • ports (if the application needs to expose ports): Maps ports from the host (edge node) to the container. This allows external access to services running inside the containers. For example: 
      - "8080:80" maps port 80 inside the container to port 8080 on the edge node.
    • networks (to define internal networks for communication between containers): Allows you to create isolated networks so that different services within your application can communicate with each other. You would then assign services to these networks.
  • Storage:
    • volumes (for persistent data or sharing data between containers): Defines how data should be persisted beyond the lifecycle of a container or shared between different containers. This is crucial for applications that need to store data locally on the edge node. You can define named volumes or bind mounts to host directories.

For example:

YAML
volumes:
  - data_volume:/app/data

and then in a service:

YAML
volumes:
  - data_volume:/container/data
  • read_only (for security): You might want to define certain container filesystems as read-only to enhance security.

     
  • Environment Variables:

    • environment: Allows you to pass configuration parameters to your containers as environment variables. This is a common way to configure application behavior without hardcoding values into the Docker image. For example:
      YAML
       

      environment:
  - API_KEY=your_secret_key
  - LOG_LEVEL=INFO
  • Dependencies and Startup Order (less common for very basic setups but important for more complex ones):
    • depends_on: Specifies dependencies between services. Docker Compose will attempt to start the dependent services before the current service. This can be important if one service relies on another (for example, an application needs a database to be running).

YAML Sample Configuration

Here’s an example of a basic compose.yaml config file for a simple web application:

version: '3.8'
services:

# Nginx Service
  web:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443" # Expose HTTPS port

    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf # Mount Nginx config
      - ./html:/usr/share/nginx/html   # Mount your site's files

    depends_on: 
      - db

    restart: always

    networks:
      - app_net

# Database Service (PostgreSQL)
  db:
    image: postgres:14
    environment:
      - POSTGRES_USER=myuser
      - POSTGRES_PASSWORD=mypassword
      - POSTGRES_DB=mydb

    volumes:
      - db_data:/var/lib/postgresql/data
    restart: always
    networks:
      - app_net

# Define Networks
networks:
  app_net:
    driver: bridge

# Define Volumes
volumes:
  db_data:
  nginx_conf: #redundant
  html_data: #redundant

Explanation (for sample above):

  • Services: Defines the two services:
    • web: Uses the latest Nginx image.
    • Maps port 80 of the container to port 80 on the host.
    • Maps port 443 of the container to port 443 on the host.
    • Mounts a local nginx.conf to configure Nginx.
    • Mounts a local html directory to serve website files.
    • Depends on the db service.
    • Restart always
  • Part of the app_net network
  • db: Uses Postgres version 14.
    • Sets environment variables for the username, password, and database name.
    • Persists data to the db_data volume.
    • Restart always
  • Part of the app_net network
  • Networks: Creates a network called app_net for the services to communicate.
  • Volumes: Defines a volume for the database data for persistence.

 

TAR file: Workflow for creating and uploading a TAR archive file

Before you can add a Docker Compose as an edge app type, you need to create the TAR file first. Follow these instructions to package your Docker Compose application into a TAR file and upload it to ZEDEDA Cloud using the ZCLI.

  1. Prepare Application Directory:
    • Ensure all necessary files for your Docker Compose application (for example, compose.yaml, .env files, supporting scripts) are located within a single directory, such as hello-world-compose-app.
       
  2. Create the TAR Archive:
    • Navigate to the parent directory containing your application folder in your terminal.
    • Run the tar command to create a gzipped TAR archive of your application directory's contents. (Replace hello-world-compose-app with your actual directory name if different.)
tar -czvf hello-world-compose-app.tar.gz -C hello-world-compose-app .
  • Explanation: This command creates (c) a gzipped (z) archive file named hello-world-compose-app.tar.gz (f), printing verbose output (v). It changes (-C) into the hello-world-compose-app directory first and then adds everything (.) from within that directory to the archive.
     
  1. Register the Image in ZEDEDA Cloud:
    • Use the zcli command to create an image entry in ZEDEDA Cloud for your TAR file. Replace hello-world-compose-tar with your desired image name and adjust --datastore-name if necessary.
zcli image create hello-world-compose-tar --datastore-name=Zededa-AWS-Image --image-format=raw --compose-tar-image
  • Explanation: This registers an image named hello-world-compose-tar in the specified datastore, marking it as a raw format image specifically intended for Docker Compose TAR deployments (--compose-tar-image).
     
  1. Upload the TAR Archive:
    • Use the zcli command to upload the actual .tar.gz file created in Step 2. Replace hello-world-compose-tar if you used a different name in Step 3, and crucially, replace path/to/your/hello-world-compose-app.tar.gz with the actual path to the archive file on your system.
zcli image upload hello-world-compose-tar --path=path/to/your/hello-world-compose-app.tar.gz
  • Explanation: This uploads the specified TAR file and associates it with the image entry created in the previous step.
     
  1. Create Application in the ZEDEDA Cloud: 
    • NOTE: When prompted for the source or type in the procedure below, select the option indicating a TAR file, and choose the image name you registered in 
      Step 3 (e.g., hello-world-compose-tar) from the available images.
    • Complete the remaining application configuration as needed.

 

TAR example type

The example below shows how to configure a Docker Compose application to be deployed to a ZEDEDA-managed edge node with a compose.tar archive file. 

  • The example starts a webserver on port 8080.
  • Serves a static index.html on “/” directory. 
  • It uses the nginx.config file (both of which are in the tar file).

Explanation of the Files:

  1. compose.yaml:  
    • The YAML file is the core Docker Compose file. This defines the application's services, and inside the file, it defines a service named nginx.
    • The YAML file specifies using the latest official nginx Docker image.
    • It creates a mapping between port 8080 on the edge node's network interface (as assigned by ZEDEDA) to port 80 inside the Nginx container.  
    • It mounts two local paths into the container:
      • ./nginx.conf (from the TAR file) is mounted to /etc/nginx/nginx.conf inside the container, providing a custom Nginx configuration.  
      • ./html (this directory is expected within the TAR file) is mounted to /usr/share/nginx/html inside the container, which is the default location Nginx serves files from.
  2. index.html:  
    • This is a simple HTML file that will be served by the Nginx web server. It contains a basic "Hello, World!" message.  
    • This is based on the compose.yaml volume mount (./html:/usr/share/nginx/html), and this file must be placed inside an html subdirectory within your TAR file structure!
  3. nginx.conf:  
    • This file provides a custom configuration for the Nginx server running inside the container.
    • The nginx.conf tells Nginx to listen on port 80 (which is mapped to 8080 externally by the compose file). 
    • It also configures Nginx to serve files from the /usr/share/nginx/html directory, and specifically to look for index.html as the default file.

Creating and Deploying the compose.tar File:

  1. Prepare the File Structure: Create a directory on your local machine. 
    Inside it, place the following files:
    1. The compose.yaml file.  
    2. The nginx.conf file.  
    3. Create a subdirectory named html.
    4. Place the index.html file inside the html subdirectory.

When finished, your directory structure should look like this:

your-app-directory/
├── compose.yaml
├── nginx.conf
└── html/
    └── index.html
  1. Create the TAR File: Navigate to the parent of your-app-directory in your terminal and create the TAR archive:
    Bash 
tar -cvf compose.tar -C your-app-directory .

Note: Make sure to include the -C your-app-directory . part to ensure the paths inside the tar file are relative to that directory, matching the ./ references in compose.yaml

  1. Upload to ZEDEDA Cloud:
    1. Log in to your ZEDEDA Cloud UI.
    2. Navigate to the Edge Application catalog (under Library > Edge App Images).
    3. Add a new Edge App image.
    4. For Image Type, choose Docker Compose.
    5. When prompted for application artifacts or bundles, upload the compose.tar file you just created. ZEDEDA will recognize it contains a compose.yaml and associated files.
  2. Configure and Deploy the Application Instance:
    1. Go to Edge Nodes and select the target node(s).
    2. Deploy the App instance.
    3. Select the Edge Application definition you created in the previous step.
    4. Configure any necessary network settings (for example, mapping the application's port 8080 to a specific network interface on the edge node). ZEDEDA manages the network interfaces and IP assignments for the application on the edge node.
    5. Deploy the app instance.

ZEDEDA will transfer the compose.tar file to the specified edge nodes, extract it, and use the compose.yaml along with the bundled nginx.conf and index.html files to start the Nginx container using the local Container Runtime Stack managed by EVE-OS. You should then be able to access the "Hello, World!" page by navigating to the edge node's IP address (on the appropriate network interface) and port 8080 in a web browser.

 

Configure the Custom Configurations

After selecting the YAML or TAR file, determine if you need to add a custom configuration template. There is no requirement for custom config, but you can find more information at Custom Configuration Edge Application.

  1. Click Add Custom Config Template.
  2. Customize the config template. (See custom config for a runtime example.)
  3. Click Next.

Configure the Developer Info

There is nothing specific needed when adding Docker Compose as an edge app type, so you can configure these fields as you wish.

  1. Configure the fields of Name, Email, and Website. 
  2. Review the information. 
  3. Click Next.

 

Review & Add

  1. Review the info.
  2. Click Add.
  3. Verify your new addition by checking for it in the ZEDEDA Marketplace.

 

Next Steps

This is a series of articles. You will likely follow them in this order.

  1. Edge Application Overview
  2. Manage an Edge App Image 
  3. Manage an Edge Application
  4. Deploy an Application Instance

After you’ve completed the series, you might be interested in the following articles. 

Manage your edge nodes and edge apps.

Was this article helpful?
0 out of 0 found this helpful