homelab/CONTRIBUTING.md

Contributing Guide

Thank you for your interest in contributing to this homelab configuration! While this is primarily a personal repository, contributions are welcome.

How to Contribute

Reporting Issues

• Use the bug report template for bugs
• Use the service request template for new services
• Search existing issues before creating a new one
• Provide as much detail as possible

Submitting Changes

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name
   

3. Make your changes following the guidelines below
4. Test your changes locally
5. Commit with clear messages

   git commit -m "feat: add new service"
   

6. Push to your fork

   git push origin feature/your-feature-name
   

7. Open a Pull Request using the PR template

Guidelines

File Naming

• All Docker Compose files must be named compose.yaml (not .yml)
• Use lowercase with hyphens for service directories (e.g., calibre-web)
• Environment files must be named .env

Docker Compose Best Practices

• Use version-pinned images when possible
• Include health checks for databases and critical services
• Use bind mounts for configuration, named volumes for data
• Set proper restart policies (unless-stopped or always)
• Include resource limits for production services

Network Configuration

• All services must use the homelab network (marked as external: true)
• Services with multiple containers should use an internal network
• Example:

  networks:
    homelab:
      external: true
    service_internal:
      name: service_internal
      driver: bridge
  

Traefik Labels

All web services must include:

labels:
  traefik.enable: true
  traefik.http.routers.service.rule: Host(`service.fig.systems`) || Host(`service.edfig.dev`)
  traefik.http.routers.service.entrypoints: websecure
  traefik.http.routers.service.tls.certresolver: letsencrypt
  traefik.http.services.service.loadbalancer.server.port: 8080
  # Optional SSO:
  traefik.http.routers.service.middlewares: tinyauth

Environment Variables

• Use .env files for configuration
• Never commit real passwords
• Use changeme_* prefix for placeholder passwords
• Document all required environment variables
• Include comments explaining non-obvious settings

Documentation

• Add service to README.md service table
• Include deployment instructions
• Document any special configuration
• Add comments to compose files explaining purpose
• Include links to official documentation

Security

• Never commit secrets
• Scan compose files for vulnerabilities
• Use official or well-maintained images
• Enable SSO when appropriate
• Document security considerations

Code Style

YAML Style

• 2-space indentation
• No trailing whitespace
• Use true/false instead of yes/no
• Quote strings with special characters
• Follow yamllint rules in .yamllint.yml

Commit Messages

Follow Conventional Commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• security: Security improvements
• chore: Maintenance tasks

Examples:

feat: add jellyfin media server
fix: correct traefik routing for sonarr
docs: update README with new services
security: update postgres to latest version

Testing

Before submitting a PR:

1. Validate compose files

   docker compose -f compose/path/to/compose.yaml config
   

2. Check YAML syntax

   yamllint compose/
   

3. Test locally

   docker compose up -d
   docker compose logs
   

4. Check for secrets

   git diff --cached | grep -i "password\|secret\|token"
   

5. Run pre-commit hooks (optional)

   pre-commit install
   pre-commit run --all-files
   

Pull Request Process

1. Fill out the PR template completely
2. Ensure all CI checks pass
3. Request review if needed
4. Address review feedback
5. Squash commits if requested
6. Wait for approval and merge

CI/CD Checks

Your PR will be automatically checked for:

• Docker Compose validation
• YAML linting
• Security scanning
• Secret detection
• Documentation completeness
• Traefik configuration
• Network setup
• File naming conventions

Fix any failures before requesting review.

Adding a New Service

1. Choose the correct category:

   • compose/core/ - Infrastructure (Traefik, auth, etc.)
   • compose/media/ - Media-related services
   • compose/services/ - Utility services

2. Create service directory:

   mkdir -p compose/category/service-name
   

3. Create compose.yaml:

   • Include documentation header
   • Add Traefik labels
   • Configure networks
   • Set up volumes
   • Add health checks if applicable

4. Create .env if needed:

   • Use placeholder passwords
   • Document all variables
   • Include comments

5. Update README.md:

   • Add to service table
   • Include URL
   • Document deployment

6. Test deployment:

   cd compose/category/service-name
   docker compose up -d
   docker compose logs -f
   

7. Create PR with detailed description

Project Structure

homelab/
├── .github/
│   ├── workflows/        # CI/CD workflows
│   ├── ISSUE_TEMPLATE/   # Issue templates
│   └── pull_request_template.md
├── compose/
│   ├── core/            # Infrastructure services
│   ├── media/           # Media services
│   └── services/        # Utility services
├── README.md            # Main documentation
├── CONTRIBUTING.md      # This file
├── SECURITY.md          # Security policy
└── .yamllint.yml        # YAML linting config

Getting Help

• Check existing issues and PRs
• Review the README.md
• Examine similar services for examples
• Ask in PR comments

License

By contributing, you agree that your contributions will be licensed under the same terms as the repository.

Code of Conduct

• Be respectful and professional
• Focus on constructive feedback
• Help others learn and improve
• Keep discussions relevant

Questions?

Open an issue with the question label or comment on an existing PR/issue.

Thank you for contributing! 🎉