Homepage self-hosted dashboard showing service tiles, container status and resource widgets
Self-hosting

Homepage Dashboard with Docker: One Start Page for Your Server

Once you run more than a handful of apps on a VPS, a quiet problem creeps in: you forget where things live. Was Uptime Kuma on port 3001 or behind status.yourdomain? Is the file sync app actually running, or did it crash after last night’s update? You end up with a bookmarks folder full of half-remembered IP addresses and a terminal permanently open on docker ps. A self-hosted dashboard fixes this with a single page that links every app, shows whether each container is up, and pulls live numbers from the services themselves. In this guide we build exactly that with Homepage, step by step, on a fresh VPS.

Homepage is an open source project (GPL-3.0 license) documented at gethomepage.dev , with the code on github.com/gethomepage/homepage . It is a fast start page built with Next.js, it integrates with well over a hundred popular self-hosted apps, and, the part we like most, its whole configuration lives in a few plain YAML files. No database, no admin panel to click through, nothing hidden: if you can edit a text file, you can build your dashboard.

What Homepage is and why a dashboard helps

Think of Homepage as the “new tab” page for your server. Every app you run becomes a tile, tiles are arranged in groups (for example “Infrastructure” and “Apps”), and the page loads in a fraction of a second. It is made of three kinds of building blocks:

  • Services: tiles for your apps. Each one has a link, an icon, a short description and, optionally, a status indicator and a widget that shows live data pulled from the app’s API, for example how many monitors are up in Uptime Kuma.
  • Info widgets: the bar at the top of the page, with things like CPU, RAM and disk usage, the date and time, the weather or a search box.
  • Bookmarks: simple lists of links for things you use often but do not host yourself, such as your DNS provider, your hosting client area or documentation.

Homepage also talks to Docker. If you are new to it, Docker is the tool that runs applications in containers: isolated, packaged environments that contain an app and everything it needs, so it behaves the same on any server. Because Homepage can ask Docker which containers exist and what state they are in, each tile can show a small “running” or “exited” badge, and Docker labels can even create tiles automatically.

The configuration format is YAML, a human-friendly text format where structure is expressed through indentation (spaces at the start of a line). That is the only “language” you need for this tutorial, and we explain every file we touch.

What we are going to build

By the end of this guide you will have:

  • Homepage running with Docker Compose, reachable only over HTTPS at an address like https://dash.example.ro, protected by a password.
  • A list of your services, grouped, with icons, descriptions and availability checks.
  • Live container status through a read-only Docker socket proxy (we explain below why we do not hand Homepage the Docker socket directly).
  • A top bar with server resources, date and time, weather and search.
  • A single config folder that holds everything and can be backed up by copying it.

Homepage compared to other dashboards

Homepage is not the only start page out there. Homer is a static page with almost no footprint but no live status. Heimdall and Dashy let you edit tiles from the browser. Homarr offers a drag-and-drop interface but is noticeably heavier. Homepage sits in a sweet spot: modest memory use, deep integrations, and configuration as text files you can keep in Git.

Approximate idle RAM of self-hosted dashboardsHomer~10 MBHeimdall~90 MBHomepage~120 MBDashy~180 MBHomarr~350 MB0100200300400Idle RAM in MB (approximate, single user)Dashboard
Approximate idle memory use measured on a small VPS. Real values vary with the number of widgets and how often they refresh.

Together with the socket proxy (a few MB), Homepage stays comfortably under 150 MB of RAM, so it fits alongside your other apps even on the smallest VPS.

What you need

  • A DreamServer VPS running Debian 13 or Ubuntu 24.04. 1 vCPU and 1 GB of RAM are plenty for Homepage itself.
  • SSH access with a sudo user (a regular user allowed to run administrative commands with sudo).
  • A domain or subdomain you control, for example dash.example.ro, with a DNS A record pointing to your VPS IP address. An A record is simply the entry that tells the internet “this name lives at this IP”.
  • About 30 minutes and a text editor in the terminal (we use nano, which is preinstalled).
  • Optional, but more fun: a few apps already running on the server, so the dashboard has something to show.

