Skip to content
Klutch.sh Docs

Deploying CasaOS

Introduction

CasaOS is a simple, elegant, open-source personal cloud operating system that brings cloud computing back to your home. Built with Go and designed with a focus on user experience, CasaOS provides an intuitive interface for managing files, installing Docker applications, and controlling your personal data center. With support for numerous self-hosted applications including Nextcloud, HomeAssistant, Jellyfin, and over 100,000 apps from the Docker ecosystem, CasaOS democratizes data ownership and gives you complete control over your digital assets. Deploy CasaOS on Klutch.sh to create a personal cloud server that manages your files, runs containerized applications, and puts your data sovereignty in your hands.

Key Features

  • Intuitive Dashboard: User-friendly interface designed for home cloud scenarios without technical complexity
  • File Management: Elegant file browser for organizing and accessing your personal data
  • Docker App Support: Install and manage over 100,000 Docker applications with one-click installation
  • App Store: Pre-selected, community-verified applications including Nextcloud, HomeAssistant, Jellyfin
  • Multi-Device Support: Run on Raspberry Pi, Intel NUC, ZimaBoard, or any Linux system
  • Storage Management: Easily add disks and manage storage expansion
  • Network File Sharing: Share files across your local network
  • User Management: Create and manage multiple user accounts
  • Privacy Protection: Self-hosted architecture keeps your data private and under your control
  • Docker Container Management: Advanced Docker container controls and monitoring
  • Custom App Installation: Import and install custom Docker applications from Docker Hub
  • Widget System: Customizable dashboard widgets for system and app status
  • Resource Monitoring: Real-time monitoring of CPU, memory, disk, and network usage
  • Application Marketplace: Curated selection of 50+ community-verified applications
  • Backup and Restore: Tools for backing up and restoring your data
  • Web Interface: Access from any device on your network
  • Responsive Design: Works seamlessly on desktop, tablet, and mobile devices
  • Multi-language Support: Interface available in multiple languages
  • Community Driven: Active community with regular updates and contributions
  • Open Source: Apache 2.0 licensed and fully transparent development

Prerequisites

Before deploying CasaOS on Klutch.sh, ensure you have:

  • A Klutch.sh account with access to the dashboard
  • A GitHub repository for your CasaOS deployment (public or private)
  • Docker installed and working on your deployment system
  • Sufficient storage for personal cloud data (100GB+ recommended)
  • Understanding of personal cloud concepts and file management
  • Network access to your deployment environment

Important Considerations

