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

> Explore CasaOS Docker installation and management. Discover its Go middleware, CLI commands via shell helpers, and real-time UI status updates via websockets. Learn how CasaOS simplifies complex Docker operations.

- Repository: [IceWhale/CasaOS](https://github.com/IceWhaleTech/CasaOS)
- Tags: deep-dive
- Published: 2026-06-27

---

**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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main//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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/model/notify.go) and [`model/o_notify.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/system.go)). This wrapper calls the [`helper.sh`](https://github.com/IceWhaleTech/CasaOS/blob/main/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**

```http
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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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**

```bash
#!/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/helper.sh) script, ensuring compatibility with standard Docker installations.
- The **notification system** in [`service/notify.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/service/notify.go) creates `AppNotify` records and pushes websocket events to provide real-time installation progress.
- **Docker root detection** in [`helper.sh`](https://github.com/IceWhaleTech/CasaOS/blob/main/helper.sh) (lines 46-53) rewrites daemon configuration to control container storage locations.
- The **V2 API** ([`route/v2.go`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/route/v2.go), which processes `application/x-yaml` payloads and forwards them to [`helper.sh`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/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`](https://github.com/IceWhaleTech/CasaOS/blob/main/helper.sh) checks `docker info` to identify the current Docker root directory and rewrites [`/etc/docker/daemon.json`](https://github.com/IceWhaleTech/CasaOS/blob/main//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.