---
tags:
  - Docker
  - Dashboard
---
# **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**

```yaml
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**

1. **Image**: Pulls the official `ghcr.io/gethomepage/homepage:latest` image for the latest features and updates.
2. **Environment Variables**:
    - `PUID` and `PGID` ensure file permissions align with the host user, avoiding access issues.
3. **Ports**: Maps port `3000` on the container to port `3000` on the host.
4. **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.
5. **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:

```plaintext
/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**

1. **Prepare Your Environment**:
    
    - Install Docker and Docker Compose on your server.
    - Create the directory `/opt/homepage/config` for storing configuration files.
2. **Deploy Homepage**:  
    Save the provided `docker-compose.yml` file and start the service:
    
    ```bash
    docker-compose up -d
    ```
    
3. **Access the Dashboard**:  
    Open a web browser and navigate to:
    
    ```none
    http://<your-server-ip>:3000
    ```
    
4. **Customize Your Dashboard**:
    
    - Edit files such as `services.yaml` or `widgets.yaml` in `/opt/homepage/config`.
    - Restart the container to apply changes:
        
        ```bash
        docker-compose restart homepage
        ```
        
5. **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:

```yaml
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**

1. **Backup Configuration**:  
    Regularly backup `/opt/homepage/config` to prevent data loss:
    
    ```bash
    tar -czvf homepage-config-backup.tar.gz /opt/homepage/config
    ```
    
2. **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.
3. **Update Homepage**:  
    Keep Homepage updated by pulling the latest image and recreating the container:
    
    ```bash
    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.