Deployment Steps

  1. Create a Dockerfile

    Create a Dockerfile in the root of your repository to containerize CasaOS:

    FROM golang:1.22-alpine AS builder
    

    # Install build dependencies
    RUN apk add --no-cache \
        git \
        make \
        gcc \
        musl-dev \
        npm \
        node
    

    # Set working directory
    WORKDIR /app
    

    # Clone CasaOS repository
    RUN git clone https://github.com/IceWhaleTech/CasaOS.git . && \
        git checkout main
    

    # Install dependencies and build
    RUN go mod download
    RUN npm ci
    RUN npm run build
    RUN go build -o casaos .
    

    # Runtime stage
    FROM alpine:latest
    

    # Install runtime dependencies
    RUN apk add --no-cache \
        ca-certificates \
        bash \
        curl \
        docker
    

    # Create app user
    RUN addgroup -g 1000 app && \
        adduser -D -u 1000 -G app app
    

    # Copy binary from builder
    COPY --from=builder /app/casaos /app/casaos
    COPY --from=builder /app/conf /app/conf
    COPY --from=builder /app/public /app/public
    

    # Set working directory
    WORKDIR /app
    

    # Create data directories
    RUN mkdir -p /data && \
        chown -R app:app /data
    

    # Switch to app user
    USER app
    

    # Expose port
    EXPOSE 8080
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
        CMD curl -f http://localhost:8080 || exit 1
    

    # Start CasaOS
    CMD ["/app/casaos"]

  2. Create CasaOS Configuration Files

    Create a config/casaos.conf file for core configuration:

    # CasaOS Configuration File
    

    # Server Port
    port=8080
    

    # Server Address
    address=0.0.0.0
    

    # Database Configuration
    [database]
    type=sqlite
    path=/data/casaos.db
    

    # File Storage Configuration
    [storage]
    root_path=/data/files
    max_upload_size=5368709120
    

    # Logging Configuration
    [logging]
    level=info
    path=/data/logs
    

    # Security Configuration
    [security]
    jwt_secret=your-secret-key-here
    session_timeout=3600
    enable_https=false

    Create an init.sh file for initialization:

    #!/bin/bash
    

    # CasaOS initialization script
    

    # Create necessary directories
    mkdir -p /data/files
    mkdir -p /data/logs
    mkdir -p /data/config
    

    # Check if configuration exists
    if [ ! -f /data/config/casaos.conf ]; then
        cp /app/conf/casaos.conf /data/config/casaos.conf
    fi
    

    # Start CasaOS
    exec /app/casaos

  3. Create Environment Configuration

    Create a .env.example file to document required environment variables:

    # CasaOS Environment Configuration
    

    # Application Settings
    CASAOS_PORT=8080
    CASAOS_DOMAIN=example-app.klutch.sh
    CASAOS_HOSTNAME=example-app
    

    # Storage Configuration
    DATA_PATH=/data
    FILE_ROOT_PATH=/data/files
    MAX_UPLOAD_SIZE=5368709120
    

    # Database
    DATABASE_TYPE=sqlite
    DATABASE_PATH=/data/casaos.db
    

    # Security
    JWT_SECRET=your-jwt-secret-key-here
    SESSION_TIMEOUT=3600
    ENABLE_HTTPS=false
    

    # Logging
    LOG_LEVEL=info
    LOG_PATH=/data/logs
    

    # Performance
    WORKER_PROCESSES=auto
    MAX_CONNECTIONS=1000
    

    # Optional: Docker Hub Configuration
    DOCKER_REGISTRY_URL=https://registry-1.docker.io

  4. Create Entrypoint Script

    Create an entrypoint.sh file for container startup:

    #!/bin/bash
    set -e
    

    echo "Starting CasaOS..."
    

    # Create necessary directories
    mkdir -p /data/files
    mkdir -p /data/logs
    mkdir -p /data/config
    

    # Set permissions
    chmod 755 /data
    chmod 755 /data/files
    chmod 755 /data/logs
    

    # Initialize database if needed
    if [ ! -f "/data/casaos.db" ]; then
        echo "Initializing database..."
        # Database will be created on first run
    fi
    

    # Start CasaOS
    echo "Starting CasaOS server on port ${CASAOS_PORT:-8080}..."
    exec /app/casaos

    Make it executable:

    Terminal window
    chmod +x entrypoint.sh

  5. Create .gitignore File

    Create a .gitignore file to exclude sensitive data and build artifacts:

    # Environment and secrets
    .env
    .env.local
    .env.*.local
    JWT_SECRET
    casaos.key
    

    # Data files
    /data/
    *.db
    *.sqlite3
    

    # Build artifacts
    dist/
    build/
    *.o
    *.a
    *.so
    

    # IDE
    .vscode/
    .idea/
    *.swp
    *.swo
    *~
    .DS_Store
    

    # Node
    node_modules/
    npm-debug.log
    yarn-error.log
    

    # Go
    vendor/
    .env
    

    # Logs
    *.log
    logs/
    

    # OS
    Thumbs.db
    .DS_Store

  6. Create docker-compose.yml for Local Testing

    Create a docker-compose.yml file for local development and testing (not for Klutch.sh deployment):

    version: '3.8'
    

    services:
      casaos:
        build: .
        container_name: casaos-dev
        ports:
          - "8080:8080"
        environment:
          - CASAOS_PORT=8080
          - CASAOS_DOMAIN=localhost:8080
          - DATA_PATH=/data
          - LOG_LEVEL=info
        volumes:
          - casaos_data:/data
          - /var/run/docker.sock:/var/run/docker.sock
        networks:
          - casaos-network
    

    volumes:
      casaos_data:
    

    networks:
      casaos-network:
        driver: bridge

  7. Push to GitHub

    Push your repository to GitHub with all configuration files:

    Terminal window
    git add Dockerfile entrypoint.sh .env.example \
      config/casaos.conf init.sh docker-compose.yml .gitignore
    git commit -m "Initial CasaOS deployment configuration"
    git push origin main

  8. Deploy on Klutch.sh

    1. Navigate to klutch.sh/app and log in to your dashboard
    2. Click Create New App
    3. Select Docker as the deployment method (detected automatically from your Dockerfile)
    4. Connect your GitHub repository containing the CasaOS deployment files
    5. Confirm the Dockerfile is detected from your root directory
    6. Click Deploy to start the deployment process
    7. Wait for the deployment to complete and your app to become active

  9. Configure Traffic Rules and Persistent Storage

    1. In your app dashboard, navigate to Traffic settings
    2. Select HTTP as the traffic type
    3. Set the internal port to 8080 (CasaOS web interface default)
    4. Save your traffic configuration
    5. Navigate to Volumes settings
    6. Click Add Volume
    7. Enter mount path: /data
    8. Set volume size to 500GB (adjust based on your personal cloud storage needs)
    9. Click Attach to create and mount the persistent volume
    10. Your CasaOS instance will be accessible at example-app.klutch.sh

