Troubleshooting Docker Compose

Updated

Introduction

Troubleshooting your ZEDEDA-managed Docker Compose edge apps involves checking several key areas, from initial deployment and access, to runtime behavior, as detailed below.

Initial User Setup and Connecting to the Edge App

When Docker Compose runtime is deployed, you will be prompted to enter credentials
(username and password). Once entered, these are provided to the cloud-init function of the runtime application.

Within the runtime cloud-init script (cloud-init.sh), the user will be created with the specified password. Keep in mind that this user is a highly-privileged user with sudo and admin rights. 

WARNING: Securely record the username and password immediately upon creation. This password is not recoverable through the ZEDEDA UI or any other method. Losing these credentials will necessitate a full reinstallation of the compose runtime.

From here, you can access the edge node app in the following ways: 

  1. Use Edge View to establish an SSH connection to the air-gapped Ethernet port (eth2). For more information, see Edge View.

  2. Or, you can enable SSH on the edge node using the ZCLI.
    1. Enable SSH on the edge node using ZCLI.
    2. Locate the IP address of the edge node.
    3. Connect to the edge node using SSH.
    4. Identify the IP address of the edge app.
    5. Connect using SSH from the edge node to the edge app over the air-gapped Ethernet interface, which typically has IP address: 10.1.255.154 

For more information, see How to enable and disable SSH for an Edge Device.

Docker CLI for Debug

For debugging purposes, ZEDEDA uses the standard Docker CLI. Each ZEDEDA-managed Docker Compose app instance is assigned a unique identifier ( <appid> ). This app ID is directly mapped to the Docker Compose "project-name." 

This mapping allows you to use familiar Docker Compose commands to inspect the containers associated with a specific ZEDEDA-deployed app instance.
For example:  docker compose --project-name <appid> ps --all 

Viewing Logs and Events for a Runtime Instance

After deploying a runtime instance on an edge node device, you can return to that runtime to see information about the state of the device, as well as a list of events that have occurred as the app changes state (such as from “init” to “loading”, and from “loading” to “online”). You can also use this procedure to access the logs generated by the runtime instance.

  1. Log in to the ZEDEDA GUI.
  2. Click on Edge App Instances.
  3. Select the target runtime instance.
  4. The Status tab appears by default, with the following fields containing information about the state of the runtime instance. It appears the same as any other virtual machine, but the Runtime Platform Versions section includes info about the agent version, compose version, and container runtime version.
    For example: 
    Admin Status: Active
    Run State: Online
    Last Seen: Apr 07, 2025  10:22 AM
    Last Booted: Nov 15, 2024  2:06 PM
    Last Known Uptime: 167 day(s)
    Opaque Status: Not Available
  1. Click the Basic Info. This tab displays information about persistence storage size, eth1 and eth2 IP addresses, Disk info, and the Compose apps using this runtime. 
  2. Select one of the Docker compose applications using this runtime and then select the Events tab. This displays a list of events that have occurred as the Docker Compose app changes state, such as changing from “loading” to “online” or “restarting” to “online”.
  3. Click the Logs tab, where you can view a list of logging activity:

    The Docker Compose apps generate logs since the containers are designed to output information about relevant activities:
    • Normal Operations: Recording events such as startup sequence, processing requests, or routine status updates.
    • Errors & Warnings: Reporting problems, failures, or unexpected conditions encountered by the edge app.
    • Debugging: Providing detailed information to help ZEDEDA support diagnose issues.

 

Next steps

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

  1. Docker Compose Overview 
  2. Create the Compose Runtime Application
  3. Agent Overview
  4. Add a Docker Compose as an Edge App Type
  5. Troubleshooting - You are here!

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

  1. Manage your edge nodes and edge apps.
Was this article helpful?
0 out of 0 found this helpful