migrate

2026-07-20 09:23:17 -04:00
parent c1315882da
commit 72272e4006
3179 changed files with 562960 additions and 14 deletions
@@ -0,0 +1,150 @@
+# **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.