Docker Basics

Every app on your PCS runs inside a Docker container. You don't need to understand Docker to use your PCS — CasaOS handles everything for you. But if you want more control, knowing the basics is helpful.

Key Concepts

Containers

A container is a lightweight, isolated environment that runs a single application. Think of it as a mini virtual machine that contains everything the app needs to run: the code, runtime, libraries, and settings.

• Each app on your PCS runs in its own container
• Containers are isolated from each other — a problem in one app doesn't affect others
• Containers can be started, stopped, restarted, and removed without affecting the host system

Images

An image is the blueprint for a container. When you install an app through CasaOS, it downloads the app's Docker image and creates a container from it.

• Images are read-only templates
• When you update an app, CasaOS pulls a newer version of the image
• Images are stored in Docker's internal storage, not in /DATA/AppData/

Volumes

Volumes are how containers store persistent data. Without volumes, all data would be lost when a container restarts.

• On your PCS, app data is stored in /DATA/AppData/<app-name>/
• This directory is "mounted" into the container so the app can read and write data
• Volumes persist even when the container is stopped or removed

Docker Compose

Docker Compose is a tool for defining multi-container applications. Most PCS apps use a docker-compose.yml file that describes:

• Which image to use
• Which ports to expose
• Which volumes to mount
• Which environment variables to set
• How containers depend on each other

Essential Commands

Connect to your PCS terminal from Admin Panel → Terminal to run these commands.

Viewing Containers

# List all running containers
docker ps

# List all containers (including stopped)
docker ps -a

# Show only container names and status
docker ps --format "table {{.Names}}\t{{.Status}}"

Container Lifecycle

# Stop a container
docker stop <container-name>

# Start a stopped container
docker start <container-name>

# Restart a container
docker restart <container-name>

# View container details
docker inspect <container-name>

Viewing Logs

Logs are essential for debugging:

# View the last 100 lines of logs
docker logs <container-name> --tail 100

# Follow logs in real-time (Ctrl+C to stop)
docker logs <container-name> -f

# Show logs with timestamps
docker logs <container-name> --tail 50 -t

# Show logs from the last hour
docker logs <container-name> --since 1h

Managing Resources

# See resource usage for all containers
docker stats

# See resource usage for a specific container
docker stats <container-name>

# Check how much disk space Docker is using
docker system df

# Clean up unused Docker resources
docker system prune

Working with Images

# List downloaded images
docker images

# Pull (download) a specific image
docker pull <image-name>:<tag>

# Remove unused images
docker image prune

Executing Commands Inside Containers

Sometimes you need to run commands inside a running container:

# Open a shell inside a container
docker exec -it <container-name> /bin/bash

# If bash isn't available (Alpine-based images)
docker exec -it <container-name> /bin/sh

# Run a single command
docker exec <container-name> ls /app

Docker Compose Commands

For apps managed by Docker Compose:

# Navigate to the app's directory
cd /DATA/AppData/<app-name>

# Start the app (in background)
docker compose up -d

# Stop the app
docker compose down

# Restart the app
docker compose restart

# View logs
docker compose logs --tail 50

# Pull latest images and restart
docker compose pull && docker compose up -d

Common Tasks

Finding Out Why an App Crashed

# Check the container's status and exit code
docker ps -a | grep <app-name>

# Read the logs leading up to the crash
docker logs <container-name> --tail 200

# Check if the container was killed due to memory
docker inspect <container-name> | grep -i oom

Checking How Much Space an App Uses

# Size of the app's data directory
du -sh /DATA/AppData/<app-name>/

# Size of the app's Docker image
docker images | grep <app-name>

Manually Updating an App

If CasaOS's update mechanism isn't working:

cd /DATA/AppData/<app-name>

# Pull the latest image
docker compose pull

# Recreate the container with the new image
docker compose up -d

Checking Network Connectivity from a Container

# Test if a container can reach the internet
docker exec <container-name> ping -c 3 8.8.8.8

# Test DNS resolution from inside a container
docker exec <container-name> nslookup google.com

Docker vs CasaOS

Task	CasaOS	Docker CLI
Install app	App Store → Install	docker compose up -d
Start/stop app	Right-click → Start/Stop	docker start/stop
Update app	Right-click → Update	docker compose pull && up -d
View logs	Not available	docker logs
Shell access	Not available	docker exec -it ... /bin/bash
Resource usage	Basic widgets	docker stats
Cleanup	Not available	docker system prune

For most users, CasaOS is sufficient. Docker CLI is for power users who need more visibility and control.

warning

Be careful with Docker commands that remove data (docker rm, docker volume rm, docker system prune --volumes). Always create a backup from Admin Panel → Apps before running destructive commands.

tip

If you break something with Docker commands, you can usually recover by restoring from a backup or reinstalling the app through CasaOS. Your data in /DATA/AppData/ persists unless you explicitly delete it.