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, with minimal latency since the page is served almost entirely as static content. It's also the ideal entry point to pilot a growing Docker stack: a single services.yaml file is enough to map dozens of containers.
The concrete benefits of a self-hosted Homepage
- YAML configuration versionable in Git: you rebuild your dashboard identically in a few seconds.
- Native widgets for over 100 services (Docker, Proxmox, Plex, Grafana, AdGuard) 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.
- No telemetry or cloud dependency: your home page stays 100% private.
- Full customization of the theme, wallpapers and search bar.
Technical prerequisites
Homepage is very lightweight. A VPS with 1 vCPU and 1 GB of RAM is largely sufficient, even while running other containers alongside. Plan for around 300 MB of disk space for the image and the configuration. You'll need Docker and Docker Compose (v2) installed, a domain or subdomain pointing to the VPS's IP (e.g. home.mydomain.com), and a reverse proxy such as Traefik or Caddy to handle HTTPS. If you want to make use of the Docker widgets, mount the /var/run/docker.sock socket read-only.
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. The services.yaml, widgets.yaml, settings.yaml and bookmarks.yaml files will be generated on first start in this folder.
Write the docker-compose.yml
In ~/homepage/docker-compose.yml, declare the service with the ghcr.io/gethomepage/homepage:latest image, mount ./config:/app/config and the Docker socket /var/run/docker.sock:/var/run/docker.sock:ro. Add the HOMEPAGE_ALLOWED_HOSTS=home.mydomain.com variable to authorize your domain.
Start the container
Run docker compose up -d then check with docker compose logs -f. Homepage listens by default on port 3000. Test locally with curl http://localhost:3000.
Connect the reverse proxy and SSL
With Caddy, a single line is enough: home.mydomain.com { reverse_proxy localhost:3000 }. Caddy generates and renews the Let's Encrypt certificate automatically. With Traefik, add the traefik.http.routers.homepage.rule=Host(\home.mydomain.com\) labels and the ACME resolver.
Customize services and widgets
Edit config/services.yaml to group your applications, then config/widgets.yaml for the resource bar (CPU, RAM, disk). Reload the page: Homepage rereads the configuration on the fly, without restarting the container.
Enable automatic discovery by adding homepage.group, homepage.name and homepage.href labels directly on your other Docker containers. Homepage detects them via the mounted socket and adds them to the dashboard without touching services.yaml. Coupled with a .env file to store your widget API keys (never in the clear in the versioned YAML), you get a dashboard that updates itself with each new deployment.
