How CasaOS Handles Docker Application Installation and Management: A Technical Deep Dive

CasaOS orchestrates Docker application lifecycles through a Go-based middleware layer that parses container configurations, executes CLI commands via shell helpers, and streams real-time status updates to the UI through websocket notifications.

CasaOS treats every Docker-based application as a first-class entity within its ecosystem, abstracting container complexity behind a unified management interface. According to the IceWhaleTech/CasaOS source code, the platform handles Docker application installation and management through a three-stage pipeline: discovery and configuration parsing, execution via wrapper scripts, and continuous runtime monitoring. This architecture enables users to install applications from the built-in App Store or import Docker Compose files while maintaining full control over container storage and lifecycle events.

Discovery and Configuration Parsing

When a user selects an application from the CasaOS App Store or imports a Docker Compose file, the system first extracts container metadata including image names, ports, volumes, and environment variables. This parsing logic resides in the low-level shell helper script, which validates configurations and prepares the Docker execution environment.

Docker Root Directory Detection

In build/sysroot/usr/share/casaos/shell/helper.sh, CasaOS executes docker info to detect the "Docker Root Dir" and validates the target image name. Lines 46-53 of this script inspect the Docker daemon configuration and rewrite /etc/docker/daemon.json to point to a custom data-root, ensuring CasaOS controls exactly where container data persists on the host filesystem.

Docker Compose Import via V2 API

For users importing existing stacks, the V2 API endpoint defined in route/v2.go (lines 98-102) accepts application/x-yaml payloads. When a compose file is posted to this endpoint, CasaOS forwards the YAML definition to the helper script, which subsequently executes docker compose up -d to orchestrate multi-container deployments.

Installation Pipeline and Notification System

The actual container creation bridges Go services and shell execution through a standardized command wrapper. This layer ensures consistent error handling and logging while providing real-time feedback to the frontend.

Real-Time Status Notifications

In service/notify.go (lines 34-48), CasaOS creates an AppNotify entry immediately upon receiving an install request. This component records the operation in the database—defined in model/notify.go and model/o_notify.go—and broadcasts websocket events to the UI. Users see progress bars and error messages as the system transitions through download, container creation, and startup phases.

CLI Execution Architecture

Rather than using a Docker client library, CasaOS invokes the Docker CLI directly through the command.OnlyExec wrapper found throughout the codebase (notably in service/system.go). This wrapper calls the helper.sh script to execute either docker run for single containers or docker compose up -d for imported stacks. The wrapper captures stdout and stderr for structured logging, standardizing how the system handles Docker daemon responses.

Example: Installing an App via the REST API

POST /v2/app/install HTTP/1.1
Content-Type: application/json

{
  "image":"library/jellyfin:latest",
  "name":"Jellyfin",
  "ports":[{"container":8096,"host":8096}],
  "env":{"TZ":"UTC"},
  "volumes":[{"container":"/config","host":"/DATA/AppData/Jellyfin"}]
}

The handler creates an AppNotify entry, executes docker run -d through the helper script, and streams status updates back to connected clients.

Runtime Monitoring and Cleanup

After installation, CasaOS continues to manage container state through periodic inspection and provides comprehensive cleanup utilities for system maintenance or uninstallation.

Container Status Monitoring

The platform monitors running applications by executing docker ps calls inside the helper.sh script. These queries determine whether containers are running, stopped, or restarting, with the results propagated back to the CasaOS dashboard for display.

System Cleanup and Uninstall

For complete removal, the Debian-specific cleanup script at build/sysroot/usr/share/casaos/cleanup/service.d/casaos/debian/cleanup-casaos.sh (lines 65-78) stops all containers with docker stop $(docker ps -aq), removes them with docker rm, and optionally prunes images using docker image prune -af. Finally, it removes the Docker root directory entirely to reclaim disk space.

Example: Complete Docker Cleanup

#!/usr/bin/env bash

# Stop and remove every container

docker stop "$(docker ps -aq)" && docker rm "$(docker ps -aq)"

# Remove all images (or just unused ones)

docker rmi "$(docker images -q)"   # full purge

# docker image prune -af          # keep only used images

Summary

• CasaOS delegates all Docker operations to CLI commands executed through the helper.sh script, ensuring compatibility with standard Docker installations.
• The notification system in service/notify.go creates AppNotify records and pushes websocket events to provide real-time installation progress.
• Docker root detection in helper.sh (lines 46-53) rewrites daemon configuration to control container storage locations.
• The V2 API (route/v2.go) supports Docker Compose imports via YAML payloads, enabling multi-container application deployment.
• Cleanup scripts stop all containers, prune images, and remove the Docker root directory during uninstallation.

Frequently Asked Questions

How does CasaOS handle Docker Compose file imports?

CasaOS accepts Docker Compose files through the V2 API endpoint in route/v2.go, which processes application/x-yaml payloads and forwards them to helper.sh. The helper script then executes docker compose up -d to deploy the entire stack, treating the compose definition as a single application entity within the CasaOS dashboard.

What happens during the Docker application uninstall process?

The platform runs the Debian-specific cleanup script at build/sysroot/usr/share/casaos/cleanup/service.d/casaos/debian/cleanup-casaos.sh, which stops all running containers with docker stop, removes them with docker rm, and optionally prunes images. Finally, it deletes the Docker root directory to ensure complete data removal.

How does CasaOS communicate installation progress to the UI?

When an installation begins, service/notify.go creates an AppNotify database entry and broadcasts websocket events to connected clients. This mechanism allows the frontend to display real-time progress bars, download status, and error messages as the command.OnlyExec wrapper executes Docker CLI commands in the background.

Where does CasaOS store Docker container data?

During initialization, helper.sh checks docker info to identify the current Docker root directory and rewrites /etc/docker/daemon.json to point to a CasaOS-controlled data-root. This ensures all container layers, volumes, and metadata reside in a predictable location that the system can monitor and clean up during uninstallation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}