Homepage on Raspberry Pi

🔍 Key Features

• Customizable Dashboard:
• Built with a clean, modern UI.
• Supports bookmarks, quick search, weather, and widgets.
• Service Integrations:
• Works with Docker, Kubernetes, and APIs from popular apps (Plex, Pi‑hole, qBittorrent, etc.).
• Automatically discovers services via Docker labels.
• Widgets & Modules:
• Real‑time stats for containers, media servers, download clients, and more.
• YAML‑based configuration for fine‑grained control.
• Security:
• All API requests are proxied through Homepage, keeping your API keys hidden.
• Can run as non‑root with PUID/PGID for safer permissions.
• Performance:
• Fully static site generation → instant load times.
• Lightweight container image, easy to deploy and restart.
• Internationalization:
• Translations into multiple languages.
• Community‑driven support and frequent updates.

My Opinion

I usually don't add my 2-cents in these guides but I will here. I don't think Homepage is good for the casual user. Its configuration is manual, I found it pretty difficult to get working correctly and I found the instructions confusing. I still have issues with it (I outline below). If you've got this to work, please Contact Me so I can update my guide.

This guide will get it installed and show you some of the basics for configuring it.

🚀 Docker Installation Steps

1. Update your system
   sudo apt update && sudo apt upgrade -y
2. Install Docker
   

   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh

3. Install Docker Compose
   sudo apt install docker-compose-plugin
4. Add your user to the Docker group
   sudo usermod -aG docker $USER
5. Enable Docker at boot
   sudo systemctl enable docker
6. Reboot
   sudo reboot
7. Test Docker
   docker run hello-world

📁 Setup Homepage

mkdir ~/docker
mkdir ~/docker/homepage

🧾 Docker Compose File

In ~/docker/homepage create docker-compose.yml

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3030:3000
    environment:
      - HOMEPAGE_ALLOWED_HOSTS=*
    volumes:
      - ./config:/app/config
      - ./images:/app/public/images
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

▶️ Start Homepage

From within ~/docker/homepage run:

📜 View Logs

🌐 Access Web Interface

Open your browser and go to "http://<192.168.xx.xx>:3030.

Configuring Homepqage

Here's the official Homepage configuration pqge: https://gethomepage.dev/configs/

Here's my layout at the time of writing this (click to expand):

Note that my "glances on Ugreen NAS" and "glances on Pi" show the exact same statistics. This is when I gave up messing with it.

As I mentioned above, configuration is manual. You have to edits services.yaml in ~/docker/homepage/config. Here's what mine looks like:

- Pi-Hole:
    - Pi-Hole:
        href: http://192.168.xx.zz:8080/admin
        description: Pi-Hole on Ugreen NAS
        icon: pi-hole.png

- Media:
    - Plex:
        href: http://192.168.xx.yy:32400
        description: Plex on Pi
        icon: plex.png
    - Jellyfin:
        href: http://192.168.xx.xx:8096
        description: Jellyfin on Ugreen NAS
        icon: jellyfin.png

- Downloads:
    - qBittorrent:
        href: http://192.168.xx.yy:8888
        description: qBittorrent on Pi
        icon: qbittorrent.png

- Speedtest:
    - Openspeedtest:
        href: http://192.168.xx.yy:3000
        description: Openspeedtest on Pi
        icon: openspeedtest.png
    - Openspeedtest:
        href: http://192.168.xx.xx:44875
        description: Openspeedtest on Ugreen NAS
        icon: openspeedtest.png

- Monitor:
    - beszel:
        href: http://192.168.xx.xx:8095
        description: beszel on Ugreen NAS
        icon: beszel.png
        widget:
          type: beszel
          url: http://192.168.xx.xx:8095
          username: jrmckins@yahoo.com
          password: Mcjim011
          #systemId: systemId # optional
          version: 2 # optional, default is 1
    - glances:
        href: http://192.168.xx.xx:61208
        description: glances on Ugreen NAS
        icon: glances.png
    - CPU Usage:
        widget:
          type: glances
          url: http:///192.168.xx.xx:61208
          version: 4 
          metric: cpu
    - Memory Usage:
        widget:
          type: glances
          url: http:///192.168.xx.xx:61208
          version: 4 
          metric: memory
    
    - glances:
        href: http://192.168.xx.yy:61208
        description: glances on Pi
        icon: glances.png
    - CPU Usage:
        widget:
          type: glances
          url: http:///192.168.xx.yy:61208
          version: 4 
          metric: cpu
    - Memory Usage:
        widget:
          type: glances
          url: http:///192.168.xx.yy:61208
          version: 4 
          metric: memory

I have one glances for my Ugreen NAS and one for my Pi. I'm using two distinct IP address (one for NAS, one for Pi), yet it's showing the statistics from the NAS for both of them. If anyone knows what I'm doing wrong, let me know.

Across the top of the screen, you'll see some widgets. I have some stats from the host I'm running Homepage on, a search bar (it uses duckduckgo be default. You can change it to google by changing duckduckgo to google), and my local weather. To set these up, edit the widgets.yaml file in ~/docker/homepage/config. This is mine:

- resources:
    cpu: true
    memory: true
    disk: /

- search:
    provider: duckduckgo
    target: _blank

- openmeteo:
    label: Waxhaw
    latitude: 34.92
    longitude: 80.74
    cache: 5

You can find more informtion on configuring widgets here: https://gethomepage.dev/configs/info-widgets/.

I tried getting the docker integration working, but ended up giving up. The instructions are here, but nothing I tried would work: https://gethomepage.dev/configs/docker/.