Skip to content

Contributing to Homelab Infrastructure

Thank you for your interest in contributing to this project. This document provides guidelines for contributing.

Development Environment

Prerequisites

  • Docker installed on your machine
  • SSH key configured for server access
  • Terraform Cloud account (for state management)

Setup

  1. Clone the repository:
git clone https://github.com/chrisleekr/homelab-infrastructure.git
cd homelab-infrastructure
  1. Install dependencies:
task repo:setup
  1. Build and enter the development container:
task docker:build
task docker:exec

Container Workspace

  • Workspace root: /srv
  • SSH keys: ~/.ssh mounted for Git and server access
  • Kubernetes config: container/root/.kube/config

Code Style Guidelines

Terraform

  • Use snake_case for resource names and variables
  • Use .tftpl extension for Terraform templates
  • Pin Helm chart versions in helm_release resources
  • Include type, description, and default for all variables
  • Add validation blocks where appropriate

Ansible

  • Follow role-based structure: tasks/, templates/, defaults/
  • Use .j2 extension for Jinja2 templates
  • Use kebab-case for playbook file names
  • Use snake_case for variable names

Naming Conventions

  • Resources: Use consistent prefixes (e.g., gitlab_, prometheus_, minio_)
  • Domains: Follow pattern service.domain.local

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. Always run before committing:

task precommit

The following hooks are configured:

Hook Purpose
ansible-lint Validate Ansible playbooks and roles
terraform_fmt Format Terraform files
terraform_validate Validate Terraform configuration
terraform_trivy Security scanning for Terraform
terraform_tflint Lint Terraform files
detect-private-key Prevent committing private keys
gitleaks Detect secrets in code
docs-drift Doc coverage, path citations, nav orphans, no em dash in any tracked text file, and no hard-wrapped Markdown paragraph. En dashes, U+2013, are allowed and correct in ranges like 30–60 min

Pull Request Process

  1. Create a feature branch from main:
git checkout -b feature/your-feature-name

  1. Make your changes following the code style guidelines.

  2. Run pre-commit hooks:

task precommit

  1. Test your changes in the container environment.

  2. Commit your changes with a descriptive message:

git commit -m "Add feature: description of changes"

  1. Push to your fork and create a pull request.

  2. Describe your changes in the PR description:

  3. What problem does this solve?
  4. How was it tested?
  5. Any breaking changes?

Adding New Modules

Terraform Module

  1. Create directory: stage2/<module-name>/
  2. Create required files:
  3. main.tf or <service>.tf - Main resources
  4. variables.tf - Module variables (if needed)
  5. provider.tf - Provider configuration (if needed)
  6. templates/ - Template files (if needed)
  7. docs/stage2/<module-name>.md - Module documentation, plus a mkdocs.yml nav entry
  8. Add module to stage2/main.tf with appropriate dependencies
  9. Add enable variable to stage2/variables.tf if optional

Ansible Role

  1. Create directory: stage1/roles/<role-name>/
  2. Create required files:
  3. tasks/main.yml - Task definitions
  4. defaults/main.yml - Default variables
  5. templates/ - Jinja2 templates (if needed)
  6. Add role to appropriate playbook in stage1/

Documentation Style

Line Wrapping

One line per paragraph, list item and quoted line. Never hard wrap prose: a reflowed paragraph arrives in review as a rewritten block and git blame then points at the reflow instead of the edit. Turn on soft wrap in your editor; .editorconfig and .markdownlint.json already disable the line-length rules that push you the other way. The docs-drift hook rejects a wrap.

Mermaid Diagrams

Never set fill: or color: in a classDef. Material renders diagrams into a closed shadow root and paints label text from the active palette, so a hardcoded color: is silently dropped and a hardcoded fill: then clashes with whichever theme the reader is using. Leave both to the theme and mark nodes with the border only:

Class classDef Use for
danger stroke:#e53935,stroke-width:3px Destructive or disruptive: reboots, drains
shared stroke:#b9770e,stroke-width:2px Re-entered from more than one caller
optional stroke-dasharray:5 3 Gated by a flag, or populated at runtime
done stroke:#388e3c,stroke-width:2px Terminal success state
aux stroke:#78909c,stroke-dasharray:2 2 Not a cluster node: localhost, external, artifacts

Most nodes should carry no class at all. Mark only what a reader would otherwise miss.

Security Guidelines

  • Never commit secrets - Store them in Bitwarden Secrets Manager (see Bitwarden secrets); the container injects them at runtime
  • Never commit .env files - The gitignored .env holds only BWS_ACCESS_TOKEN / BWS_PROJECT_ID
  • Use SSH keys - Never commit private keys
  • Pin versions - Always pin tool and chart versions

Questions?

If you have questions about contributing, please open an issue for discussion.