Initial Setup and Configuration

After deploying CasaOS on Klutch.sh, complete the initial setup for your personal cloud.

Access Your CasaOS Instance

  1. Navigate to http://example-app.klutch.sh in your browser
  2. You’ll see the CasaOS login page
  3. Create your administrator account:
    • Enter your username
    • Set a strong password
    • Confirm password
  4. Click Create Account
  5. Log in with your new credentials
  6. Complete the initial setup wizard

Configure Basic Settings

  1. Navigate to Settings in the sidebar
  2. Configure general settings:
    • Hostname: Name for your CasaOS instance
    • System Name: Display name for your personal cloud
    • Language: Choose your preferred language
    • Time Zone: Set your local time zone
  3. Configure storage settings:
    • Set file storage paths
    • Configure upload size limits
  4. Save your settings

Set Up File Storage

  1. Navigate to Files section
  2. Create folder structure for organizing data:
    • Click New Folder
    • Enter folder name (e.g., Documents, Photos, Videos)
    • Create subfolders as needed
  3. Configure sharing settings:
    • Right-click folder → Share
    • Set access permissions (read-only or read-write)
    • Generate share links for network access

Install Pre-Configured Apps

  1. Navigate to App Store or Application Center
  2. Browse pre-installed, community-verified applications:
    • Click app to view details
    • Click Install to add to your CasaOS
  3. Configure installed apps:
    • Set access ports
    • Mount storage volumes
    • Configure environment variables

Install Custom Docker Apps

  1. Navigate to Application Center → Custom Install
  2. Find your desired Docker application:
    • Visit Docker Hub and search for app
    • Copy the docker run command
  3. Import the application:
    • Click Import button
    • Paste the Docker command
    • Click Submit
  4. Configure application settings:
    • Set listening port
    • Mount storage paths
    • Configure environment variables
  5. Click Install to deploy the application

Create User Accounts

  1. Navigate to Settings → Users
  2. Click Add User
  3. Enter user details:
    • Username: User login name
    • Password: Initial password
    • Role: Admin, User, or Guest
  4. Click Create
  5. Share login credentials with users via secure channel

Configure Network Sharing

  1. Navigate to Settings → Network
  2. Enable network file sharing:
    • Enable SMB/CIFS for Windows network access
    • Enable NFS for Unix/Linux network access
  3. Configure firewall settings:
    • Allow necessary ports through firewall
    • Configure port forwarding if accessing remotely
  4. Save network configuration

Monitor System Status

  1. Access the dashboard to monitor:
    • CPU and memory usage
    • Disk space utilization
    • Active applications
    • Network activity
  2. Use widgets to customize dashboard view
  3. Check application logs for any issues

