Homepage

Self-hosted start page / dashboard using Homepage via Docker Compose.

---

Repository Contents

File	Description
docker-compose.yaml	Homepage service definition

Configuration files live outside this repo at /etc/homepage/ on the host.

---

Stack

• Homepage - ghcr.io/gethomepage/homepage:latest
• Docker socket - mounted for live container status widgets
• SMB share - /smb mounted into the container for any assets served from network storage

---

Prerequisites

• Docker + Docker Compose installed
• /etc/homepage/ directory created on the host with your config files in place
• /etc/homepage/images/ directory created for custom images/icons
• /etc/homepage/.env file created (see below)

---

Setup

1. Create the config directory

mkdir -p /etc/homepage/images

2. Create the .env file

Homepage reads environment variables from /etc/homepage/.env. At minimum create an empty file so the container starts:

touch /etc/homepage/.env

API keys for service widgets go here. Example:

HOMEPAGE_VAR_SONARR_KEY=your_sonarr_api_key
HOMEPAGE_VAR_RADARR_KEY=your_radarr_api_key
HOMEPAGE_VAR_TAUTULLI_KEY=your_tautulli_api_key

Variables prefixed with HOMEPAGE_VAR_ are available in your services.yaml as {{HOMEPAGE_VAR_SONARR_KEY}}.

3. Populate config files

Homepage is configured entirely through YAML files in /etc/homepage/:

File	Purpose
settings.yaml	Title, theme, color scheme, layout
services.yaml	Service tiles and widgets
bookmarks.yaml	Bookmark groups and links
widgets.yaml	Top-bar info widgets (search, date, resources)
docker.yaml	Docker socket integration config
custom.css	Optional style overrides
custom.js	Optional JS overrides

See the Homepage docs for full reference.

4. Start the stack

docker compose up -d

Homepage will be available at http://<host>:3000.

---

Ports

Port (Host)	Port (Container)	Purpose
3000	3000	Homepage web UI

---

Allowed Hosts

The HOMEPAGE_ALLOWED_HOSTS environment variable restricts which hostnames/IPs can serve the dashboard. Currently set to:

10.10.14.199:3000 (host IP)
home.wittenberger.us
home.wittenberger.local

Add or remove entries as needed when accessing from additional addresses.

---

Volumes

Host Path	Container Path	Purpose
/etc/homepage	/app/config	All YAML config files and .env
/etc/homepage/images	/app/public/images	Custom images and icons
/var/run/docker.sock	/var/run/docker.sock	Docker integration (container status)
/smb	/smb	SMB share mount for network assets

---

Docker Integration

The Docker socket mount enables Homepage to display live container status on service tiles. Configure which containers to show in /etc/homepage/docker.yaml and reference them in services.yaml with a docker widget block.

The Docker socket grants full Docker API access to the container. If this is a concern, consider fronting it with Docker Socket Proxy to restrict permissions.

---

Updating

docker compose pull
docker compose up -d

Config files in /etc/homepage/ are unaffected by updates.