Homepage Service Documentation

Overview

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.

Docker Setup

Docker Compose Configuration

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

Key Configuration Details

Image: Pulls the official ghcr.io/gethomepage/homepage:latest image for the latest features and updates.
Environment Variables:
- PUID and PGID ensure file permissions align with the host user, avoiding access issues.
Ports: Maps port 3000 on the container to port 3000 on the host.
Volumes:
- /opt/homepage/config: Stores configuration files persistently.
- /var/run/docker.sock: Optional for Docker container monitoring.
- /opt/homepage/config/icons: Hosts custom service icons.
Restart Policy: Ensures the service restarts automatically unless manually stopped.

Configuration Directory Structure

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

Deployment Instructions

Prepare Your Environment:
- Install Docker and Docker Compose on your server.
- Create the directory /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:
- Edit files such as services.yaml or widgets.yaml in /opt/homepage/config.
- Restart the container to apply changes:
```
docker-compose restart homepage
```
Add Custom Icons:
Place your icon files in /opt/homepage/config/icons and reference them in services.yaml.

Additional Features

Docker Monitoring

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 Styles and Scripts

Custom CSS: Modify the appearance of the dashboard by editing custom.css.
Custom JavaScript: Add advanced functionality by editing custom.js.

Best Practices

Backup Configuration:
Regularly backup /opt/homepage/config to prevent data loss:
```
tar -czvf homepage-config-backup.tar.gz /opt/homepage/config
```
Security:
- Use a firewall to restrict access to port 3000 if the dashboard is for internal use only.
- Optionally set up a reverse proxy with SSL using Nginx or Traefik.
Update Homepage:
Keep Homepage updated by pulling the latest image and recreating the container:
```
docker-compose pull
docker-compose up -d
```

Why Use Homepage?

Centralized Access: Consolidate all your services in one intuitive dashboard.
Customizable: Fully tailor the dashboard’s layout, services, and appearance to your needs.
Integration Capabilities: Monitor Docker containers, display widgets, and manage bookmarks seamlessly.
Lightweight: Minimal resource consumption ensures smooth performance in home lab environments.

5.0 KiB Raw Blame History Unescape Escape