How to Install CasaOS on Linux: Full Setup Walkthrough

CasaOS turns a spare Linux box into a home server dashboard with a built-in app marketplace. No Docker CLI required. No complicated networking. You get a web interface, system monitoring, and one-click app installs. If you’ve been meaning to spin up services like Jellyfin or Nextcloud but balked at the command-line learning curve, this is worth an afternoon.

Why CasaOS Instead of Alternatives

The homelab space is crowded. Portainer does container management better. Proxmox handles VMs. TrueNAS owns storage. But CasaOS sits in a weird, useful middle ground: it assumes you own the hardware, you want to run apps, and you don’t want to SSH into a black terminal every time you need to change something.

The app store matters more than it sounds. Installing Nextcloud through CasaOS takes maybe ninety seconds. The same install via Docker Compose takes thirty minutes of YAML hunting and config guessing. For someone building their first homelab, that friction difference is real.

That said, CasaOS is opinionated. It assumes x86-64 hardware (or ARM64 on newer Pis). It wraps Docker, which means you’re not learning Docker—you’re learning CasaOS’s idea of Docker. If you want raw control or need to run non-container workloads, this isn’t it.

Prerequisites and Hardware

You need a Linux machine. Debian, Ubuntu, or Ubuntu-based distros work best. CasaOS officially supports Ubuntu 20.04 LTS and newer, but I’ve run it on Debian 12 without issues. Don’t use a live USB or container. This needs to be persistent hardware with its own IP address.

Hardware-wise, be realistic. The dashboard itself uses almost nothing. But running five containerized services concurrently does. Here’s what I’d actually recommend:

• Minimum: 2 CPU cores, 2GB RAM. You’ll feel it. App installs will be slow.
• Comfortable: 4 cores, 4GB RAM. Most small homelabs run here.
• Breathing room: 6+ cores, 8GB+ RAM. Leaves space for media servers, databases, and whatever you add next.

Storage doesn’t matter for CasaOS itself. It uses maybe 500MB. But if you’re running Jellyfin or Plex, plan for your media library. I’m running this on an Intel NUC with an i5, 16GB RAM, and a 500GB NVMe. Overkill for CasaOS alone, but realistic for a working homelab.

You also need a static IP address on the machine or a DHCP reservation. CasaOS runs on port 80 and 443. If something else is already using those, the install won’t fail—it’ll just create a mess you have to untangle. Worth checking first.

Installing CasaOS

SSH into your Linux machine. Make sure you have sudo access. Then run the official install script:

curl -fsSL https://get.casaos.io | sudo bash

That’s it. The script handles package dependencies, Docker installation, and the CasaOS container itself. On a fresh Ubuntu 22.04 system, this takes about two to four minutes. You’ll see output scrolling past. Skim it, but don’t panic at the words “ERROR” if they appear—the script often reports warnings that don’t actually break anything.

When it finishes, you’ll see something like:

CasaOS installed successfully. Access it at http://YOUR_IP_ADDRESS

Replace YOUR_IP_ADDRESS with the actual IP of your machine. If you don’t know it, type hostname -I and pick the one that looks like 192.168.x.x or 10.x.x.x.

Open a browser and go there. You should see the CasaOS login screen. Don’t get excited yet—you have to set up the admin account.

First-Run Configuration

The first person to access CasaOS becomes the admin. Create a username and password. Use something you won’t forget, but don’t use the default “admin/admin” nonsense. CasaOS will offer it. Resist.

Once logged in, you’re in the dashboard. You’ll see system stats (CPU, RAM, storage, network), a list of installed apps (empty at first), and a sidebar with settings. Take a breath. This is functional, not flashy.

Before installing apps, do three things:

First, set up local storage. Go to Settings → Storage. You’ll see mounts available to the system. If you have a second disk or partition where you want to store media, docker volumes, or backups, add it here. CasaOS needs to know where to put data that survives a restart. By default, everything goes to root, which is fine for testing but will bite you later.

Second, check the Network settings. Go to Settings → Network. Make sure CasaOS has the IP address you expect. If DHCP is on and you haven’t reserved the IP on your router, the address might change after a reboot. Set a static IP now or reserve it in your DHCP settings. This is tedious and nobody wants to do it, but you’ll thank yourself when you’re bookmarking the dashboard URL.

Third, turn on automatic updates. Settings → System → Auto Update. Enable it. CasaOS patches are usually small and safe. Letting your home server rot on an old version is how you end up with vulnerabilities.

Now you can breathe.

Installing Your First App

The App Store is in the main navigation. Click it. You’ll see categories: Media, Productivity, Utilities, Development. Pick something low-stakes first. I usually start with Portainer just so I can see what CasaOS actually installed under the hood.

