jramos/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(security): implement template-based credential management for sensitive configurations

Browse Source 
Introduce template-based approach to prevent credential exposure in version control.
This security enhancement establishes a standard pattern for managing sensitive data
across the homelab repository.

Changes:
- Create services/homepage/services.yaml.template with env var placeholders
  * Replace 7 hardcoded credentials with ${VARIABLE_NAME} format
  * Add OPNSense, Proxmox, Plex, Radarr, Sonarr, Deluge placeholders
- Create scripts/fix_n8n_db_c_locale.sh.template with env var validation
  * Remove hardcoded PostgreSQL password
  * Add N8N_DB_PASSWORD environment variable requirement
  * Include security reminder to shred script after use
- Update .gitignore with explicit exclusions for sensitive files
  * Add services/homepage/services.yaml exclusion
  * Add scripts/fix_n8n_db_c_locale.sh exclusion
- Create services/homepage/README.md with comprehensive setup guide
  * Document environment variable usage (recommended method)
  * Provide API key acquisition instructions for all services
  * Include troubleshooting and security best practices
- Update scripts/README.md with template pattern documentation
  * Add fix_n8n_db_c_locale.sh template usage instructions
  * Create "Template-Based Script Pattern" section
  * Enhance security guidelines with shred usage

Template Pattern Benefits:
- Repository remains credential-free
- Templates serve as documentation
- Easy to recreate configs on new systems
- Supports CI/CD pipelines with secret injection

Security Validation:
- No API keys in staged files (verified)
- No passwords in staged files (verified)
- .gitignore properly excludes sensitive files
- Templates contain clear usage instructions

Related: n8n troubleshooting (CLAUDE_STATUS.md), Docker Compose migration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jordan Ramos
2025-12-02 19:49:28 -07:00
parent 3eea6b1b4e
commit eec4c4b298
13 changed files with 870 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
services/homepage/README.md Normal file
View File

@@ -0,0 +1,229 @@
# 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)