A note for LXC customers: Docker runs inside an unprivileged LXC container only if the “nesting” feature is enabled. If Docker refuses to start, contact support to enable it, or use a KVM VPS, where Docker works without any special settings.

How the pieces fit together

Before typing commands, let us look at the path a request takes. Understanding this makes the security choices later obvious.

How a request reaches HomepageYour DreamServer VPSBrowseryou, anywhereUFW firewall80, 443 openCaddyHTTPS + passwordLet's Encrypt TLSHomepage127.0.0.1:3000Socket proxyread-only APIYour appswidget API calls./configYAML filesPort 3000 is never exposed to the internet
Only Caddy faces the internet. Homepage listens on localhost, reads Docker state through a read-only proxy and its settings from the config folder.

Here is what each piece does:

  • The firewall (UFW) decides which network ports are reachable from outside. A port is a numbered door on the server: SSH uses 22, web traffic uses 80 (HTTP) and 443 (HTTPS). We open only those three.
  • Caddy is a reverse proxy: a web server that receives every visitor, handles the HTTPS certificate automatically through Let’s Encrypt, asks for a password, and then forwards the request to the right app on the inside.
  • Homepage listens on port 3000, but only on 127.0.0.1 (localhost), which means nobody on the internet can reach it directly. Only Caddy, running on the same machine, can.
  • The socket proxy is a tiny container that sits between Homepage and Docker and allows only safe, read-only questions such as “which containers are running?”.
  • The config folder holds the YAML files that describe your dashboard. It lives on the VPS disk, so it survives container restarts and updates.

The procedure at a glance

Homepage setup in 8 steps1Prepare VPSDocker, firewall2Compose filefolder + YAML3First startcompose up -d4settings.yamltheme, layout5services.yamllinks, widgets6Live statussocket proxy7Widgetsinfo, bookmarks8HTTPS + authCaddy proxy
Steps 1 to 3 get Homepage running, steps 4 to 7 build the dashboard, step 8 publishes it safely over HTTPS.

Step 1: Prepare the VPS (updates, Docker, firewall)

First, bring the system up to date. This installs security patches before we add anything new:

sudo apt update && sudo apt upgrade -y

On Ubuntu, check whether a reboot is required (for example after a kernel update):

[ -f /var/run/reboot-required ] && echo "Reboot needed" || echo "No reboot needed"

Debian does not create /var/run/reboot-required by default, so if the upgrade installed a new linux-image package, simply reboot with sudo reboot to be safe.

Next, install Docker from Docker’s official repository. The packages shipped by the distribution are often older and do not include the Compose v2 plugin under the same name. The block below works on both Debian and Ubuntu, because it reads the distribution name (ID) and release codename from /etc/os-release:

sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
. /etc/os-release
sudo curl -fsSL "https://download.docker.com/linux/${ID}/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Check that it works:

sudo docker run --rm hello-world
sudo docker compose version

You should see a “Hello from Docker!” message, followed by something like Docker Compose version v2.x.x. In this guide we always prefix Docker commands with sudo. You can add your user to the docker group to skip it, but keep in mind that membership in that group is effectively equivalent to root access.

Now the firewall. On Debian 13, UFW is not installed by default; on Ubuntu 24.04 it is installed but inactive. The same commands work on both:

sudo apt install -y ufw
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

If your SSH server listens on a different port, allow that port before running ufw enable, or you will lock yourself out. One important detail: ports published by Docker bypass UFW rules, because Docker writes its own firewall rules. That is why, in the next step, we publish Homepage only on 127.0.0.1 instead of relying on UFW to hide it.

Step 2: Create the project folder and the Compose file

Docker Compose lets us describe several containers, their settings and how they connect, in one file called compose.yaml. Let us create a project folder with a config subfolder for Homepage’s settings:

