homelab/services/homepage/README.md

# Homepage Service Configuration

This directory contains the configuration for the [Homepage](https://gethomepage.dev/) 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:
   ```bash
   cd /home/jramos/homelab/services/homepage
   cp .env.example .env  # If example exists, or create manually
   ```

2. **Add your credentials** to the `.env` file:
   ```bash
   # 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:
   ```bash
   # 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**:
   ```bash
   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**:
   ```bash
   cp services.yaml.template services.yaml
   ```

2. **Edit the file** and replace all `${VARIABLE_NAME}` placeholders with actual values:
   ```bash
   nano services.yaml
   ```

3. **Set proper permissions**:
   ```bash
   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:

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

```bash
# 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
   ```bash
   docker restart homepage
   # OR
   docker-compose restart
   ```

2. **Standalone deployment**: Restart the Homepage service
   ```bash
   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](https://gethomepage.dev/)
- [Service Widget Configuration](https://gethomepage.dev/configs/services/)
- [Available Service Integrations](https://gethomepage.dev/widgets/)
- [Custom Widgets](https://gethomepage.dev/configs/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](https://github.com/gethomepage/homepage/issues)
- [Homepage Discord Community](https://discord.gg/homepage)