Backup Your Data

  1. Configure backup strategy:
    • Determine backup frequency (daily, weekly, monthly)
    • Choose backup storage location
  2. Use built-in backup tools:
    • Navigate to Settings → Backup
    • Configure backup schedule
    • Select data to backup
  3. Verify backup integrity regularly

Environment Variables

Basic Configuration

Configure these essential environment variables for your CasaOS deployment:

  • CASAOS_PORT=8080 - Web interface port
  • CASAOS_DOMAIN=example-app.klutch.sh - External domain for CasaOS
  • DATA_PATH=/data - Base path for data storage
  • FILE_ROOT_PATH=/data/files - Root path for file storage
  • DATABASE_TYPE=sqlite - Database type (sqlite recommended)
  • LOG_LEVEL=info - Logging verbosity level

Production Environment Variables

For production deployments using Nixpacks, configure these environment variables for optimal performance:

# Application Core
CASAOS_PORT=8080
CASAOS_DOMAIN=example-app.klutch.sh
CASAOS_HOSTNAME=example-app-server


# Data and Storage
DATA_PATH=/data
FILE_ROOT_PATH=/data/files
MAX_UPLOAD_SIZE=5368709120


# Database Configuration
DATABASE_TYPE=sqlite
DATABASE_PATH=/data/casaos.db


# Security and Authentication
JWT_SECRET=your-very-long-random-secret-key-here
SESSION_TIMEOUT=3600
ENABLE_HTTPS=false
SECURE_COOKIES=true


# Logging
LOG_LEVEL=info
LOG_PATH=/data/logs
LOG_MAX_SIZE=100m


# Performance
WORKER_PROCESSES=auto
MAX_CONNECTIONS=1000
CONNECTION_TIMEOUT=30


# Docker Integration
DOCKER_REGISTRY_URL=https://registry-1.docker.io
DOCKER_SOCKET=/var/run/docker.sock
DOCKER_TIMEOUT=300


# Optional Features
ENABLE_BACKUP=true
ENABLE_SHARING=true
ENABLE_NETWORK_ACCESS=true
NETWORK_SHARE_TYPE=smb

Code Examples

Go - CasaOS File Management Module

// CasaOS File Management Module
package main


import (
    "fmt"
    "io"
    "os"
    "path/filepath"
)


type FileManager struct {
    RootPath string
}


// Create a new FileManager
func NewFileManager(rootPath string) *FileManager {
    return &FileManager{
        RootPath: rootPath,
    }
}


// List files in directory
func (fm *FileManager) ListFiles(path string) ([]os.FileInfo, error) {
    fullPath := filepath.Join(fm.RootPath, path)


    files, err := os.ReadDir(fullPath)
    if err != nil {
        return nil, fmt.Errorf("failed to read directory: %v", err)
    }


    var fileInfos []os.FileInfo
    for _, file := range files {
        info, err := file.Info()
        if err != nil {
            continue
        }
        fileInfos = append(fileInfos, info)
    }


    return fileInfos, nil
}


// Create directory
func (fm *FileManager) CreateDirectory(path string, name string) error {
    fullPath := filepath.Join(fm.RootPath, path, name)


    err := os.MkdirAll(fullPath, 0755)
    if err != nil {
        return fmt.Errorf("failed to create directory: %v", err)
    }


    return nil
}


// Upload file
func (fm *FileManager) UploadFile(path string, filename string, file io.Reader) error {
    fullPath := filepath.Join(fm.RootPath, path, filename)


    out, err := os.Create(fullPath)
    if err != nil {
        return fmt.Errorf("failed to create file: %v", err)
    }
    defer out.Close()


    _, err = io.Copy(out, file)
    if err != nil {
        return fmt.Errorf("failed to write file: %v", err)
    }


    return nil
}


// Download file
func (fm *FileManager) DownloadFile(path string) (io.Reader, error) {
    fullPath := filepath.Join(fm.RootPath, path)


    file, err := os.Open(fullPath)
    if err != nil {
        return nil, fmt.Errorf("failed to open file: %v", err)
    }


    return file, nil
}


// Delete file
func (fm *FileManager) DeleteFile(path string) error {
    fullPath := filepath.Join(fm.RootPath, path)


    err := os.Remove(fullPath)
    if err != nil {
        return fmt.Errorf("failed to delete file: %v", err)
    }


    return nil
}


