homelab/templates/service-template/README.md

Service Template

This template provides a starting point for adding new services to your homelab.

Quick Start

1. Copy this template:

   cp -r templates/service-template compose/[category]/[service-name]
   cd compose/[category]/[service-name]
   

2. Choose the correct category:

   • compose/core/ - Infrastructure services (reverse proxy, auth, etc.)
   • compose/media/ - Media-related services (streaming, automation)
   • compose/services/ - Utility services (bookmarks, tasks, etc.)

3. Update compose.yaml:

   • Replace service-name with actual service name
   • Update image: with the correct Docker image
   • Configure environment variables
   • Update port numbers
   • Update Traefik domain (replace service.fig.systems)
   • Add any required volumes or dependencies

4. Create .env file (if needed):

   cp .env.example .env
   # Edit .env and set real values
   

5. Update README.md:

   • Add service to main README.md service table
   • Include service URL and description
   • Document any special configuration

6. Test deployment:

   docker compose config  # Validate syntax
   docker compose up -d   # Deploy
   docker compose logs -f # Check logs
   

Template Features

Included by Default

• ✅ Traefik integration with SSL/TLS
• ✅ Dual domain support (fig.systems + edfig.dev)
• ✅ SSO middleware support (commented)
• ✅ Network configuration (homelab external)
• ✅ Standard environment variables (PUID, PGID, TZ)
• ✅ Restart policy
• ✅ Health check template

Optional Components (Commented)

• Database service (PostgreSQL example)
• Redis cache
• Internal network for multi-container setups
• Port exposure (prefer Traefik)
• Named volumes
• Health checks

Common Patterns

Simple Single-Container Service

services:
  app:
    image: app:latest
    volumes:
      - ./config:/config
    networks:
      - homelab
    labels:
      # Traefik config

Multi-Container with Database

services:
  app:
    image: app:latest
    depends_on:
      - database
    networks:
      - homelab
      - app_internal

  database:
    image: postgres:16-alpine
    networks:
      - app_internal

networks:
  homelab:
    external: true
  app_internal:
    driver: bridge

Service with Media Access

services:
  app:
    image: app:latest
    volumes:
      - ./config:/config
      - /media/movies:/movies:ro
      - /media/books:/books:ro

Checklist

Before submitting a PR with a new service:

• Service name is descriptive and lowercase with hyphens
• Docker image is from a trusted source
• All placeholder passwords use changeme_* format
• Traefik labels are complete (router, entrypoint, tls, rule)
• Both domains configured (fig.systems + edfig.dev)
• SSO middleware decision made (enabled/disabled with comment)
• Networks properly configured (external: true)
• Health check added (if applicable)
• Service added to README.md
• Documentation header in compose.yaml
• .env.example provided (if using env_file)
• Tested locally before committing

Domain Selection

Choose a subdomain that makes sense:

Common Patterns:

• Service name: servicename.fig.systems (most common)
• Function-based: monitor.fig.systems, backup.fig.systems
• Alternative names: flix.fig.systems (Jellyfin), requests.fig.systems (Jellyseerr)

Reserved Domains:

• auth.fig.systems - Tinyauth
• lldap.fig.systems - LLDAP
• traefik.fig.systems - Traefik dashboard
• See README.md for complete list

Network Configuration

Single Container

networks:
  homelab:
    external: true

Multi-Container (with internal network)

networks:
  homelab:
    external: true  # For Traefik access
  service_internal:
    name: service_internal
    driver: bridge  # For inter-container communication

Traefik Network Selection

If using multiple networks, specify which Traefik should use:

labels:
  traefik.docker.network: homelab

Volume Patterns

Configuration Only

volumes:
  - ./config:/config

With Data Storage

volumes:
  - ./config:/config
  - ./data:/data

With Media Access (read-only recommended)

volumes:
  - ./config:/config
  - /media/movies:/movies:ro
  - /media/tv:/tv:ro

With Database

volumes:
  - ./db:/var/lib/postgresql/data

Troubleshooting

Service won't start

# Check logs
docker compose logs app

# Validate compose syntax
docker compose config

# Check network exists
docker network ls | grep homelab

Can't access via domain

# Check Traefik is running
docker ps | grep traefik

# Check Traefik logs
docker logs traefik

# Verify DNS points to server
dig service.fig.systems

# Check SSL certificate
curl -I https://service.fig.systems

Permission errors

# Check PUID/PGID match your user
id

# Fix ownership
sudo chown -R 1000:1000 ./config ./data

Examples

See these services for reference:

• Simple: compose/services/filebrowser/
• With database: compose/services/vikunja/
• Multi-container: compose/media/frontend/immich/
• Media service: compose/media/frontend/jellyfin/

Resources

• Docker Compose Docs
• Traefik Docker Provider
• LinuxServer.io Images
• Awesome Selfhosted