mkdir -p ~/homepage/config
cd ~/homepage
id -u && id -g

The last command prints your user ID and group ID, usually 1000 and 1000 on a fresh VPS. Homepage will create its files with these IDs, so you can edit them without sudo. Now create the Compose file:

nano compose.yaml

Paste the following, replacing dash.example.ro with your real subdomain and 1000 with the values you just saw:

services:
  dockerproxy:
    image: tecnativa/docker-socket-proxy:latest
    container_name: dockerproxy
    environment:
      CONTAINERS: "1"   # allow reading the container list and stats
      POST: "0"         # block every write operation (start, stop, delete)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped
    networks:
      - homepage

  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    environment:
      HOMEPAGE_ALLOWED_HOSTS: "dash.example.ro"
      PUID: "1000"
      PGID: "1000"
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./config:/app/config
    depends_on:
      - dockerproxy
    restart: unless-stopped
    networks:
      - homepage

networks:
  homepage:
    name: homepage

Save with Ctrl+O, Enter, and exit with Ctrl+X. What each part means:

  • dockerproxy connects to the Docker socket (/var/run/docker.sock, the “control channel” of Docker) and exposes only the container read endpoints to other containers on the private homepage network. Its port 2375 is never published to the host.
  • HOMEPAGE_ALLOWED_HOSTS is a security check introduced in Homepage v1: the app answers only requests addressed to the host names in this list. localhost:3000 and 127.0.0.1:3000 are always allowed, which is handy for testing.
  • ports "127.0.0.1:3000:3000" means “publish container port 3000 on the host, but only on localhost”.
  • volumes ./config:/app/config is a bind mount: the config folder on the VPS appears inside the container at /app/config, so your YAML files persist outside the container.
  • restart: unless-stopped brings the containers back after a reboot or crash.

About image tags: :latest always pulls the newest release, which is convenient but means an update can surprise you. For a setup you rarely touch, pin a specific release from the Homepage releases page , using a tag in the form vX.Y.Z, and bump it deliberately when you want to upgrade. The socket proxy changes rarely, so :latest is a reasonable tradeoff there, but you can pin it the same way.

Step 3: Start Homepage for the first time

Start both containers in the background (-d means “detached”):

sudo docker compose up -d
sudo docker compose ps

The ps output should list dockerproxy and homepage with the status Up. Look at the logs to confirm Homepage started cleanly:

sudo docker compose logs --tail 30 homepage

You should see a line saying the server is ready on port 3000. Now ask it for a page from the VPS itself:

curl -sI http://127.0.0.1:3000 | head -n 1

Expected output: HTTP/1.1 200 OK. On the first start, Homepage also copies example files into the empty config folder:

ls config

You should see files such as bookmarks.yaml, docker.yaml, services.yaml, settings.yaml, widgets.yaml, plus custom.css and custom.js for advanced styling. These are the only files you will edit from now on.

To see the dashboard in your browser before configuring HTTPS, use an SSH tunnel, which forwards a port from your own computer to the VPS through the encrypted SSH connection. On your computer (not on the VPS), run:

ssh -L 3000:127.0.0.1:3000 your-user@your-vps-ip

While that session stays open, browse to http://localhost:3000. You will see Homepage with its example content. Leave the tunnel open, because we will refresh this page after each of the next steps.

Step 4: Set the look and layout in settings.yaml

settings.yaml controls the global appearance: page title, theme, colors and how groups are laid out. Open it:

nano ~/homepage/config/settings.yaml

Replace its content with:

title: My Server
theme: dark
color: slate
headerStyle: boxed
statusStyle: dot
hideVersion: true
layout:
  Infrastructure:
    style: row
    columns: 3
  Apps:
    style: row
    columns: 3