// Get directory size
func (fm *FileManager) GetDirectorySize(path string) (int64, error) {
    var size int64
    fullPath := filepath.Join(fm.RootPath, path)


    err := filepath.Walk(fullPath, func(_ string, info os.FileInfo, err error) error {
        if err != nil {
            return err
        }
        if !info.IsDir() {
            size += info.Size()
        }
        return nil
    })


    return size, err
}


// Share file with link
func (fm *FileManager) ShareFile(path string, permissions string) (string, error) {
    // Generate unique share link
    shareToken := generateToken()


    // Store share information in database
    err := storeShareToken(shareToken, path, permissions)
    if err != nil {
        return "", fmt.Errorf("failed to create share: %v", err)
    }


    shareURL := fmt.Sprintf("https://example-app.klutch.sh/share/%s", shareToken)
    return shareURL, nil
}


// Import custom Docker app
func (fm *FileManager) ImportDockerApp(dockerCommand string) error {
    // Parse Docker command and create Appfile
    appFile, err := parseDockerCommand(dockerCommand)
    if err != nil {
        return fmt.Errorf("failed to parse Docker command: %v", err)
    }


    // Store app configuration
    err = storeAppConfiguration(appFile)
    if err != nil {
        return fmt.Errorf("failed to store app configuration: %v", err)
    }


    return nil
}


// Helper functions
func generateToken() string {
    // Implementation for generating unique token
    return ""
}


func storeShareToken(token string, path string, permissions string) error {
    // Implementation for storing share information
    return nil
}


func parseDockerCommand(command string) (interface{}, error) {
    // Implementation for parsing Docker command
    return nil, nil
}


func storeAppConfiguration(appFile interface{}) error {
    // Implementation for storing app configuration
    return nil
}


// Usage example
func main() {
    fm := NewFileManager("/data/files")


    // List files
    files, err := fm.ListFiles("/")
    if err != nil {
        fmt.Printf("Error listing files: %v\n", err)
    } else {
        for _, file := range files {
            fmt.Printf("- %s (%d bytes)\n", file.Name(), file.Size())
        }
    }


    // Create directory
    err = fm.CreateDirectory("/", "Documents")
    if err != nil {
        fmt.Printf("Error creating directory: %v\n", err)
    } else {
        fmt.Println("Directory created successfully")
    }


    // Get directory size
    size, err := fm.GetDirectorySize("/")
    if err != nil {
        fmt.Printf("Error getting size: %v\n", err)
    } else {
        fmt.Printf("Total size: %d bytes\n", size)
    }
}

Bash - CasaOS Management Script

#!/bin/bash


# CasaOS Management and Administration Script
# Perform common management tasks


CASAOS_HOST="example-app.klutch.sh"
CASAOS_URL="http://${CASAOS_HOST}"


# Color output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'


# Check instance status
check_status() {
  echo -e "${BLUE}Checking CasaOS instance status...${NC}"


  if curl -s "${CASAOS_URL}" > /dev/null 2>&1; then
    echo -e "${GREEN}✓ CasaOS is online${NC}"
    return 0
  else
    echo -e "${RED}✗ CasaOS is offline${NC}"
    return 1
  fi
}


# List applications
list_apps() {
  echo -e "${BLUE}Listing installed applications:${NC}"


  curl -s "${CASAOS_URL}/api/apps" | \
    jq '.[] | {name: .name, status: .status, port: .port}' 2>/dev/null || \
    echo "Unable to parse application list (jq not available)"
}


# Get storage usage
get_storage_usage() {
  echo -e "${BLUE}Storage usage:${NC}"


  curl -s "${CASAOS_URL}/api/storage/usage" | \
    jq '{total: .total, used: .used, available: .available, percentage: .percentage}' 2>/dev/null || \
    echo "Unable to fetch storage information"
}


# Get system stats
get_system_stats() {
  echo -e "${BLUE}System statistics:${NC}"


  curl -s "${CASAOS_URL}/api/system/stats" | \
    jq '{cpu: .cpu, memory: .memory, uptime: .uptime}' 2>/dev/null || \
    echo "Unable to fetch system statistics"
}


