How to Self-Host Homarr in 2026: Dashboards, Secrets and Live Tiles

A Homarr container can be green while the job users care about is broken. For Homarr, that hidden failure is usually that widgets cannot reach services because they use host-local addresses. This guide treats “create a board, add a service tile, configure one credentialed integration and confirm live status and search after restart” as the acceptance test and builds the deployment backward from that result.

Homarr has a specific role in the stack: searchable dashboard with live tiles for self-hosted services. The production question is therefore not whether port 7575 answers once, but whether state, dependencies and the public address continue to agree after a restart, update and restore.

Define success for Homarr first

Do not let the Homarr image choose production architecture by accident. The image supplies a process on 7575; storage, routing and external requirements still need deliberate lifecycles. The local runtime requirement is persistent app data plus credentials for live integrations. This belongs in the capacity and mount plan, with an owner and a measurable limit.

The deployment is ready for deeper testing when it can create a board, add a service tile, configure one credentialed integration and confirm live status and search after restart. Follow the transaction in logs and watch widget request fan-out, downstream API latency, app-data size and concurrent dashboard clients. Those observations reveal whether the current topology isolates the right component.

Rehearse the risky Homarr change

A green container is necessary but not sufficient. The service-level indicator is successful completion of “create a board, add a service tile, configure one credentialed integration and confirm live status and search after restart”, while the likely pressure signals are widget request fan-out, downstream API latency, app-data size and concurrent dashboard clients.

Change control matters because Homarr schema migrations and encryption-key continuity can affect stored integration credentials. Preserve the old image, test migrations on copied state and document whether rollback is supported after the schema moves. If widgets cannot reach services because they use host-local addresses, diagnose the first boundary that differs from the working environment.

Record a known-good Homarr deployment

Do not make first-user traffic the acceptance test for Homarr. Prepare harmless sample state and run the complete action “create a board, add a service tile, configure one credentialed integration and confirm live status and search after restart”. Note the exact public URL, result, image reference and log interval associated with the run.

Replace the container and repeat without rebuilding data. Next, recover onto an empty host; the recovery condition is that boards, users, integrations and custom assets return and credentialed widgets reconnect. Observe widget request fan-out, downstream API latency, app-data size and concurrent dashboard clients in every pass and define an alert around degradation of the transaction rather than around idle container metrics.

One final check should fail on purpose: submit harmless input near the resource or format limit associated with this boundary: widgets cannot reach services because they use host-local addresses. Verify that the resulting Homarr message identifies the relevant boundary instead of triggering data deletion or an endless restart. Restore the valid condition and confirm the same sample transaction succeeds. Keep this short drill in the release checklist.

Run the first production-shaped instance

The first container should be easy to delete and recreate. Keep data off the writable layer, bind port 7575 only where the proxy can reach it and pass configuration at runtime.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Pin the image after the initial test. Read the earliest startup error rather than the final restart message, verify each mount with docker inspect, and follow logs while you create a board, add a service tile, configure one credentialed integration and confirm live status and search after restart. That sequence distinguishes a bad image command from a dependency or permission problem.

Volumes are only the first recovery layer

For Homarr, redeploy safety starts with boards, users, integrations, secrets and custom assets. Mount /appdata before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. Test the path by replacing the container while harmless sample data exists; this exposes mounts pointed one directory too high or low.

Next test disaster recovery on a blank host. Use an application-consistent database export where necessary and verify that boards, users, integrations and custom assets return and credentialed widgets reconnect. The restore-tested database backup guide provides a stronger target than merely checking that an archive file was created.

Prevent proxy success from masking application failure

The browser, API client and Homarr must agree on one origin. To make that true, set the external HTTPS hostname and allowed origins. Preserve the original host and protocol while keeping port 7575 unavailable as a competing public address.

The site-down troubleshooting guide helps distinguish an unreachable route from a responding application. That distinction matters here: widgets cannot reach services because they use host-local addresses. Only the former is fixed by ingress changes; the latter needs Homarr logs, state or workload inspection.

Close temporary setup access

A secure Homarr deployment starts by removing authority. Avoid changing the encryption key after integration secrets are stored; instead, keep SECRET_ENCRYPTION_KEY stable, protect board editing and scope every widget credential.

Generate SECRET_ENCRYPTION_KEY once, keep it out of Git and preserve it with the recovery manifest because changing it can invalidate encrypted or signed application state. Restrict administrative routes, use private DNS for dependencies and review every bind mount. When logs are shipped centrally, filter secrets and private content before they leave the server.

Move the repeatable infrastructure work to Dockup

For Homarr, Dockup is most useful at the boundary between an image and a durable service. It keeps the route to 7575, TLS, secret values and storage attached across container replacements, whether the compute belongs to Dockup or to your attached server.

Finish with application knowledge: set the external HTTPS hostname and allowed origins; confirm the local requirement — persistent app data plus credentials for live integrations; and run this verification: create a board, add a service tile, configure one credentialed integration and confirm live status and search after restart. Keep the result as a deployment check so the next image update is judged by behavior rather than by container status.

Frequently asked questions

What does Homarr need for a production deployment?

Route the Homarr container on port 7575 through one HTTPS origin. The local runtime requirement is persistent app data plus credentials for live integrations. Do not call Homarr ready until you can create a board, add a service tile, configure one credentialed integration and confirm live status and search after restart.

Which Homarr data belongs in a backup?

Persist /appdata and include boards, users, integrations, secrets and custom assets in the same recovery manifest. A clean Homarr restore passes only when boards, users, integrations and custom assets return and credentialed widgets reconnect.

Does Homarr require HTTPS behind a reverse proxy?

Use HTTPS for the public Homarr origin and keep port 7575 on the internal route. Apply the Homarr setting correctly: set the external HTTPS hostname and allowed origins. For Homarr, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Homarr upgrade be tested?

Restore current Homarr state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because Homarr schema migrations and encryption-key continuity can affect stored integration credentials. Keep the previous Homarr image until its data-migration and rollback boundary are understood.