How to install CasaOS on a server and keep its dashboard private

CasaOS is an open-source personal cloud dashboard built on Docker. It gives you a web interface with a file manager, system widgets and an app store that installs self-hosted apps such as Jellyfin, Nextcloud or Home Assistant with one click. It comes from IceWhale and was designed for small home devices like single-board computers and mini PCs on a private network.

A rented server is not a home network. The CasaOS dashboard speaks plain HTTP, the first visitor creates the admin account, and app store apps publish their ports on every address of the server. This guide installs CasaOS on Debian 12 with the official installer, which you download and read before running. You then make Docker publish app ports on localhost only, keep the dashboard private with an SSH tunnel, WireGuard or Caddy with HTTPS, and learn how to back up, update and remove CasaOS.

Step 1 — Close the firewall before you install

CasaOS creates its administrator account on the first visit to the dashboard. If the dashboard is reachable from the internet before you open it, anyone who finds it first can claim it. The CasaOS gateway runs as a normal host service, so ufw does filter its port. Allow only SSH and turn the firewall on:

sudo apt update
sudo apt install ufw
sudo ufw default deny incoming
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status verbose

The status output should list only OpenSSH (and its IPv6 twin) as allowed.

Step 2 — Make Docker publish app ports on localhost only

App store apps are Docker Compose projects that publish ports without a host address. The CasaOS Jellyfin app, for example, publishes port 8097 on every address. Docker routes published ports before ufw evaluates its rules, so these ports would be open to the internet even with ufw enabled.

Docker can change the default address it binds published ports to. The ip key covers the default bridge network, and default-network-opts covers the networks that Compose creates for each app. Write both into /etc/docker/daemon.json, together with the log rotation settings from the Docker guide:

sudo tee /etc/docker/daemon.json <<'EOF'
{
  "log-driver": "local",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "ip": "127.0.0.1",
  "default-network-opts": {
    "bridge": {
      "com.docker.network.bridge.host_binding_ipv4": "127.0.0.1"
    }
  }
}
EOF
sudo systemctl restart docker

Test it with a throwaway container on a new network:

docker network create probe-net
docker run -d --rm --name probe --network probe-net -p 9999:80 nginx:stable
sudo ss -tlnp | grep 9999
docker rm -f probe && docker network rm probe-net

The ss line should show 127.0.0.1:9999, not 0.0.0.0:9999. The setting applies to networks created from now on, which is why you set it before installing any app.

Step 3 — Download, review and run the official installer

The official one-line install is curl -fsSL https://get.casaos.io | sudo bash. Download the script first so you can read it:

cd ~
curl -fsSL https://get.casaos.io -o casaos-install.sh
less casaos-install.sh
sudo bash casaos-install.sh

At the time of writing, the script (installer v0.4.16) does the following:

• checks the CPU architecture and distribution, stops below 400 MB of RAM and asks before continuing with less than 5 GB of free disk space;
• installs helper packages: wget, curl, smartmontools, parted, ntfs-3g, net-tools, udevil, samba, cifs-utils, mergerfs and unzip;
• uses your existing Docker (version 20 or newer), or installs Docker with Docker's convenience script if it is missing, then adds a systemd override for Docker's minimum API version;
• installs rclone, then downloads the CasaOS components (gateway, message bus, user service, local storage, app management, UI, CLI and app store) from GitHub releases and copies them into the system;
• installs the casaos-uninstall command and starts the CasaOS services, then prints the dashboard address.

When it finishes, check the version and the services:

casaos -v
systemctl status casaos-gateway casaos --no-pager
sudo ss -tlnp | grep -E "casaos|smbd"

The gateway listens on port 80 if it is free. If port 80 is taken, it picks the first free port from 81 to 89, then 8080 to 8089, and stores its choice in /etc/casaos/gateway.ini.

Step 4 — Create the admin account through an SSH tunnel

Open the dashboard through an encrypted SSH tunnel instead of the public address. Run this on your own computer, replacing the user and IP:

ssh -L 8080:127.0.0.1:80 admin@203.0.113.10

Keep the session open and browse to http://localhost:8080. CasaOS asks you to create an account: choose a username and a long, unique password, ideally from a password manager. After that, the dashboard opens with its widgets, the file manager and the App Store.

Step 5 — Choose how you reach the dashboard

Pick one of three ways to use CasaOS from outside the server:

Option A — SSH tunnel only

Keep using the command from Step 4. Nothing else is exposed, and ufw keeps port 80 closed.

Option B — WireGuard

Set up WireGuard with How to set up a WireGuard VPN server, then allow the dashboard port only on the VPN interface:

sudo ufw allow in on wg0 to any port 80 proto tcp

Connected VPN clients open the server's WireGuard address in the browser, for example http://10.8.0.1. The public interface stays closed.

Option C — Caddy with HTTPS and an IP allowlist

Caddy needs ports 80 and 443, so move the CasaOS gateway to another port first, for example 8088:

sudo sed -i 's/^port=.*/port=8088/' /etc/casaos/gateway.ini
sudo systemctl restart casaos-gateway
sudo ss -tlnp | grep 8088

