Homepage seemed like the right tool - customizable, has system monitoring built in, integrates with Docker. Should be simple, right?

It wasn’t.

Why Homepage?

I had Portainer for container management. Plans to add Nginx, Grafana, PostgreSQL. Keeping track of everything across different ports was already getting annoying.

Homepage does what I need: service cards, system stats, Docker integration. Heimdall and Dashy exist, but Homepage’s monitoring capabilities made more sense for infrastructure work.

Initial Deployment

Checked that Portainer was still up, then created the compose file for Homepage.

~/docker/homepage/docker-compose.yml:

version: '3.8'

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

Spun it up:

cd ~/docker/homepage
docker compose up -d

Both containers running

Both containers running. Opened http://192.168.1.19:3000.

Problem 1: No Config Files

Container started fine. Dashboard threw an error.

Missing configuration error

The message was actually helpful - Homepage needs config files to know what to display. It wasn’t broken, just empty.

Building the Config

Homepage needs three YAML files:

• settings.yaml - dashboard settings
• services.yaml - what services to show
• widgets.yaml - system monitoring

Created the directory:

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

Setting up config directory

Settings

settings.yaml - kept it simple:

title: Homelab Dashboard
background: https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=1920

layout:
  Containers:
    style: row
    columns: 3

Services

services.yaml - defined the service cards:

---
- Containers:
    - Portainer:
        icon: portainer.png
        href: http://192.168.1.19:9000
        description: Docker Management UI

    - Homepage:
        icon: homepage.png
        href: http://192.168.1.19:3000
        description: This Dashboard

Widgets

widgets.yaml - system stats:

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

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

System monitoring widgets

Problem 2: Container Didn’t Care

Config files were there. Refreshed the browser. Same error.

The container was already running when I added the files. It needed a kick.

docker compose restart

Restarting to load config

Refreshed again. Different error. Progress, but still broken.

Different error after restart

Debugging YAML

Error pointed to syntax issues. YAML is picky about indentation - spaces vs tabs, nesting, structure.

Went through each file:

• Check indentation (spaces only)
• Verify nesting
• Match documentation examples

Found it - services.yaml had inconsistent spacing. Fixed it, tried again.

docker compose down
docker compose up -d

Multiple restarts during troubleshooting

Multiple restarts. Each time hoping this would be the one.

It Worked

After the third or fourth restart, the dashboard loaded.

Dashboard finally loading

Clean interface, both services showing, system stats visible. Worth the troubleshooting.

Adding the Rest

With Homepage working, I deployed the other services. Nginx Proxy Manager for reverse proxy, Grafana for monitoring, PostgreSQL for database work.

Updated services.yaml after each deployment:

---
- Containers:
    - Portainer:
        icon: portainer.png
        href: http://192.168.1.19:9000
        description: Docker Management UI

    - Homepage:
        icon: homepage.png
        href: http://192.168.1.19:3000
        description: This Dashboard

    - Nginx Proxy Manager:
        icon: nginx-proxy-manager.png
        href: http://192.168.1.19:81
        description: Reverse Proxy & SSL

    - Grafana:
        icon: grafana.png
        href: http://192.168.1.19:3001
        description: Monitoring & Visualization

    - PostgreSQL:
        icon: postgres.png
        description: Database Server
        
- Links:
    - GitHub:
        icon: github.png
        href: https://github.com/artezchapman/docker-homelab
        description: Homelab Code
        
    - Blog:
        icon: web.png
        href: https://blog.artezchapman.com
        description: Technical Blog

Process for each:

1. Deploy container
2. Add to services.yaml
3. Restart Homepage
4. Verify card shows up

All five services on the dashboard

Five services, all managed from one dashboard.

What I Learned

Configuration as code works. Those three YAML files define everything. Version control them, back them up, deploy the exact setup elsewhere in minutes.

Errors teach more than docs. Reading about YAML structure is one thing. Debugging your own syntax errors actually teaches you how it works.

Fast iteration matters. Container restarts take seconds. Made troubleshooting tolerable instead of painful.

System monitoring isn’t optional. CPU, RAM, and disk stats visible on the dashboard made it immediately useful beyond just a link page.

Current Setup

The homelab structure:

~/docker/
├── portainer/
│   └── docker-compose.yml
├── homepage/
│   ├── docker-compose.yml
│   └── config/
│       ├── services.yaml
│       ├── settings.yaml
│       └── widgets.yaml
├── nginx-proxy-manager/
│   └── docker-compose.yml
├── grafana/
│   └── docker-compose.yml
└── postgresql/
    └── docker-compose.yml

Each service isolated. Start, stop, rebuild one without touching the others.

What’s Next

Foundation’s solid. Five services running, accessible through one dashboard.

