150 lines
5.0 KiB
Markdown
150 lines
5.0 KiB
Markdown
# **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. |