Homepage is a self-hosted dashboard application designed for organizing and accessing web-based services. With features like bookmarks, service integrations, and Docker monitoring, it serves as a central hub for managing home labs efficiently. This guide details the configuration and setup of Homepage using Docker Compose, ensuring a simple, scalable, and maintainable deployment.
services:
homepage:
image: ghcr.io/gethomepage/homepage:latest
container_name: homepage
environment:
PUID: 1000 # Replace with your user ID
PGID: 1000 # Replace with your group ID
ports:
- "3000:3000" # Map external port as needed
volumes:
- /opt/homepage/config:/app/config
- /var/run/docker.sock:/var/run/docker.sock:ro # Optional for Docker integrations
- /opt/homepage/config/icons:/app/public/icons
restart: unless-stopped
ghcr.io/gethomepage/homepage:latest image for the latest features and updates.PUID and PGID ensure file permissions align with the host user, avoiding access issues.3000 on the container to port 3000 on the host./opt/homepage/config: Stores configuration files persistently./var/run/docker.sock: Optional for Docker container monitoring./opt/homepage/config/icons: Hosts custom service icons.The configuration directory /opt/homepage/config on the host contains all the files needed to customize and manage Homepage:
/opt/homepage/config/
├── bookmarks.yaml # Bookmark definitions for the dashboard
├── config.yml # Main configuration file
├── custom.css # Custom CSS for styling
├── custom.js # Custom JavaScript for advanced tweaks
├── docker.yaml # Docker container monitoring configuration
├── icons/ # Directory for service icons
├── kubernetes.yaml # Kubernetes integration configuration
├── logs/ # Logs for troubleshooting
├── services.yaml # Definitions for services displayed on the dashboard
├── settings.yaml # General settings for Homepage
├── settings.yaml.bck # Backup of settings
├── widgets.yaml # Widget configuration
Prepare Your Environment:
/opt/homepage/config for storing configuration files.Deploy Homepage:
Save the provided docker-compose.yml file and start the service:
docker-compose up -d
Access the Dashboard:
Open a web browser and navigate to:
http://<your-server-ip>:3000
Customize Your Dashboard:
services.yaml or widgets.yaml in /opt/homepage/config.docker-compose restart homepage
Add Custom Icons:
Place your icon files in /opt/homepage/config/icons and reference them in services.yaml.
To enable container monitoring, mount the Docker socket:
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
This integration allows Homepage to display real-time container stats.
custom.css.custom.js.Backup Configuration:
Regularly backup /opt/homepage/config to prevent data loss:
tar -czvf homepage-config-backup.tar.gz /opt/homepage/config
Security:
3000 if the dashboard is for internal use only.Update Homepage:
Keep Homepage updated by pulling the latest image and recreating the container:
docker-compose pull
docker-compose up -d