theme can be dark or light, color picks the palette (for example slate, zinc, blue, emerald), statusStyle: dot shows availability as a small colored dot instead of a text badge, and the layout section tells Homepage to display the “Infrastructure” and “Apps” groups as rows with three tiles each. The group names must match exactly the names you use in services.yaml in the next step, including capitalization.

Refresh the browser: most changes appear immediately. If something does not update, restart the container with sudo docker compose restart homepage.

Remember the YAML golden rule: indentation uses spaces, never tabs, and every nested level is indented consistently (two spaces in our examples).

Step 5: Add your services in services.yaml

Now the heart of the dashboard. Open services.yaml:

nano ~/homepage/config/services.yaml

Here is an example with two groups. Adapt names and addresses to the apps you actually run:

- Infrastructure:
    - Uptime Kuma:
        icon: uptime-kuma.png
        href: https://status.example.ro
        description: Uptime monitoring and status page
        siteMonitor: https://status.example.ro
        widget:
          type: uptimekuma
          url: https://status.example.ro
          slug: main

    - Webmail:
        icon: mdi-email-outline
        href: https://mail.example.ro
        description: Company mailboxes
        siteMonitor: https://mail.example.ro

- Apps:
    - Nextcloud:
        icon: nextcloud.png
        href: https://cloud.example.ro
        description: Files, calendar and contacts
        siteMonitor: https://cloud.example.ro

    - Website:
        icon: mdi-web
        href: https://www.example.ro
        description: Public company site
        siteMonitor: https://www.example.ro

The structure is: a list of groups, each group contains a list of services, each service has its settings. The fields:

  • icon: an icon name. Names ending in .png come from Homepage’s built-in icon library of popular apps; names starting with mdi- use Material Design icons, useful for generic things.
  • href: where the tile takes you when clicked.
  • siteMonitor: Homepage sends a request to this URL periodically and shows a green or red dot plus the response time. It works for any web address, even on other servers.
  • widget: live data from the app’s API. The uptimekuma widget needs the URL of your Uptime Kuma instance and the slug of one of its status pages (the last part of the status page URL), and then shows how many monitors are up or down.

Widgets are fetched by the Homepage server, not by your browser, so API keys for apps that need them stay on the VPS. If an app runs in Docker on the same server, you can also connect its container to the homepage network (declared as external: true in that app’s Compose file) and use its internal address, such as http://uptime-kuma:3001, instead of the public URL.

Save and refresh the browser. Your tiles should appear in two groups, with green dots for the sites that respond.

Step 6: Show live container status with docker.yaml

So far Homepage checks URLs. Now we let it see the containers themselves, through the read-only proxy we started in Step 2. Open docker.yaml:

nano ~/homepage/config/docker.yaml

Replace its content with:

my-docker:
  host: dockerproxy
  port: 2375

my-docker is just a name we choose for this Docker server, and dockerproxy is the container name of the proxy, which Docker resolves automatically on the shared homepage network. Now link a tile to a container by adding two lines to the service in services.yaml:

    - Uptime Kuma:
        icon: uptime-kuma.png
        href: https://status.example.ro
        description: Uptime monitoring and status page
        server: my-docker
        container: uptime-kuma

container must match the name shown in the NAMES column of sudo docker ps. After a restart (sudo docker compose restart homepage), the tile shows the container state, and clicking the status reveals CPU and memory usage of that container. To display these numbers on every tile all the time, add showStats: true to settings.yaml.

There is an even lazier option: Docker labels. Labels are small key/value tags attached to a container. If you add Homepage labels to another app’s Compose file, Homepage discovers it automatically through the proxy, no editing of services.yaml needed:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma
    labels:
      - homepage.group=Infrastructure
      - homepage.name=Uptime Kuma
      - homepage.icon=uptime-kuma.png
      - homepage.href=https://status.example.ro
      - homepage.description=Uptime monitoring

Pick one method per service: if you define the same app both in services.yaml and through labels, it shows up twice.

Step 7: Add info widgets and bookmarks

The info bar at the top is configured in widgets.yaml:

