homelab-optimized/docs/advanced/customization.md

🎨 Customization Guide

Overview

This guide covers how to customize and extend the homelab configuration to fit your specific needs.

---

🎯 Customization Areas

1. Theme & Branding

Heimdall/Homer Dashboard

# homer/config.yml
title: "My Homelab"
subtitle: "Self-hosted services"
logo: "assets/logo.png"

colors:
  light:
    highlight-primary: "#3367d6"
    highlight-secondary: "#4285f4"
  dark:
    highlight-primary: "#3367d6"
    highlight-secondary: "#4285f4"

Grafana Theme

# grafana.ini
[users]
default_theme = dark

[panels]
disable_sanitize_html = true

2. Service Configuration

Environment Variables

# docker-compose.yml
services:
  myservice:
    environment:
      # Override default settings
      - APP_NAME=My Custom Name
      - TIMEZONE=America/Los_Angeles
      - LANGUAGE=en_US

Custom Domains

# In Nginx Proxy Manager:
# Add custom domain for any service
# yourservice.yourdomain.com -> container:port

3. Notification Customization

ntfy Topics

# Customize alert channels
alerts:
  critical: homelab-critical    # High priority
  warnings: homelab-warnings    # Normal
  info: homelab-info           # Low priority

Alert Templates

# alertmanager/templates/custom.tmpl
{{ define "custom.title" }}
[{{ .Status | toUpper }}] {{ .CommonLabels.alertname }}
{{ end }}

{{ define "custom.text" }}
{{ range .Alerts }}
*Alert:* {{ .Labels.alertname }}
*Instance:* {{ .Labels.instance }}
*Description:* {{ .Annotations.description }}
{{ end }}
{{ end }}

---

📁 Adding New Services

Template docker-compose.yml

# templates/new-service.yaml
version: "3.8"

services:
  servicename:
    image: image:tag
    container_name: servicename
    restart: unless-stopped
    environment:
      - TZ=America/Los_Angeles
      - PUID=1000
      - PGID=1000
    volumes:
      - ./config:/config
      - ./data:/data
    ports:
      - "8080:8080"
    networks:
      - proxy
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

networks:
  proxy:
    external: true

Adding to Monitoring

# prometheus/prometheus.yml
scrape_configs:
  - job_name: 'new-service'
    static_configs:
      - targets: ['servicename:metrics_port']

Adding to Uptime Kuma

1. Open Uptime Kuma dashboard
2. Add New Monitor
3. Configure HTTP/TCP check
4. Add to relevant status page

---

🔧 Advanced Customization

Custom Docker Networks

# Create isolated networks for service groups
networks:
  media:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16
  
  monitoring:
    driver: bridge
    ipam:
      config:
        - subnet: 172.21.0.0/16

Reverse Proxy Custom Headers

# In NPM Advanced config
proxy_set_header X-Custom-Header "value";
proxy_hide_header X-Powered-By;

# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;

Custom Health Checks

services:
  myservice:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

---

📚 Further Reading

• Integrations Guide
• Scaling Guide
• Ansible Automation