Why host Homepage on your VPS
Homepage (gethomepage.dev) is a static dashboard written in Next.js, designed to be the home page of your infrastructure. Unlike SaaS start-page solutions, everything stays under your control: the configuration lives in simple YAML files, the widgets query your own services (Proxmox, qBittorrent, Sonarr, Pi-hole…), and no data transits through an external cloud. Hosting it on a VPS makes it accessible everywhere, from any browser, the page being served almost entirely as static content.
It is also the ideal entry point to pilot a growing Docker stack: a single services.yaml file is enough to map dozens of containers. As your infrastructure grows more complex — multiple applications, multiple subdomains, services across several VPS — Homepage becomes the single cockpit from which you check the status of each one at a glance, without opening five tabs.
The concrete benefits of a self-hosted Homepage
- YAML configuration versionable in Git: rebuild your dashboard identically in seconds after a reinstall.
- Native widgets for over 100 services (Docker, Proxmox, Plex, Grafana, AdGuard, Pi-hole, Portainer…) with real-time stat display.
- Automatic detection of Docker containers via labels, with no manual URL entry.
- Minimal memory footprint: less than 128 MB of RAM, ideal on a small VPS already running other containers.
- No telemetry or cloud dependency: your home page stays 100% private, even during a network outage.
- Full customization of the theme, wallpapers, search bar and service groups.
- Hot reload of configuration: no container restart needed after modifying the YAML files.
Technical prerequisites
Homepage is very lightweight. A VPS with 1 vCPU and 512 MB of RAM is sufficient in practice, even running other containers alongside. Plan for around 300 MB of disk space for the image and the configuration. You will need:
- Docker and Docker Compose v2 installed (check with docker compose version).
- A domain name or subdomain pointing to the public IP of the VPS, for example home.yourdomain.com.
- A reverse proxy — Caddy or Traefik — to handle HTTPS and the Let's Encrypt certificate.
- The Docker socket /var/run/docker.sock mounted read-only if you want to use Docker widgets and automatic discovery.
If you start from a fresh VPS, install Docker following the official documentation, then enable automatic start with systemctl enable --now docker.
Deploy Homepage with Docker in 5 steps
Prepare the directory tree
Connect to your VPS over SSH and create the folders:
mkdir -p ~/homepage/config cd ~/homepageThe files
services.yaml,widgets.yaml,settings.yamlandbookmarks.yamlwill be generated automatically on first start inside thisconfig/folder. You can also create them empty in advance to control their content from the start.Write the docker-compose.yml
Create
~/homepage/docker-compose.ymlwith the following content:services: homepage: image: ghcr.io/gethomepage/homepage:latest container_name: homepage restart: unless-stopped ports: - 127.0.0.1:3000:3000 volumes: - ./config:/app/config - /var/run/docker.sock:/var/run/docker.sock:ro environment: - HOMEPAGE_ALLOWED_HOSTS=home.yourdomain.comNote the
127.0.0.1:3000:3000binding: the port is only accessible from the local loopback, never exposed directly on the public IP. The reverse proxy is the only entry point.Start the container
Start Homepage in the background and check the logs:
docker compose up -d docker compose logs -fHomepage listens on port
3000. Test locally before opening the reverse proxy:curl http://localhost:3000If the response is an HTML document, the container is working.
Connect the reverse proxy and SSL
With Caddy — add to your
Caddyfile:home.yourdomain.com { reverse_proxy localhost:3000 }Caddy generates and renews the Let's Encrypt certificate automatically. Reload:
systemctl reload caddy.With Traefik — add labels to the service in
docker-compose.yml:labels: - traefik.enable=true - traefik.http.routers.homepage.rule=Host(`home.yourdomain.com`) - traefik.http.routers.homepage.entrypoints=websecure - traefik.http.routers.homepage.tls.certresolver=letsencryptIn both cases, verify that your DNS points to the VPS IP before attempting the ACME challenge.
Customize services and widgets
Edit
config/services.yamlto declare your applications in groups:- Tools: - Portainer: href: https://portainer.yourdomain.com description: Container management icon: portainer.pngAdd system resource widgets in
config/widgets.yaml:- resources: cpu: true memory: true disk: /Homepage rereads configuration on the fly: simply reload the page in your browser after each change, no container restart needed.
Configure service widgets
Widgets are the added value of Homepage over a simple list of links. Each widget queries its target service's API and displays real-time metrics directly on the card.
To enable a widget, add a widget block under the service declaration in services.yaml. Example with Portainer:
- Portainer:
href: https://portainer.yourdomain.com
widget:
type: portainer
url: https://portainer.yourdomain.com
env: 1
key: your-api-tokenAPI keys must never be written in plain text in services.yaml if that file is versioned in a public repository. Create a .env file next to docker-compose.yml and reference secrets with the {{PORTAINER_KEY}} notation in the YAML — Homepage resolves these variables at startup.
Other widely used widgets: Proxmox (CPU, RAM, cluster storage), Pi-hole (blocked requests, active clients), Sonarr / Radarr (active downloads), Grafana (embedded panels), Uptime Kuma (status of each monitor). The full list is in the official gethomepage.dev documentation.
Enable automatic discovery by adding homepage.group, homepage.name, homepage.href and homepage.icon labels directly on your other Docker containers. Homepage detects them via the mounted socket and adds them to the dashboard without touching services.yaml. Combining this approach with a .env file to store your widget API keys (never in the clear in the versioned YAML) gives you a dashboard that updates itself with each new deployment: set the labels once, Homepage reads them continuously.
Secure access to your dashboard
A dashboard listing all your services is an attractive target. Two basic measures are needed before exposing Homepage on the internet.
Restrict access by IP or authentication. If Homepage is only for you, the simplest solution is to allow only your IP address in your reverse proxy configuration. With Caddy:
home.yourdomain.com {
@allowed remote_ip 203.0.113.42
handle @allowed {
reverse_proxy localhost:3000
}
respond 403
}If you access the dashboard from multiple networks, prefer HTTP basic authentication or an authentication middleware such as Authelia or Authentik in front of Homepage.
Do not expose the Docker socket in write mode. The /var/run/docker.sock:/var/run/docker.sock:ro read-only mount is sufficient for Homepage. Never grant write access: a compromised container with write access to the socket can create new containers with arbitrary volumes on the host.
Update the image regularly. Use docker compose pull && docker compose up -d to update Homepage whenever a new image is available. You can automate this with Watchtower configured to watch only the homepage container.
Back up and restore your configuration
All Homepage configuration lives in the config/ folder: that is the only directory to back up. No database, no persistent state outside these YAML files.
Version in Git. The most reliable method is to initialize a Git repository in ~/homepage/config/ and commit after each change. If your configuration contains API keys (even via variables), add a .gitignore to exclude the .env file and version only the YAML files.
Incremental backup to object storage. With restic and an S3-compatible bucket (Garage, MinIO, Backblaze B2), schedule a daily backup from a cron job:
restic -r s3:s3.example.com/my-bucket/homepage backup ~/homepage/configRestoration. In case of VPS loss, recreate the container, restore the config/ folder from the backup, and run docker compose up -d. Homepage is operational in under a minute — one of the concrete advantages of a 100% declarative YAML configuration.
Install Homepage via the ServOrbit Marketplace
If you prefer not to configure Docker manually, the ServOrbit Marketplace offers Homepage as a guided installation. A few clicks from your client dashboard provision a VPS with Homepage ready to use: official image, loopback-bound port and HOMEPAGE_ALLOWED_HOSTS pre-configured.
The template also includes Caddy pre-installed with the minimal reverse proxy configuration, so your dashboard is accessible over HTTPS as soon as provisioning completes. You only need to declare your subdomain and customize the YAML files in config/.
Find the full spec sheet, minimum requirements and the install button on the dedicated Marketplace page.