Next: setting up Nginx for reverse proxy, building Grafana dashboards, connecting PostgreSQL. Making everything work together instead of just existing in parallel.

Real learning happens when things break and you have to fix them. Theory gets you started. Building and troubleshooting actually teaches you how infrastructure works.

Code: github.com/artezchapman/docker-homelab

Part 3 coming soon: Nginx reverse proxy, Grafana monitoring, and making all services work together.

Questions? Find me on LinkedIn or GitHub.

The idea of building my own personal network accessible from anywhere has always intrigued me. Rather than relying on paid services and passing my data through multiple companies, the concept of self-hosting appealed to me. Full control, no subscriptions, and a hands-on way to learn production-grade infrastructure.

This homelab is about understanding how modern infrastructure actually works: containerization, infrastructure as code, monitoring, and security practices that translate to real-world environments.

Hardware: Working With What I Have

My current workstation (Intel i9-10900K, 64GB RAM) has enough resources to run virtual environments for testing infrastructure concepts before committing to dedicated hardware.

Why start with virtualization?

• Test different infrastructure buildouts risk-free
• Snapshots for easy recovery when experiments break
• Can destroy and rebuild quickly to try new approaches
• Simulates real cloud infrastructure
• Easy to scale up to multiple VMs for future Kubernetes clusters

Eventually, I plan to move to dedicated bare metal hardware for 24/7 hosting, but VMs let me validate the architecture first.

VM Specifications:

• Ubuntu Server 24.04 LTS
• 8GB RAM
• 4 CPU cores
• 50GB storage
• Bridged network adapter

Ubuntu Server Setup

I chose Ubuntu Server over Desktop for one simple reason: it’s what’s used in production. No GUI, no unnecessary packages, just a clean server environment I’d manage entirely through SSH.

The installation was straightforward - select language, configure network, partition the disk, create a user account, and enable OpenSSH server during installation.

Once the VM was up, I SSH’d in from my Windows machine using Windows Terminal:

ssh homelab@192.168.1.19

Successful SSH connection to the Ubuntu Server VM

Getting that SSH connection working felt like the first real milestone. This VM was now a proper remote server I could manage from anywhere on my network.

Installing Docker

With the base system ready, it was time to install Docker - the foundation of everything I’d build.

# Update package index
sudo apt update && sudo apt upgrade -y

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

# Add user to docker group (avoid sudo for docker commands)
sudo usermod -aG docker $USER

Updating system packages before Docker installation

After logging out and back in for the group change to take effect, I verified Docker was working:

docker run hello-world

Verifying Docker installation with hello-world container

Seeing that “Hello from Docker!” message confirmed everything was working. Now for Docker Compose:

sudo apt install docker-compose-plugin -y
docker compose version

Installing Docker Compose plugin

Project Structure: Organization Matters

Before deploying anything, I set up a clean directory structure. Each service would get its own folder with a docker-compose.yml file and any necessary configuration.

mkdir -p ~/docker
cd ~/docker

Creating organized directory structure for Docker services

This might seem basic, but organization matters. When this grows to 10+ services, having a clear structure will keep things manageable. Each service is self-contained and easy to understand.

First Container: Portainer

For my first “real” service, I chose Portainer - a web UI for managing Docker containers. It would let me visualize what’s running, check logs, and manage resources without memorizing every Docker CLI command.

I created ~/docker/portainer/docker-compose.yml:

version: '3.8'

services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    ports:
      - "9000:9000"
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/data

Then deployed it:

cd ~/docker/portainer
docker compose up -d

First container successfully deployed

Within seconds, Portainer was running. I opened my browser to http://192.168.1.19:9000 and was greeted with the setup screen. Created an admin account, and I was in.

Portainer web interface managing Docker containers

This was the moment it clicked. I had a real service running in a container, managed by code, accessible via browser. This was actual infrastructure.

What I Learned

Infrastructure as Code is powerful: That docker-compose.yml file is the entire configuration. I can version control it, share it, destroy it, and redeploy it identically in seconds.

Start small, build up: I could have tried to deploy 10 services at once. Instead, I got one working properly, understood it, then moved on. Portainer taught me the workflow I’d use for every service after.

Documentation matters: I took screenshots and notes as I went. Future me (and anyone reading this) would thank past me for that.

What’s Next

Now that I have Docker running and Portainer managing containers, the next step is building out a service dashboard. I want a single Homepage that shows all my services, system stats, and gives me quick access to everything.

After that: Nginx Proxy Manager for reverse proxy, Grafana for monitoring, and PostgreSQL for database work.

Full code for this project: github.com/artezchapman/docker-homelab

Part 2 coming soon: Building a custom Homepage dashboard and troubleshooting configuration issues.

Have questions or suggestions? Find me on LinkedIn or check out the code on GitHub.