Homepage Docker Compose: Private Access, Host Checks, and Safe Widgets

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      HOMEPAGE_ALLOWED_HOSTS: localhost:3000,127.0.0.1:3000
    volumes:
      - ./config:/app/config
    restart: unless-stopped

How should links and widgets be configured?

Make the browser link work first, then test any server-side widget separately. A successful click does not prove that the Homepage container can reach the API used by a widget.

For a first entry, save this in config/services.yaml:

- Resources:
    - OpenAlt:
        href: https://openreplace.com/self-hosted
        description: Find self-hosted software and deployment tradeoffs

The bookmarks documentation offers an even simpler bookmarks.yaml option when all you need is navigation. Choose the simplest form that communicates the destination clearly. A dashboard with a few dependable links is more useful than one full of broken status indicators.

For live integrations, the browser and container may use different addresses. Docker's Compose networking documentation explains service-name discovery on shared networks. Inside Homepage, localhost means that container, not a different application or your laptop.

Add one widget at a time. Verify its endpoint, credentials, permissions and displayed fields before moving on. Keep API credentials out of publicly shared configuration examples. If an integration supports narrowly scoped credentials, grant only the operations it needs.

Does Homepage need the Docker socket?

No. Ordinary links and many service integrations work without direct access to the Docker daemon. Leave the socket disconnected until a concrete feature requires it.

Homepage's Docker integration guide describes a restricted socket proxy and shows POST=0 to deny write requests. This is a separate control from mounting a socket with a read-only filesystem flag; the latter does not define which API requests may travel over the socket.

Before adding a proxy, identify the exact information you want: container status, a service health check, or application-specific data. These are different questions. A running container can still serve an error page, and a healthy website does not require access to its container daemon.

Keep the proxy on a private network and enable only the endpoints the integration needs. Document who can reach that network. If understanding these permissions feels disproportionate to a small status badge, omit the badge. The Portainer guide explains the similar responsibility attached to managing Docker through another web interface.

How do you protect remote access?

Choose a private VPN or an authenticated HTTPS entry point, then verify access with a signed-out browser. Do this before connecting widgets that reveal personal or operational information.

Current Homepage security documentation describes password or OIDC authentication from version 2.0. It requires a signing secret of at least 32 characters and warns that password attempts are not rate-limited by the application. Follow the documentation for your installed version rather than mixing newer authentication settings into an older image.

For an Internet-facing route, configure TLS, authentication and appropriate rate limiting at the access layer. Verify that the container's direct port cannot bypass that layer. The Caddy Compose guide covers the proxy foundation; a working certificate alone is not the entire access policy.

Test from a device outside the trusted network. Check both the initial page and widget responses. Finally, revoke a test credential and confirm that access stops. Write the recovery procedure somewhere reachable without the dashboard itself.

How do you back up and update the dashboard?

Back up the configuration, deployment definition and necessary secrets through your normal protected backup process. Restore them into a private test instance before relying on a rebuild during an outage.

Docker's volume documentation distinguishes persistent storage from a container's writable layer. In this guide the configuration uses a host bind mount, so explicitly include that host directory in your backup selection.

Before updating, keep a working configuration copy and record the current image identity. After updating, check navigation, authentication, host validation and each credentialed widget. If a widget breaks, isolate that integration before rolling back unrelated services.

A useful acceptance record is short: date, image, backup location, tested client, and any disabled integration. Keep it with the operating notes. Another person should be able to restore the dashboard without reconstructing every decision from memory.

FAQ

Why does Homepage say the host is not allowed?

The incoming hostname or port does not match the configured allowlist. Check the log and add the intended host precisely rather than disabling validation.

Must I mount the Docker socket?

No. Start without it. Add a restricted integration only when container information provides a clear benefit.

Why does a link work while its widget fails?

The browser opens the link, while the widget may call its API from the container. Check that second network route and its credentials.

Can I move Homepage to another server?

Yes, by preserving configuration and necessary secrets, then checking permissions, host settings and integration addresses on the new host before switching users over.