nano ~/homepage/config/widgets.yaml
- resources:
    cpu: true
    memory: true
    disk: /

- datetime:
    text_size: xl
    format:
      timeStyle: short
      dateStyle: short

- openmeteo:
    label: Bucharest
    latitude: 44.43
    longitude: 26.10
    timezone: Europe/Bucharest
    units: metric

- search:
    provider: duckduckgo
    target: _blank

resources shows CPU, RAM and disk usage. Inside a Docker container on a KVM VPS, these values reflect the whole server, and disk: / reports the filesystem that holds Docker’s data, which is usually your root disk. On an LXC VPS, you see the limits of your container. openmeteo uses a free weather service that needs no API key, and search adds a search box that opens results in a new tab.

Bookmarks go in bookmarks.yaml:

nano ~/homepage/config/bookmarks.yaml
- Admin:
    - DreamServer:
        - abbr: DS
          href: https://dreamserver.ro
    - Docker docs:
        - abbr: DK
          href: https://docs.docker.com

- Docs:
    - Homepage docs:
        - abbr: HP
          href: https://gethomepage.dev

The format looks a little odd at first: each bookmark is a list with a single entry, which holds its settings. abbr is a two-letter abbreviation displayed when there is no icon. Refresh, and your dashboard is complete. A nice bonus: just start typing on the page and Homepage’s quick launch searches through your services, so you can open any app with a few keystrokes.

Step 8: Publish it with HTTPS and a password

Homepage has no login of its own. Anyone who can reach it sees all your services, and widgets can reveal internal details. So we put it behind Caddy, which adds HTTPS and a password in a few lines.

First, make sure your subdomain points to the VPS:

getent hosts dash.example.ro

The output must show your VPS IP. If it does not, fix the DNS A record and wait a few minutes. Then install Caddy, which is available in the official repositories of both Debian 13 and Ubuntu 24.04 (on Ubuntu it comes from the universe component, enabled by default on server images):

sudo apt install -y caddy
caddy hash-password

caddy hash-password asks for a password twice and prints a hash starting with $2a$14$. A hash is a one-way scrambled version of the password, so the real password never sits in a config file. Copy it, then edit the Caddy configuration:

sudo nano /etc/caddy/Caddyfile

Replace the whole file with:

dash.example.ro {
	basicauth {
		admin $2a$14$PASTE_YOUR_HASH_HERE
	}
	reverse_proxy 127.0.0.1:3000
}

admin is the username you will type in the browser. We use the basicauth directive because it works on the Caddy version shipped by both distributions; newer Caddy releases call it basic_auth and still accept the old name with a warning. Validate and reload:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -sI https://dash.example.ro | head -n 1

Expected output: HTTP/2 401. That “401 Unauthorized” is good news: it means HTTPS works, the certificate was issued, and a password is required. Open https://dash.example.ro in your browser, log in, and enjoy your dashboard. You can now close the SSH tunnel from Step 3.

Troubleshooting and common mistakes

  • “Host validation failed” in the browser: the address you used is not listed in HOMEPAGE_ALLOWED_HOSTS. Add it (several hosts are comma-separated, without spaces) and run sudo docker compose up -d to apply the change. Setting the value to * disables the check, which we do not recommend.
  • An error page after editing YAML: almost always indentation, a tab character or a missing colon. Run sudo docker compose logs --tail 50 homepage; the log names the file and line. Revert your last change if in doubt.
  • Container status shows “not found” or “unknown”: the container value does not match docker ps, the server value does not match the name in docker.yaml, or the proxy is not running. Check with sudo docker compose ps.
  • A widget shows “API Error”: wrong URL, wrong slug or key, or Homepage cannot reach the address from inside its container. Try the public HTTPS URL first, then switch to internal addresses once it works.
  • Caddy cannot obtain a certificate: port 80 or 443 is blocked, the DNS record points elsewhere, or another web server (Apache, nginx) already uses those ports. Read sudo journalctl -u caddy --no-pager -n 50.
  • Permission denied when editing config files: the PUID/PGID values do not match your user. Fix them in compose.yaml and run sudo chown -R $USER:$USER ~/homepage/config.
  • Port 3000 already in use: another app uses it. Change only the left side, for example "127.0.0.1:3010:3000", and point Caddy to 127.0.0.1:3010.
  • Docker does not start on an LXC VPS: nesting is disabled for your container. Ask support to enable it, or use a KVM VPS.

