homelab/services/homepage/README.md

Homepage Service Configuration

This directory contains the configuration for the Homepage dashboard service - a modern, fully static, fast, secure fully self-hosted application dashboard with integrations for over 100 services.

Security Notice

⚠️ IMPORTANT: The services.yaml file contains sensitive API keys, tokens, and passwords. It is excluded from git via .gitignore to prevent credential exposure.

Setup Instructions

Option 1: Using Environment Variables (Recommended)

This is the most secure method as it keeps credentials separate from configuration files.

1. Create a .env file in this directory:

   cd /home/jramos/homelab/services/homepage
   cp .env.example .env  # If example exists, or create manually
   

2. Add your credentials to the .env file:

   # OPNSense
   OPNSENSE_API_USERNAME=your_opnsense_api_username
   OPNSENSE_API_PASSWORD=your_opnsense_api_password
   
   # Proxmox
   PROXMOX_HOMERAMOSLAB_API_TOKEN=your_proxmox_token_1
   PROXMOX_PVE_API_TOKEN=your_proxmox_token_2
   
   # Media Services
   PLEX_API_KEY=your_plex_api_key
   RADARR_API_KEY=your_radarr_api_key
   SONARR_API_KEY=your_sonarr_api_key
   DELUGE_WEBUI_PASSWORD=your_deluge_password
   

3. Create the actual configuration from the template:

   # Using envsubst (if available)
   envsubst < services.yaml.template > services.yaml
   
   # OR manually copy and edit
   cp services.yaml.template services.yaml
   nano services.yaml  # Replace ${VARIABLE_NAME} with actual values
   

4. Set proper permissions:

   chmod 600 services.yaml  # Owner read/write only
   chmod 600 .env           # Owner read/write only
   

Option 2: Manual Configuration

If you prefer to manage credentials directly in the file:

1. Copy the template:

   cp services.yaml.template services.yaml
   

2. Edit the file and replace all ${VARIABLE_NAME} placeholders with actual values:

   nano services.yaml
   

3. Set proper permissions:

   chmod 600 services.yaml  # Owner read/write only
   

Configuration Files

Tracked in Git (Templates & Non-Sensitive)

• services.yaml.template - Template with environment variable placeholders
• bookmarks.yaml - Browser bookmark links (no sensitive data)
• docker.yaml - Docker integration configuration
• settings.yaml - General settings (may contain some preferences)
• widgets.yaml - Dashboard widgets configuration
• kubernetes.yaml - Kubernetes integration (if used)
• custom.css - Custom styling
• custom.js - Custom JavaScript

Excluded from Git (Sensitive)

• services.yaml - Contains API keys and passwords (excluded via .gitignore)
• .env - Contains environment variables with credentials (excluded via .gitignore)

Obtaining API Keys and Tokens

OPNSense API Credentials

1. Log into OPNSense web UI (https://192.168.50.1/)
2. Navigate to System → Access → Users
3. Select your user or create a dedicated API user
4. Scroll to "API keys" section
5. Click "+" to generate a new API key
6. Copy the Key (username) and Secret (password)

Proxmox API Tokens

1. Log into Proxmox web UI (https://192.168.50.230:8006 or :240)
2. Navigate to Datacenter → Permissions → API Tokens
3. Click "Add" to create a new token
4. User: api@pam, Token ID: homepage
5. Uncheck "Privilege Separation" for full access
6. Copy the generated token (format: PVEAPIToken=api@pam!homepage=uuid-format-token)
7. Use only the UUID portion in the configuration

Plex API Key

1. While playing any media in Plex Web App
2. Click the settings icon → "Get Info" → "View XML"
3. In the URL, look for X-Plex-Token= parameter
4. Copy the token value after the equals sign

Radarr/Sonarr API Keys

1. Log into Radarr/Sonarr web UI
2. Navigate to Settings → General
3. Scroll to "Security" section
4. Copy the API Key

Deluge Web UI Password

This is the password you set when first accessing the Deluge Web UI at http://192.168.50.231:8112

Default is often deluge but should be changed for security.

Docker Compose Integration

If running Homepage in Docker, mount this directory as a volume:

services:
  homepage:
    image: ghcr.io/gethomepage/homepage:latest
    container_name: homepage
    ports:
      - 3000:3000
    volumes:
      - /home/jramos/homelab/services/homepage:/app/config
      - /var/run/docker.sock:/var/run/docker.sock:ro  # For Docker widget
    environment:
      - PUID=1000
      - PGID=1000
    restart: unless-stopped

Troubleshooting

Service Widgets Not Loading

1. Check API credentials: Ensure all API keys/tokens are correct
2. Verify network connectivity: Can Homepage reach the service URLs?
3. Review permissions: API tokens need appropriate permissions
4. Check service status: Is the target service actually running?
5. Enable debug logging: Add LOG_LEVEL=debug to docker-compose environment

Configuration Syntax Errors

1. Validate YAML: Use a YAML validator (yamllint, online validators)
2. Check indentation: YAML is sensitive to spaces (use 2-space indentation)
3. Review logs: docker logs homepage or check homepage logs

Permission Denied Errors

# Fix file permissions
chmod 600 services.yaml
chown $(whoami):$(whoami) services.yaml

Security Best Practices

1. Never commit services.yaml - It's already in .gitignore, keep it that way
2. Use dedicated API users - Don't use admin accounts for integrations
3. Rotate credentials regularly - Change API keys/tokens periodically
4. Limit token permissions - Grant only necessary permissions to API tokens
5. Use HTTPS - Access Homepage only over HTTPS in production
6. Restrict access - Use firewall rules or reverse proxy authentication
7. Back up securely - If backing up configs, encrypt the backup

Updating Configuration

After making changes to services.yaml:

1. Docker deployment: Restart the container

   docker restart homepage
   # OR
   docker-compose restart
   

2. Standalone deployment: Restart the Homepage service

   systemctl restart homepage
   

3. Verify changes: Check the Homepage UI to ensure widgets load correctly

Template Maintenance

When adding new services or widgets:

1. Update the template (services.yaml.template) with placeholders
2. Document the new environment variables in this README
3. Update your local services.yaml with actual values
4. Commit the template to git (not the actual config)

Additional Resources

• Homepage Documentation
• Service Widget Configuration
• Available Service Integrations
• Custom Widgets

Support

For issues specific to this homelab configuration:

• Check the main repository documentation
• Review CLAUDE_STATUS.md for recent changes
• Consult the services/README.md for Docker Compose context

For general Homepage issues:

• Homepage GitHub Issues
• Homepage Discord Community