3.5 KiB
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 -
/smbmounted 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/.envfile 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.