Homepage

Build a private dashboard of services, bookmarks and application widgets.

Choose your deployment and the way you want to use Selfhost. The instructions below follow that choice.

Deployment Use Selfhost with

Set up Homepage

Build a private dashboard of services, bookmarks and application widgets.

The native deployment creates portable settings, services, bookmarks and widgets YAML files under files/.
Use Native settings to edit the services list as structured JSON. The root list is written as native YAML.
Set HOMEPAGE_ALLOWED_HOSTS to your exact public host and port when adding a domain.

Customize deployment inputs (1)

Local HTTP port port: portDefault: 13000

Save this as inputs.json and adjust the values before initialization.

{
  "port": 13000
}

selfhost app --directory ./homepage init homepage --method native --inputs inputs.json

Initialization writes portable files and does not start the app. Review compose.yaml, the private .env and any files in files/, then start it:

selfhost app --directory ./homepage start

No Selfhost dashboard or background service is needed. You can also start these files directly:

cd homepage
docker compose -f compose.yaml up -d

Review the portable Compose and native configuration before starting.
The default listener is local-only. Add an authenticated HTTPS proxy before exposing private data.
Add service groups, bookmarks and widget definitions in the corresponding native YAML files. Set HOMEPAGE_ALLOWED_HOSTS to your exact domain and port when adding a proxy.
Homepage has no built-in authentication. Use an authenticated reverse proxy. Docker socket access is intentionally absent; use a separately secured socket proxy if needed.

Before configuring integrations

Service entries can contain supported Homepage widget configuration and credentials.
Settings, bookmarks and widgets remain ordinary files that can be edited through project configuration or directly.
No Docker socket is attached by default.
Homepage has no built-in login. Place it behind authentication before exposing it.
Automatic synchronization of Selfhost projects into Homepage is not implemented by this profile.
Only services.yaml has a typed settings profile; the other native files use the regular file editor.

Homepage integrations

Compose service: homepage. These operations use the profile saved when this deployment is created.

Homepage has no built-in authentication. Protect it with an authenticated reverse proxy.
Widget credentials belong in HOMEPAGE_VAR_ environment variables, referenced from YAML. Do not put reusable tokens in public links.

Native settings

Changes use the app’s native YAML file. Unrelated settings are preserved.

Supported fields (1)

Service groups and widgets services: Native Homepage services.yaml array. Includes groups, app links, widgets, descriptions, icons, status checks and per-service options. Keep secrets in HOMEPAGE_VAR_ environment variables. json

Save a JSON map of the field IDs you want to change as changes.json. Replace FIELD_ID with an ID from the supported fields above, and use its declared value type. Review the plan and replace REVIEWED_REVISION with the revision it returns.

{
  "FIELD_ID": "YOUR_VALUE"
}

selfhost app --directory ./homepage config homepage
selfhost app --directory ./homepage plan homepage changes.json
selfhost app --directory ./homepage apply homepage changes.json --revision REVIEWED_REVISION

Saved changes need service recreation to become active. Existing interpolated environment values stay under your control in .env or Compose.

App actions

Validate settings YAML

Parse the native settings YAML without changing it.

selfhost app --directory ./homepage action homepage check-config

App configuration reference

Versions and updates

This deployment uses the following images. Existing projects retain their saved recipe and images. A new catalogue version does not silently update them.

homepage: ghcr.io/gethomepage/homepage:v2.4.0

v2.4.0 ghcr.io/gethomepage/homepage:v2.4.0
Local Docker HTTP startup, native configuration roundtrip, declared read-only actions and container recreation with persistent volumes passed. Native file bytes used a fixture volume because this host did not share bind directories; host file sharing remains unverified. External authentication and version upgrades require separate validation.

Review compatibility and back up app data before an update. Choose an image version and review the change.

Keep control of your setup

Selfhost remains optional. Your app runs using ordinary Compose files, its own settings and persistent data. Keep the Compose project name and volumes to preserve storage. Configuration exports and setting backups do not include application data.

Standalone CLI guide · Backups and removal · Homepage documentation