Security notes

  • Never skip the password. Homepage is designed as a private start page. Besides Caddy’s basic auth, a VPN is an even stronger option if only you and your team use the dashboard.
  • The Docker socket is root access. Whoever can talk to it freely can start a privileged container and take over the server. Mounting it with :ro does not change that, which is why we use the proxy with POST=0 and never publish its port.
  • Keep Homepage on localhost. Because Docker bypasses UFW, a mapping like "3000:3000" would expose the dashboard to the internet without HTTPS or a password. Always keep the 127.0.0.1: prefix.
  • Keep secrets out of YAML. Widgets that need API keys can read them from environment variables whose names start with HOMEPAGE_VAR_. Put them in a .env file next to compose.yaml, protect it with chmod 600 .env, add env_file: .env under the homepage service, and reference the value in YAML like this:
        widget:
          type: portainer
          url: https://portainer.example.ro
          env: 1
          key: "{{HOMEPAGE_VAR_PORTAINER_KEY}}"
  • Use read-only API keys wherever an app offers them: a dashboard only needs to read.

Keeping Homepage updated and backed up

Updating is two commands, run from ~/homepage:

sudo docker compose pull
sudo docker compose up -d

If you pinned a version, change the tag in compose.yaml first. Read the release notes before major upgrades, because configuration options occasionally change. As for backups, everything that matters is in the project folder:

tar czf ~/homepage-backup-$(date +%F).tar.gz -C ~ homepage

Copy that archive off the server from time to time. Since the configuration is plain text, it also fits perfectly in a private Git repository, so every change to your dashboard is versioned.

So, is Homepage worth it?

If you run more than three or four services, yes. In half an hour you get one page that answers “where is that app?” and “is it running?” at a glance, with live numbers from your apps, and a configuration made of a few readable text files that you can back up, version and copy to the next server. It costs around 120 MB of RAM and no ongoing effort beyond the occasional update.

You can deploy everything in this guide on a VPS from our Romanian data center in minutes. If you would rather have someone else set up Docker, the reverse proxy, HTTPS and the dashboard for you, our server administration team can build and maintain the whole stack.

FAQ

Does Homepage have a login or user accounts?

No. Homepage has no built-in authentication, by design. Protect it with a reverse proxy that requires a password, as in Step 8, or make it reachable only through a VPN.

Can I edit the dashboard from the browser?

No, Homepage is configured only through YAML files. This is deliberate: text files are easy to back up, compare and keep in Git. Most changes show up after a simple browser refresh.

Can Homepage show services running on other servers?

Yes. siteMonitor works with any URL, and docker.yaml can list several Docker hosts, each with its own socket proxy. Expose a remote proxy only over a private network or VPN, never directly on the internet.

Will it run on the smallest VPS?

Yes. Homepage and the socket proxy together use roughly 120 to 150 MB of RAM and almost no CPU when idle, leaving room for the apps the dashboard links to.

Does it work in an LXC container?

It does, as long as Docker itself works, which in an unprivileged LXC container requires nesting to be enabled. On a KVM VPS there are no such restrictions.

Trusted By & Member Of

We are proud members of leading internet infrastructure organizations.

RIPE NCC MANRS PeeringDB RoTLD DSIX SBIX 4IXP LOCIX Euro-IX RIPE NCC MANRS PeeringDB RoTLD DSIX SBIX 4IXP LOCIX Euro-IX