# Install application
install_app() {
  local app_name=$1


  if [ -z "$app_name" ]; then
    echo -e "${RED}Usage: install_app <app_name>${NC}"
    return 1
  fi


  echo -e "${YELLOW}Installing application: $app_name${NC}"


  curl -s -X POST "${CASAOS_URL}/api/apps/install" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"$app_name\"}" | \
    jq . 2>/dev/null || echo "Installation initiated"
}


# Start application
start_app() {
  local app_id=$1


  if [ -z "$app_id" ]; then
    echo -e "${RED}Usage: start_app <app_id>${NC}"
    return 1
  fi


  echo -e "${YELLOW}Starting application $app_id...${NC}"


  curl -s -X POST "${CASAOS_URL}/api/apps/${app_id}/start" | \
    jq . 2>/dev/null || echo "Start command sent"
}


# Stop application
stop_app() {
  local app_id=$1


  if [ -z "$app_id" ]; then
    echo -e "${RED}Usage: stop_app <app_id>${NC}"
    return 1
  fi


  echo -e "${YELLOW}Stopping application $app_id...${NC}"


  curl -s -X POST "${CASAOS_URL}/api/apps/${app_id}/stop" | \
    jq . 2>/dev/null || echo "Stop command sent"
}


# List files
list_files() {
  local path=${1:-/}


  echo -e "${BLUE}Files in $path:${NC}"


  curl -s "${CASAOS_URL}/api/files/list?path=$path" | \
    jq '.[] | {name: .name, size: .size, type: .type, modified: .modified}' 2>/dev/null || \
    echo "Unable to list files"
}


# Get disk usage
get_disk_usage() {
  echo -e "${BLUE}Disk usage breakdown:${NC}"


  curl -s "${CASAOS_URL}/api/storage/disk-usage" | \
    jq '.[] | {device: .device, mount: .mount, total: .total, used: .used, available: .available}' 2>/dev/null || \
    echo "Unable to fetch disk usage"
}


# Backup system
backup_system() {
  local output_file=${1:-casaos_backup_$(date +%s).tar.gz}


  echo -e "${YELLOW}Backing up CasaOS configuration...${NC}"


  tar -czf "$output_file" -C /data . 2>/dev/null && \
    echo -e "${GREEN}✓ Backup complete: $output_file${NC}" || \
    echo -e "${RED}✗ Backup failed${NC}"
}


# View logs
view_logs() {
  local lines=${1:-50}


  echo -e "${BLUE}Recent CasaOS logs:${NC}"


  tail -n $lines /data/logs/casaos.log 2>/dev/null || \
    echo "Log file not available"
}


# Main menu
case "${1:-help}" in
  status)
    check_status
    ;;
  apps)
    list_apps
    ;;
  storage)
    get_storage_usage
    ;;
  stats)
    get_system_stats
    ;;
  install)
    install_app "$2"
    ;;
  start)
    start_app "$2"
    ;;
  stop)
    stop_app "$2"
    ;;
  files)
    list_files "${2:-/}"
    ;;
  disk)
    get_disk_usage
    ;;
  backup)
    backup_system "${2:-casaos_backup_$(date +%s).tar.gz}"
    ;;
  logs)
    view_logs "${2:-50}"
    ;;
  *)
    echo -e "${YELLOW}CasaOS Management Tool${NC}"
    echo "Usage: $0 {status|apps|storage|stats|install|start|stop|files|disk|backup|logs} [args]"
    echo ""
    echo "Commands:"
    echo "  status              - Check instance status"
    echo "  apps                - List installed applications"
    echo "  storage             - Show storage usage"
    echo "  stats               - Display system statistics"
    echo "  install <name>      - Install application"
    echo "  start <app_id>      - Start application"
    echo "  stop <app_id>       - Stop application"
    echo "  files [path]        - List files in directory"
    echo "  disk                - Show disk usage"
    echo "  backup [file]       - Backup configuration"
    echo "  logs [lines]        - View recent logs"
    ;;
