How to Self-Host Homepage in 2026: Allowed Hosts, Widgets and Config

There are two versions of “running Homepage”: a container exists, or the service completes its real job. Only the second matters. Here the proof is to load services and bookmarks, call several live widgets, test search and restart after editing a YAML configuration file.

Homepage serves this purpose: start page with live widgets for self-hosted services. The deployment has to preserve the pieces behind that behavior; a port, a volume and a certificate are inputs, not the result.

Choose the smallest viable Homepage topology

A useful Homepage diagram shows the public route, private port 3000, state boundary and every supporting requirement. Mark which arrows carry credentials and which are ordinary user traffic. The external requirement for Homepage is read-only configuration plus credentials for optional service widgets. Test outbound DNS, TLS and provider behavior without publishing another inbound service.

Prove the diagram with one real action: load services and bookmarks, call several live widgets, test search and restart after editing a YAML configuration file. The likely pressure comes from widget fan-out, slow downstream APIs, DNS resolution and the refresh rate of the browser dashboard; monitor that path rather than treating all HTTP requests as equal.

Upgrade Homepage without guessing

The first useful operational metric for Homepage is whether it can load services and bookmarks, call several live widgets, test search and restart after editing a YAML configuration file. Pair that with saturation signals for widget fan-out, slow downstream APIs, DNS resolution and the refresh rate of the browser dashboard. A process-only probe should not call expensive dependencies or restart the container because an upstream is briefly unavailable.

Treat upgrades as data changes because configuration keys and widget integrations can change, so validate YAML and provider behavior before an image update. Pin versions, rehearse on restored state and keep the previous image available until a rollback remains valid. When the host is rejected or YAML indentation prevents config from loading, preserve logs from before the restart; they usually contain the causal message.

A production acceptance run for Homepage

Before real users arrive, make a release worksheet for Homepage. It must name the pinned image, port 3000, canonical origin, persistent paths and the owner of read-only configuration plus credentials for optional service widgets. Attach the expected result of this transaction: load services and bookmarks, call several live widgets, test search and restart after editing a YAML configuration file.

Use the worksheet after a normal replacement and after a clean restore. Recovery is accepted only if services, bookmarks, widgets and custom assets return and all critical widgets handle downstream failures visibly. Also collect a short resource trace covering widget fan-out, slow downstream APIs, DNS resolution and the refresh rate of the browser dashboard; keep it beside the release so future capacity changes are compared with the same workload.

Include one controlled failure: temporarily deny the test path used by read-only configuration plus credentials for optional service widgets. Confirm Homepage reports the problem at the correct boundary, put the valid condition back and rerun the transaction. This checks error visibility, not merely success, and prevents a healthy-looking interface from concealing a broken worker, callback or database connection.

Make Homepage startup reproducible

Use the container as a replaceable runtime, not as the location of truth.

docker run -d \
  --name homepage \
  --restart unless-stopped \
  -p 127.0.0.1:3000:3000 \
  -v homepage-data:/app/config \
  -e HOMEPAGE_ALLOWED_HOSTS=home.example.com \
  ghcr.io/gethomepage/homepage:latest

Allow and verify the outbound or client-side path required for read-only configuration plus credentials for optional service widgets. Inspect the container user, writable paths and bound listener before exposing it. Run the complete action — load services and bookmarks, call several live widgets, test search and restart after editing a YAML configuration file — and save the exact image reference that produced the result.

Separate replaceable containers from lasting data

The durable recovery set is configuration files, bookmarks, services and custom assets. Mount /app/config before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. A volume protects data from container replacement, but not from host loss, accidental deletion or application-level corruption.

Take backups that understand the data source: use logical dumps for live databases when required and copy files only from a consistent state. Keep one encrypted copy away from the Homepage host. The acceptance criterion for a restore is specific — services, bookmarks, widgets and custom assets return and all critical widgets handle downstream failures visibly. The restore-tested backup guide explains why job success alone is insufficient.

Domains, proxy headers and port 3000

The browser, API client and Homepage must agree on one origin. To make that true, set allowed hosts for the exact domain and proxy hostname. Preserve the original host and protocol while keeping port 3000 unavailable as a competing public address.

The site-down troubleshooting guide helps distinguish an unreachable route from a responding application. That distinction matters here: the host is rejected or YAML indentation prevents config from loading. Only the former is fixed by ingress changes; the latter needs Homepage logs, state or workload inspection.

Security decisions specific to Homepage

Do not inherit security assumptions from a local tutorial. Homepage's specific concern is committing widget API keys to a public repository. Production should therefore set allowed hosts precisely and keep widget API keys in environment or secret-backed config rather than a public repository.

HOMEPAGE_ALLOWED_HOSTS controls behavior rather than confidentiality; validate its type and value, and store genuine Homepage credentials separately. Scope filesystem and network access, protect setup endpoints and define upload, request or execution limits around widget fan-out, slow downstream APIs, DNS resolution and the refresh rate of the browser dashboard.

Where Dockup removes work for Homepage

For Homepage, Dockup is most useful at the boundary between an image and a durable service. It keeps the route to 3000, 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 allowed hosts for the exact domain and proxy hostname; allow and verify read-only configuration plus credentials for optional service widgets; and run this verification: load services and bookmarks, call several live widgets, test search and restart after editing a YAML configuration file. 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 Homepage need for a production deployment?

Route the Homepage container on port 3000 through one HTTPS origin. The external delivery requirement is read-only configuration plus credentials for optional service widgets. Do not call Homepage ready until you can load services and bookmarks, call several live widgets, test search and restart after editing a YAML configuration file.

Which Homepage data belongs in a backup?

Persist /app/config and include configuration files, bookmarks, services and custom assets in the same recovery manifest. A clean Homepage restore passes only when services, bookmarks, widgets and custom assets return and all critical widgets handle downstream failures visibly.

Does Homepage require HTTPS behind a reverse proxy?

Use HTTPS for the public Homepage origin and keep port 3000 on the internal route. Apply the Homepage setting correctly: set allowed hosts for the exact domain and proxy hostname. For Homepage, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Homepage upgrade be tested?

Restore current Homepage state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because configuration keys and widget integrations can change, so validate YAML and provider behavior before an image update. Keep the previous Homepage image until its data-migration and rollback boundary are understood.