Install Caddy with How to set up Caddy as a reverse proxy and allow 80/tcp and 443/tcp in ufw. Do not allow port 8088; Caddy reaches it on localhost. Add a site block to /etc/caddy/Caddyfile that only answers your own IP address (here 198.51.100.7):

casa.example.com {
    @denied not remote_ip 198.51.100.7
    abort @denied
    reverse_proxy 127.0.0.1:8088
}

Reload Caddy and test from your computer:

sudo systemctl reload caddy
curl -I https://casa.example.com

From your allowed IP you should get an HTTP 200 response; from any other address the connection is closed. Remember to update the SSH tunnel from Step 4 to port 8088. If your IP changes often, use WireGuard instead of an allowlist.

Step 6 — Install apps and reach them safely

Open App Store in the dashboard and install an app. Thanks to Step 2, its ports now listen on localhost only; check with:

sudo ss -tlnp | grep docker-proxy

Every line should start with 127.0.0.1. App data lives in /DATA/AppData/ followed by the app name, and the app definitions live in /var/lib/casaos/apps.

The app icons in the dashboard link to http://your-server-ip:port, which no longer answers from outside. Reach an app in one of these ways: add its port to your SSH tunnel (for example -L 8097:127.0.0.1:8097), or give it its own Caddy site block, such as this one for the Jellyfin app:

media.example.com {
    reverse_proxy 127.0.0.1:8097
}

Back up and restore

CasaOS keeps its state in three places:

• /DATA: app data (/DATA/AppData), media and the files you manage in the dashboard,
• /var/lib/casaos: app definitions, the app store cache and CasaOS databases,
• /etc/casaos: configuration files such as gateway.ini.

Stop the running containers so databases inside apps are consistent, archive the three folders, then start the same containers again:

sudo mkdir -p /opt/backups
RUNNING=$(docker ps -q)
docker stop $RUNNING
sudo tar czf /opt/backups/casaos-$(date +%F).tar.gz /DATA /var/lib/casaos /etc/casaos
docker start $RUNNING

Copy the archive off the server, for example to another machine with rsync:

rsync -avP admin@203.0.113.10:/opt/backups/ ~/casaos-backups/

To restore, install Docker, the daemon.json from Step 2 and the same CasaOS version on the target server. Then stop CasaOS, unpack the archive and start the services again:

sudo systemctl stop casaos casaos-app-management casaos-local-storage casaos-user-service casaos-message-bus casaos-gateway
sudo tar xzf /opt/backups/casaos-2026-10-09.tar.gz -C /
sudo systemctl start casaos-gateway casaos-message-bus casaos-user-service casaos-local-storage casaos-app-management casaos

If an app does not start on a new server, install it again from the App Store with the same settings; it uses the data it finds under /DATA/AppData.

Update CasaOS

Back up first. You can update from the dashboard under Settings, or from the command line. The project asks you to run the command-line update over SSH or a local console, not from the terminal built into the CasaOS dashboard. Download and review the update script like the installer:

curl -fsSL https://get.casaos.io/update -o casaos-update.sh
less casaos-update.sh
sudo bash casaos-update.sh
casaos -v

CasaOS does not update installed apps automatically. Update each app from the dashboard after reading its release notes. Docker itself is updated through apt, as described in the Docker guide.

Uninstall CasaOS

The installer added an uninstall command. It asks whether to delete all containers, images and the app data in /DATA/AppData; answer n to keep them. It removes /etc/casaos and the CasaOS services, but leaves Docker installed.

sudo casaos-uninstall

Troubleshooting

The dashboard is not on port 80

The gateway found port 80 busy and picked another one. Run grep port /etc/casaos/gateway.ini and sudo ss -tlnp | grep casaos to see the port, then adjust your tunnel or Caddy block, or set the port as shown in Option C.

An app is reachable from the internet although ufw is enabled

The app was installed before you changed daemon.json, or its network existed already. Check with sudo ss -tlnp | grep docker-proxy. Uninstall the app in the dashboard (keep its data), make sure Step 2 is in place, and install it again.

Recommended minimum Docker version

The installer stopped because Docker is older than version 20. Remove the old packages and install Docker from Docker's repository as described in the Docker guide, then run the installer again.

Docker does not start after the install

Check systemctl status docker and journalctl -u docker -n 50. A typo in /etc/docker/daemon.json stops the daemon; validate the file with python3 -m json.tool /etc/docker/daemon.json, fix it, and run sudo systemctl restart docker.

An app icon opens a page that never loads

The app listens on 127.0.0.1 as intended. Open it through your SSH tunnel, WireGuard plus Caddy, or its own Caddy site block as shown in Step 6.

Next steps

• Reach the dashboard from all your devices with a WireGuard VPN server.
• Learn more about HTTPS and site blocks in How to set up Caddy as a reverse proxy.
• Manage containers in more detail with Portainer.
• Compare servers for a self-hosted dashboard on the CasaOS hosting page.
• Follow the project on GitHub.