CasaOS: Built a Home Cloud on Raspberry Pi

Wanted a home server but didn't want to deal with CLI Docker commands. Found CasaOS - a web UI that makes your Pi feel like a mini cloud. Running Nextcloud, Plex, and Home Assistant on a $75 setup. The installation was almost too easy.

External Hard Drive Not Detected by CasaOS

Problem

Set up CasaOS on a Raspberry Pi 4, plugged in a 2TB external USB drive. The drive was visible in lsblk and I could mount it manually, but CasaOS storage panel showed "No drives available". Couldn't use it for app data.

Error: Drive not available for CasaOS management

What I Tried

Attempt 1: Reformatted drive to ext4 - still not detected.
Attempt 2: Restarted CasaOS service - drive appeared briefly then disappeared.
Attempt 3: Tried different USB port - same issue.

Actual Fix

CasaOS requires drives to be unmounted and formatted with specific partition types. The issue was that the drive had an NTFS partition (from Windows use) and CasaOS prefers ext4. Also, the drive needs to be properly unmounted first, then CasaOS will take over management. 

# 1. Unmount the drive if mounted
sudo umount /dev/sda1

# 2. Format to ext4 (CasaOS preference)
sudo mkfs.ext4 /dev/sda1

# 3. Get the disk UUID (needed by CasaOS)
sudo blkid /dev/sda1

# 4. Create mount point
sudo mkdir -p /mnt/external

# 5. Add to fstab for automatic mounting
echo 'UUID=your-uuid-here /mnt/external ext4 defaults 0 2' | sudo tee -a /etc/fstab

# 6. Mount
sudo mount -a

# 7. Restart CasaOS to detect drive
sudo systemctl restart casaos

# 8. In CasaOS UI: Settings → Storage → Add Drive
# Should now see the drive available
App Installation Fails with "Port Already in Use"

Problem

Trying to install Nextcloud through CasaOS App Store. Installation got to 80% then failed with "Port 80 already in use". Checked CasaOS - no other apps running. Port 80 was supposed to be available.

Error: Error: bind: address already in use

What I Tried

Attempt 1: Uninstalled and reinstalled Nextcloud - same error.
Attempt 2: Changed Nextcloud port to 8080 - worked but broke web access.
Attempt 3: Killed all Docker containers - CasaOS UI stopped working too.

Actual Fix

CasaOS itself uses port 80 for its web UI. When installing apps like Nextcloud that also want port 80, there's a conflict. The solution is to use CasaOS's built-in reverse proxy to route domains/subdomains to different apps, rather than running everything on the same port. 

# 1. Check what's using port 80
sudo lsof -i :80

# You'll see CasaOS using it - this is normal

# 2. Instead of changing ports, use CasaOS's domain routing:
# In CasaOS UI: App → Nextcloud → Network

# 3. Set up local DNS or use different ports per app:
# Nextcloud: cloud.home.lan:8080
# Plex: plex.home.lan:32400
# Home Assistant: home.home.lan:8123

# 4. Or use CasaOS's reverse proxy (recommended):
# In CasaOS: Settings → Network → Reverse Proxy
# Enable it, then each app can have its own subdomain

# 5. Add to your router's DNS or /etc/hosts:
# 192.168.1.100 cloud.home.lan
# 192.168.1.100 plex.home.lan
# 192.168.1.100 home.home.lan

# Then apps can all use their default ports internally
Raspberry Pi Running Out of Memory with Multiple Apps

Problem

Running CasaOS + Nextcloud + Plex + Home Assistant on a 4GB Pi 4. System became unresponsive after a few hours. SSH was slow, apps were timing out. free -h showed only 100MB free and heavy swap usage.

What I Tried

Attempt 1: Added 2GB swap file on SD card - made it worse (slow SD + wear issues).
Attempt 2: Disabled Plex transcoding - reduced RAM usage but still problematic.
Attempt 3: Stopped Home Assistant - system was stable but defeated the purpose.

Actual Fix

4GB RAM isn't enough for all those apps simultaneously. The solution involved: 1) Using swap on USB drive (not SD), 2) Adding Docker memory limits per app, and 3) Using an optimized architecture with fewer resource-heavy apps. Consider upgrading to 8GB Pi or adding more Pis. 

# 1. Create swap on USB drive (faster than SD)
sudo fallocate -l 2G /mnt/external/swapfile
sudo chmod 600 /mnt/external/swapfile
sudo mkswap /mnt/external/swapfile
sudo swapon /mnt/external/swapfile
echo '/mnt/external/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

# 2. Add memory limits to Docker containers
# In CasaOS UI: App → Settings → Resources
# Set limits per app:
# - CasaOS: 512MB
# - Nextcloud: 1GB
# - Plex: 512MB (no transcoding)
# - Home Assistant: 512MB

# 3. Or edit docker-compose directly
# In CasaOS: /var/lib/casaos/apps/
# Add to each service:
deploy:
  resources:
    limits:
      memory: 512M

# 4. Monitor memory usage
watch -n 5 'free -h && docker stats --no-stream'

# 5. Consider architecture changes:
# - Use separate Pi for media (Plex) vs services (Nextcloud)
# - Upgrade to 8GB Pi 4
# - Use mini PC with 16GB RAM for ~$200

What I Learned

Production Setup

Complete Raspberry Pi setup with CasaOS. 

# 1. Flash Raspberry Pi OS Lite (64-bit) to SD card
# Use Raspberry Pi Imager: https://www.raspberrypi.com/software/

# 2. Enable SSH and set hostname
# In advanced settings of Raspberry Pi Imager:
# - Enable SSH: Use password authentication
# - Set hostname: casaos.local

# 3. Boot and connect
ssh pi@casaos.local

# 4. Update system
sudo apt update && sudo apt upgrade -y

# 5. Install CasaOS
curl -fsSL https://get.icewhale.io/casaos.sh | bash

# 6. Access CasaOS web UI
# Open browser: http://casaos.local
# Initial setup wizard will appear

# 7. Configure external storage
# Settings → Storage → Add Drive
# Select your external drive

# 8. Install essential apps from App Store
# - Portainer (for Docker management)
# - File Browser (for file management)
# - Nextcloud (for cloud storage)
# - Plex/Jellyfin (for media)
# Recommended CasaOS apps for home server:

# 1. Cloud Storage
casaos-app-install nextcloud

# 2. Media Server
casaos-app-install jellyfin  # More efficient than Plex on Pi

# 3. Home Automation
casaos-app-install homeassistant

# 4. Network Tools
casaos-app-install pi-hole
casaos-app-install wireguard

# 5. Development
casaos-app-install portainer
casaos-app-install vscode-server

# 6. Backup
casaos-app-install syncthing

# Or install through the web UI:
# CasaOS → Apps → App Store → Search & Install

Monitoring & Debugging

Keep your home cloud healthy:

Essential Commands

# CasaOS service management
sudo systemctl status casaos
sudo systemctl restart casaos
journalctl -u casaos -f

# Container management
docker ps
docker stats --no-stream
docker logs 

# System resources
htop
free -h
df -h
vcgencmd measure_temp  # CPU temperature

# Network
ip addr
ping casaos.local

# Backup CasaOS configuration
tar -czf casaos-backup-$(date +%Y%m%d).tar.gz /var/lib/casaos

# Update CasaOS
casaos-update

Red Flags to Watch For

Related Resources