Homarr

Homarr is a dashboard whose tiles show live state rather than only links — it talks to the services behind them through their APIs. One container with its own SQLite database.

Last run on a host 8 Nov 2026

Pinned at v2.12.0 (released 6 Nov 2026) · the newest upstream release

In the upstream images: 0 CRITICAL · 2 HIGH with a published fix — per image

To try it: Docker, nothing else. See Try it locally.

To deploy it behind the proxy: Traefik running and a domain.

Try it locally

On your own machine, with no proxy, domain or certificate. From apps/homarr/:

cp .env.local.example .env.local

# The secrets ship empty; generate the ones this stack needs
echo "HOMARR_SECRET_ENCRYPTION_KEY=$(openssl rand -hex 32)" >> .env.local

docker compose -f docker-compose.local.yml --env-file .env.local up -d

Then open http://localhost:7575. Stop it again with the same command and down.

Installation

From apps/homarr/:

1. Copy the environment file and set APP_TRAEFIK_HOST and TZ:

   cp .env.example .env

2. Generate the encryption key and put it into .env as HOMARR_SECRET_ENCRYPTION_KEY. It encrypts the API tokens Homarr stores for the services it queries:

   openssl rand -hex 32

3. Create the data directory:

   mkdir -p volumes/appdata

4. Start it:

   docker compose up -d

5. Open https://<APP_TRAEFIK_HOST> — a setup wizard runs on the first visit.

Verify

docker compose ps                       # one service, healthy
curl -sSI https://<APP_TRAEFIK_HOST>/   # 307 to /init until the setup wizard is done, then 200

Then add one integration and confirm its tile shows live data. That is the check that covers the encryption key; a dashboard renders fine without it working.

Going further

Live container status

Homarr can show container state and offer start and stop buttons, which needs access to the Docker daemon. A direct socket mount gives the container full control of Docker — root on the host in practice.

Route it through a filtering socket proxy instead, exposing only the endpoints it needs. Dockhand shows the same pattern.

Who can reach it

The stack ships access-vpn. A dashboard with working integrations holds API tokens for everything it displays, which makes it worth more than the tiles suggest.

What it sends outward

Homarr reports weekly to a PostHog instance at hog.homarr.dev, keyed on an ID minted on first run and stored in this stack’s database. It also checks GitHub for a new version at startup.

Turn the telemetry off after first login: Manage → Settings → Analytics, switch off general. It is a database setting, so it cannot be pre-set here.

NO_EXTERNAL_CONNECTION=true stops both calls, but it also stops the icon repository refreshing, which is most of what Homarr is for. The UI switch is the narrower instrument.

Backup

Database	SQLite inside volumes/appdata — no server, no dump hook
State	volumes/appdata — boards, integrations, users, encrypted credentials
Also needed	the encryption key, wherever .env is kept
Quiescing	Required. Stop the container or snapshot the filesystem rather than copying a live SQLite file.

For borgmatic this stack is source_directories only, with quiescing.

The key is not in the data directory. It comes from the environment, so the two have to be treated as one restore unit — the data alone is not enough.

Updates

1. Read the release notes.

2. Back up volumes/appdata with the container stopped, and the key with it.

3. Raise APP_TAG in .env, then:

   docker compose pull && docker compose up -d

4. Open a board with an integration on it. A migration that touched the encrypted columns shows up there.

Troubleshooting

Every integration stopped authenticating. The encryption key changed or is missing. Put the original back and restart.

Container state does not appear. Homarr has no route to the Docker daemon. See above before mounting the socket directly.

Repository files

• apps/homarr/README.md — setup, security model, the Docker options
• apps/homarr/UPSTREAM.md — source and upgrade checklist

Official sources

• Homarr documentation