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

> Install CasaOS on Debian with the official script, keep its dashboard and app ports private with ufw, WireGuard or Caddy HTTPS, and back up /DATA safely.

Difficulty: Intermediate\
Tested on: Debian 12

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.

> **Note**
>
> Project status, October 2026: the latest stable CasaOS release on GitHub is v0.4.15 (December 2024), followed by a v0.4.17-alpha1 pre-release (April 2025). The repository is not archived and still receives commits, and the CasaOS website now points users to ZimaOS, IceWhale's NAS operating system. Check the [releases page](https://github.com/IceWhaleTech/CasaOS/releases) before you store important data in CasaOS.

## Prerequisites

- A server running **Debian 12 (Bookworm)**, the release the CasaOS project lists as tested and recommended. The installer also accepts other Debian and Ubuntu releases, but the project does not list Ubuntu 24.04, Ubuntu 26.04 or Debian 13 as tested. CasaOS supports amd64, arm64 and armv7.
- A non-root user with `sudo` rights and SSH key login. Follow [Secure a new Linux server](/guides/secure-a-new-linux-server) and [Set up SSH keys](/guides/ssh-keys) first.
- Docker Engine from Docker's own repository: follow [How to install Docker Engine on Debian](/guides/install-docker-debian). If Docker is missing, the CasaOS installer falls back to Docker's convenience script, which Docker does not recommend for production. CasaOS needs Docker 20 or newer.
- Optional: a domain or subdomain such as `casa.example.com` with an A/AAAA record pointing at the server, if you want HTTPS through Caddy.

The project does not publish minimum hardware requirements. The installer itself stops on systems with less than 400 MB of RAM and warns when less than 5 GB is free on `/`. The suggested figures below are a conservative starting point, not official numbers:

| Resource | Minimum (official) | Suggested starting point |
|---|---|---|
| RAM | Not published (installer stops below 400 MB) | 2 GB plus what your apps need |
| CPU | Not published | 2 vCPUs |
| Disk | Not published (installer warns below 5 GB free) | 40 GB SSD plus space for your files and apps |

## 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`.

> **Warning**
>
> The installer also installs Samba, which listens on ports 139 and 445. Never open these ports to the internet. ufw blocks them as long as you only allow the ports listed in this guide.

## 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:

```bash
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:

| Method | What you need | Best for |
|---|---|---|
| SSH tunnel | Nothing extra | One administrator, occasional use |
| WireGuard VPN | A WireGuard server on this host | Daily use from several devices |
| Caddy with HTTPS | A domain and Caddy on the server | Browser access from fixed IP addresses |

### 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](/guides/wireguard-vpn-server), then allow the dashboard port only on the VPN interface:

```bash
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:

```bash
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](/guides/caddy-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`):

```caddyfile
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:

```bash
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:

```bash
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:

```caddyfile
media.example.com {
    reverse_proxy 127.0.0.1:8097
}
```

> **Tip**
>
> A few apps use host networking instead of published ports. They listen directly on the server, and ufw filters them like any other host service, so they stay closed until you allow their port.

## 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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.

> **Danger**
>
> Answering yes to the container and AppData questions deletes every app and its data. Make a backup first.

```bash
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](/guides/wireguard-vpn-server).
- Learn more about HTTPS and site blocks in [How to set up Caddy as a reverse proxy](/guides/caddy-reverse-proxy).
- Manage containers in more detail with [Portainer](/guides/install-portainer).
- Compare servers for a self-hosted dashboard on the [CasaOS hosting](/casaos-hosting) page.
- Follow the project on [GitHub](https://github.com/IceWhaleTech/CasaOS).

## Frequently asked questions

### Is CasaOS still maintained?

As of October 2026 the latest stable CasaOS release on GitHub is v0.4.15 from December 2024, followed by a v0.4.17-alpha1 pre-release in April 2025. The repository is not archived, and IceWhale, the company behind it, now presents ZimaOS as the next step for its users. Check the releases page before you rely on CasaOS for important data.

### Does CasaOS support HTTPS?

No. The CasaOS gateway serves the dashboard over plain HTTP because the project is designed for home networks. On an internet server, reach it through an SSH tunnel or WireGuard, or put Caddy in front of it for HTTPS and limit access to your own IP address.

### Why is a CasaOS app reachable from the internet although ufw blocks its port?

App store apps publish their ports on every address, and Docker handles published ports before ufw sees the traffic. This guide sets Docker's default bind address to 127.0.0.1 before you install apps, so new app ports listen on localhost only.

### Can I install CasaOS on Ubuntu 24.04 or Debian 13?

The installer accepts Debian and Ubuntu systems, but the project lists Debian 12 as tested and recommended and only older Ubuntu releases as tested. Other releases may work, but they are untested by the project, so this guide uses Debian 12.

### Which HyperDC servers can run CasaOS?

CasaOS runs on top of the operating system, so you can use a HyperDC Linux VPS, VDS or dedicated server with root access and Debian 12. Size the server for the apps you plan to install, not for CasaOS itself.

---

Source: <https://hyperdc.com/guides/tutorials/install-casaos>\
Updated: 2026-10-09