Posted inUbuntu

Installing Homepage on Ubuntu: The Feather-Light Docker Management Dashboard

Ubuntu tutorial - IT technology blog
Ubuntu tutorial - IT technology blog

The Problem: When 20 VPS Instances Make Your Head Spin

After running a Home Lab for over six months with more than 20 Ubuntu Server VPS instances for clients, I nearly went crazy forgetting IP addresses. As the number of Docker containers skyrocketed to 30-40 (from Portainer and Nginx Proxy Manager to Plex and Grafana…), digging through Note files just to find a URL became a total nightmare.

I tried Heimdall, Dashy, and Organizr. The results weren’t great: some were too heavy (consuming 300-500MB of RAM), some had outdated interfaces, and others required tedious point-and-click configuration. Finally, I settled on Homepage (gethomepage.dev). It is a modern dashboard, configured entirely via YAML files—something we techies always prefer for the ability to copy-paste quickly.

The beauty of Homepage is its deep integration via API with Docker and monitoring tools like Glances. You can monitor server CPU and RAM or see which containers are ‘up’ or ‘down’ right on a single screen without ever opening a Terminal.

Installing Homepage on Ubuntu using Docker Compose

Installing via Docker Compose is the optimal method. This approach allows you to backup or migrate to a new server in just 2 minutes by simply copying the configuration directory.

Step 1: Create a storage space

First, create a directory to house the “soul” of your dashboard. I usually keep it in the home directory for convenience:

mkdir -p ~/homepage/config
cd ~/homepage

Step 2: Draft the Docker Compose file

Use nano to create the service file:

nano docker-compose.yml

The file content is as follows:

version: "3.3"
services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - ./config:/app/config
      - /var/run/docker.sock:/var/run/docker.sock # To allow Homepage to read Docker data
    restart: unless-stopped

A small note: Mounting /var/run/docker.sock helps the dashboard automatically detect the status of other containers on the same server. Don’t forget this line if you want to see the dashboard stats update in real-time.

Step 3: Activate the dashboard

Run the following command to have the system pull the image and start the service:

docker compose up -d

Now, open your browser and access http://Your-IP-Address:3000. A blank interface will appear, waiting for you to populate it with data.

Turning Homepage into your Control Center

All Homepage settings are located in .yaml files. If you don’t see the files yet, create them manually in the config folder.

1. Service Management (services.yaml)

This is where you list the apps you are running. For example, I’ll add Portainer and Pi-hole for monitoring:

- Server Management:
    - Portainer:
        icon: portainer.png
        href: http://192.168.1.10:9000/
        description: Docker Management
        container: homepage

- Network:
    - Pi-hole:
        icon: pi-hole.png
        href: http://192.168.1.10/admin
        widget:
          type: pihole
          url: http://192.168.1.10
          key: YOUR_API_KEY_HERE

The widget section is extremely useful. It fetches data from Pi-hole and displays the number of blocked ads immediately without requiring you to log into that app.

2. Bookmarking frequently used sites (bookmarks.yaml)

Used for external links like GitHub or Google Cloud. The configuration is very simple:

- Tools:
    - Github:
        - abbr: GH
          href: https://github.com/
    - ChatGPT:
        - abbr: AI
          href: https://chat.openai.com/

3. System Health Monitoring (widgets.yaml)

To have the dashboard display CPU, RAM, or Disk usage, use this file:

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

- datetime:
    text_size: xl
    format: { "timeStyle": "short", "dateStyle": "long" }

Real-world Experience and Security

After saving the YAML files, Homepage will automatically detect changes instantly. You don’t need to restart the container. If the interface doesn’t update, use the command docker logs -f homepage to check for syntax errors (usually due to incorrect YAML indentation).

Regarding security, Homepage does not have a password by default. When exposing this dashboard to the Internet via Nginx Proxy Manager, I always take two steps:

  1. Enable Basic Auth on Nginx to lock out strangers.
  2. Use settings.yaml to change the title and switch to your preferred language for a friendlier feel.

In practice, Homepage only “consumes” about 50-80MB of RAM. It saves me at least 15 minutes a day just searching for and typing IPs. This truly is the perfect “landing page” for anyone managing professional Ubuntu or Docker systems.

Share:
Tags: