Install Homarr on CasaOS or ZimaOS With Docker Compose

Bottom Line: Use Homarr's Current Docker Compose Path Rather Than the 2023 BigBear Template

The old CasaOS post was useful when BigBearCasaOS packaged Homarr for one-click installation. Homarr has changed substantially. Its current self-hosting flow uses Compose, persists state under /appdata, requires a SECRET_ENCRYPTION_KEY, and can optionally mount the Docker socket for container integrations.

Start With a Persistent Compose Definition

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /DATA/AppData/homarr:/appdata
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SECRET_ENCRYPTION_KEY=REPLACE_WITH_64_HEX_CHARS

Current Homarr Docker install recommends Compose and documents /appdata.

Generate the Encryption Key Before First Start

openssl rand -hex 32

Homarr uses this secret to protect sensitive integration data. Keep it outside public Compose exports. OpenSSL's secure random generation explains the command.

Mount the Docker Socket Only If Needed

The Docker socket gives powerful control over the host. If Homarr only needs links, bookmarks and external widgets, omit it. Add it only for Docker-aware integrations you intentionally use.

Use the ZimaOS OpenAPI for ZimaOS Data

For storage or system status, use the published ZimaOS OpenAPI instead of scraping dashboard HTML. The ZimaOS app requirements covers resource planning.

Keep Homarr Internal Until Authentication Is Ready

A dashboard can expose internal IPs, ports and infrastructure state. Do not publish it directly without authentication and HTTPS. The ZimaOS HTTPS proxying provides the public-access layer.

Update Homarr as a Container

docker compose down
docker compose pull
docker compose up -d

Persistent /appdata survives recreation. This is why the volume matters more than preserving the old container.

Do Not Put Homarr Config Only Inside the Container

If /appdata is not mapped to persistent host storage, recreating the container can wipe configuration. Back up the host-side Homarr folder. The ZimaOS backup provides the recovery layer.

Use Homarr as a Front Door, Not an Admin Bypass

Homarr can centralize links and read-only status, but every underlying app still has its own authentication. Do not embed admin credentials into public widgets for one-click access.

Build the Dashboard in Layers Instead of Connecting Everything on Day One

Start with plain links to ZimaOS, Plex, Home Assistant and other services. Once the dashboard itself is stable, add one integration at a time. This makes it obvious which integration caused a login loop, slow page load or permission problem. A dashboard with twenty API integrations can look like one broken app even when only one backend is timing out.

Use Internal Hostnames or Stable LAN IPs

Homarr's current container instructions recommend a hostname or direct IP that clients on your network can resolve. If you use a reverse proxy, keep the public hostname consistent and make sure WebSocket/API requests use the same origin. Avoid hard-coding temporary Docker IPs because they can change when containers are recreated.

Back Up More Than the Pretty Layout

Your dashboard can contain encrypted integration credentials, user accounts, icons and service metadata. Preserve the entire persistent /appdata directory together with the encryption key. Test a restore into a disposable Homarr container before relying on the backup.

Be Careful With Automatic Container Updates

A dashboard is often the first place you notice whether the rest of the homelab is healthy. If Homarr updates automatically and breaks at the same time as another service, diagnosis becomes harder. Pin a known-good version or update manually when uptime matters, then roll forward after testing.

Record the exact Homarr image tag after every successful upgrade so rollback remains simple.

FAQ

Is BigBearCasaOS still required for Homarr?

No. Homarr publishes its own current Docker and Compose installation path.

What is SECRET_ENCRYPTION_KEY?

It is a persistent secret Homarr uses to protect sensitive integration data.

Do I need the Docker socket?

Only for Docker-aware integrations or container controls.

Can Homarr show ZimaOS system data?

Potentially through custom integrations using ZimaOS OpenAPI.

How do I update Homarr safely?

Persist /appdata, pull the newer image, recreate the service and verify the dashboard before pruning old images.