esac

Shell - CasaOS Initialization and Monitoring

#!/bin/sh


# CasaOS Initialization and Monitoring Script
# Initialize a fresh CasaOS instance and monitor its status


CASAOS_CONTAINER="casaos"
CASAOS_PORT=8080
CASAOS_URL="http://localhost:${CASAOS_PORT}"


# Initialize CasaOS application
init_casaos() {
  echo "Initializing CasaOS..."


  echo "Step 1: Creating data directories..."
  mkdir -p /data/files
  mkdir -p /data/logs
  mkdir -p /data/config


  echo "Step 2: Setting permissions..."
  chmod 755 /data
  chmod 755 /data/files
  chmod 755 /data/logs


  echo "Step 3: Starting CasaOS service..."
  docker start $CASAOS_CONTAINER 2>/dev/null || \
    echo "Container not running yet"


  echo "Step 4: Waiting for CasaOS to initialize..."
  sleep 5


  # Check if service is running
  if curl -s "$CASAOS_URL" > /dev/null 2>&1; then
    echo "✓ CasaOS is ready"
  else
    echo "✗ CasaOS initialization may have issues"
  fi


  echo ""
  echo "Initialization complete!"
  echo "Access CasaOS at: $CASAOS_URL"
  echo "Create your admin account on first login"
}


# Monitor container health
monitor_health() {
  echo "Monitoring CasaOS health..."


  while true; do
    clear
    echo "=== CasaOS Health Monitor ==="
    echo "Time: $(date)"
    echo ""


    # Check container status
    if docker ps | grep -q $CASAOS_CONTAINER; then
      echo "✓ CasaOS container running"
    else
      echo "✗ CasaOS container stopped"
    fi


    # Check web interface
    if curl -s "$CASAOS_URL" > /dev/null 2>&1; then
      echo "✓ Web interface responding"
    else
      echo "✗ Web interface not responding"
    fi


    # Show container stats
    echo ""
    echo "Container Stats:"
    docker stats --no-stream $CASAOS_CONTAINER 2>/dev/null | tail -1 || echo "Stats unavailable"


    # Show recent logs
    echo ""
    echo "Recent logs (last 5 lines):"
    docker logs --tail 5 $CASAOS_CONTAINER 2>/dev/null || echo "Logs unavailable"


    sleep 10
  done
}


# List running applications
list_running_apps() {
  echo "Running CasaOS applications..."


  docker exec $CASAOS_CONTAINER curl -s http://localhost:8080/api/apps 2>/dev/null | \
    grep -o '"name":"[^"]*"' | \
    cut -d'"' -f4 || echo "Unable to list applications"
}


# Check storage usage
check_storage() {
  echo "Storage usage:"


  docker exec $CASAOS_CONTAINER df -h /data 2>/dev/null || \
    df -h /data
}


# Backup data
backup_data() {
  local timestamp=$(date +%Y%m%d_%H%M%S)
  local backup_file="casaos_backup_${timestamp}.tar.gz"


  echo "Creating CasaOS backup..."


  tar -czf "$backup_file" -C /data . 2>/dev/null && \
    echo "✓ Backup complete: $backup_file" || \
    echo "✗ Backup failed"
}


# View application logs
view_app_logs() {
  local lines=${1:-50}


  echo "Displaying last $lines lines of CasaOS logs..."


  docker logs --tail $lines $CASAOS_CONTAINER 2>/dev/null || \
    tail -n $lines /data/logs/casaos.log 2>/dev/null || \
    echo "Logs unavailable"
}


# Main function
case "${1:-help}" in
  init)
    init_casaos
    ;;
  monitor)
    monitor_health
    ;;
  apps)
    list_running_apps
    ;;
  storage)
    check_storage
    ;;
  backup)
    backup_data
    ;;
  logs)
    view_app_logs "${2:-50}"
    ;;
  *)
    echo "CasaOS Initialization and Monitoring"
    echo "Usage: $0 {init|monitor|apps|storage|backup|logs} [args]"
    echo ""
    echo "Commands:"
    echo "  init              - Initialize CasaOS instance"
    echo "  monitor           - Monitor instance health"
    echo "  apps              - List running applications"
    echo "  storage           - Check storage usage"
    echo "  backup            - Backup CasaOS data"
    echo "  logs [lines]      - View application logs"
    ;;