Click on an app. You get a description, a link to the original project, and an Install button. Some apps have configurable fields—storage paths, port numbers, environment variables. Read them. They matter. If you install Jellyfin without pointing it to your media folder, it’ll start clean and confused.

Hit Install. The dashboard shows progress. It’s pulling a Docker image, creating a container, and wiring up the networking. Most apps finish in under two minutes. When the status changes to Running (usually with a green dot), you’re done. Click the app tile and it opens in a new tab.

This part actually works well. I was skeptical, but one-click installs beat the hell out of docker-compose files and missing environment variables.

Common Gotchas and Fixes

Port conflicts. If you try to install an app and it fails silently, check if something’s already using that port. CasaOS usually assigns predictable ports—8096 for Jellyfin, 5000 for something else. Use sudo netstat -tlnp to see what’s listening. If it’s another Docker container, you can usually reassign ports in CasaOS settings. If it’s a system service, you’ll need to stop it or uninstall it first.

Storage mounting issues. If you added a second disk and told CasaOS about it, but apps can’t access the data, check permissions. CasaOS runs containers as specific users. Your external drive might be owned by root with 755 permissions, which won’t let the container write. Fix it with:

sudo chown -R 1000:1000 /path/to/mounted/drive
sudo chmod -R 775 /path/to/mounted/drive

The 1000:1000 is a guess that works most of the time. If it doesn’t, check the app’s documentation for which UID it expects.

Dashboard becomes slow or unresponsive. This usually means one of your apps is consuming all available RAM. SSH in and check: docker stats. You’ll see CPU and memory usage per container. If something’s hogging resources, either kill it or increase your machine’s specs. There’s no magic tuning lever here.

You can’t reach the dashboard from outside your network. By design, CasaOS doesn’t expose itself to the internet. If you want remote access, you need a reverse proxy (Nginx Proxy Manager, which you can install via the app store, or Tailscale for wireguard-based access). This is annoying the first time you realize it, but it’s the right call security-wise.

Apps won’t update. CasaOS handles app updates through the dashboard, not Docker’s automatic restart policies. If an app is showing as outdated in the Store, go to App Management, find it, and hit the update button. Sometimes it fails quietly. Check the logs: Settings → Logs. The error messages there are usually cryptic, but at least you know something went wrong.

What to Do Next

After your first app runs, pick a second. Install something that does something useful for you—a photo backup service, a password manager, a media server. Each one teaches you how CasaOS handles persistent storage, networking, and configuration. By the third app, you’ll stop feeling like you’re following instructions and start feeling like you’re actually running things.

Set up backups for important data. CasaOS doesn’t do this automatically. Databases and user configs live in Docker volumes. If your machine dies, they’re gone. A simple rsync job to an external drive or NAS keeps you safe. Something like:

rsync -av /var/lib/docker/volumes/ /mnt/backup/casaos-volumes/

Run that weekly from a cron job. You won’t regret it.

If CasaOS ever feels limiting—if you need raw Docker access or need to run something that doesn’t fit the app model—remember that it’s just a wrapper. You can SSH in and manage containers directly. The thing about CasaOS is it gets you started fast, then gets out of your way if you need to go deeper.

FAQ

Can CasaOS run on a Raspberry Pi?

Yes, but with caveats. CasaOS supports ARMv7 (Pi 3 and older, reluctantly) and ARM64 (Pi 4 and 5, properly). A Pi 4 with 4GB is workable for light services. A Pi 5 with 8GB is actually pleasant. Anything older than a Pi 4 will struggle with multiple apps running simultaneously.

How much RAM does CasaOS need?

CasaOS itself needs about 200-300MB. But running actual apps on top demands more. I’d consider 2GB a hard minimum, 4GB comfortable, and 8GB breathing room. Without enough RAM, Docker will OOM-kill your containers unpredictably.

Can I use CasaOS if I already have Docker running?

Technically yes, practically no. CasaOS assumes it owns the Docker daemon. If you have other containers running elsewhere, CasaOS won’t see them or manage them. You’d have two competing interfaces for the same system. Pick one approach and stick with it.

Is CasaOS secure enough for public internet access?

No. Don’t expose it directly. Use a reverse proxy with authentication, or use Tailscale for private network access. CasaOS is designed for local network use. Treat it accordingly.

What happens if CasaOS crashes or is updated?

Your running apps keep running. CasaOS is just the management layer. If the dashboard container restarts, you lose access to the UI temporarily, but Jellyfin, Nextcloud, etc. keep serving. Updates are usually smooth, but always have a plan to revert if something breaks.

Explore CasaOS in our AI Homelab Toolkit.