esac

Best Practices

  • Regular Backups: Implement automated daily backups of critical data
  • Storage Planning: Monitor storage usage and plan expansion before running out of space
  • Application Selection: Verify Docker applications from trusted sources before installation
  • Security Updates: Keep CasaOS and installed applications updated regularly
  • User Management: Use strong passwords and manage user permissions carefully
  • Network Security: Restrict network access to trusted devices only
  • Performance Monitoring: Monitor resource usage and optimize container allocation
  • Data Organization: Create a logical folder structure for easy file management
  • Access Control: Use appropriate sharing permissions for different user types
  • Documentation: Maintain records of installed applications and configurations
  • Testing: Test backup and restore procedures regularly
  • Community Support: Engage with CasaOS community for troubleshooting and advice

Troubleshooting

Issue: “Can’t access CasaOS web interface”

  • Verify CasaOS container is running: docker ps | grep casaos
  • Check firewall rules allowing port 8080
  • Verify network connectivity to the server
  • Check application logs for startup errors

Issue: File uploads failing

  • Verify persistent volume is properly mounted
  • Check disk space availability
  • Review file size limits in configuration
  • Check file permissions on storage directory

Issue: Slow performance or laggy interface

  • Monitor CPU and memory usage
  • Check disk I/O performance
  • Reduce number of simultaneously running applications
  • Clear browser cache and cookies

Issue: Application won’t start or install

  • Verify Docker daemon is running
  • Check internet connectivity for Docker registry access
  • Review application logs for errors
  • Verify sufficient disk space for application

Issue: Network sharing not working

  • Verify SMB/NFS is enabled in settings
  • Check firewall rules for network file sharing ports
  • Verify correct network share credentials
  • Test connectivity from client device

Issue: Data corruption or loss

  • Restore from most recent backup
  • Check disk health and SMART status
  • Review system logs for errors
  • Consider filesystem check and repair

Update Instructions

To update CasaOS to the latest version:

  1. Check Current Version: View your current CasaOS version in settings
  2. Backup First: Create a complete backup before updating
  3. Update via UI:
    • Navigate to Settings → Update
    • Click Check for Updates
    • Click Update if new version is available
  4. Update via Terminal (if needed):
    Terminal window
    ssh into-server
    wget -qO- https://get.casaos.io/update | sudo bash
  5. Verify: Test functionality after update completes
  6. Monitor Logs: Watch logs for any post-update issues

Use Cases

  • Personal File Storage: Centralized backup for important documents and photos
  • Media Server: Host and stream video, music, and media content
  • Home Automation Hub: Run HomeAssistant and IoT device management
  • Development Environment: Host development databases and tools
  • Collaborative Workspace: Share files and projects with team members
  • Backup Solution: Automated backup system for multiple devices
  • Document Management: Centralized document storage and sharing with Nextcloud
  • Email Server: Host your own email service
  • Chat Platform: Run Mattermost or other communication platforms
  • Database Server: Host PostgreSQL, MySQL, or other databases
  • VPN Server: Create secure remote access to your network
  • Ad Blocking: Deploy AdGuard for network-wide ad blocking

Additional Resources

Conclusion

Deploying CasaOS on Klutch.sh provides a personal cloud server that puts data ownership and control back in your hands. By following this guide, you’ve set up a production-ready CasaOS instance with persistent storage for your files, applications, and personal data.

Your CasaOS deployment is now ready to serve as a personal cloud platform for managing files, running self-hosted applications, and maintaining complete data sovereignty. Whether you’re backing up important files, hosting media content, running home automation, or deploying custom Docker applications, CasaOS provides the flexibility and control needed for a modern personal cloud.

For advanced configurations, community-developed applications, or additional support, refer to the official CasaOS documentation, community forums, and Discord channel. Regular updates, backups, and security practices will keep your personal cloud secure and running smoothly.