homelab-optimized/docs/admin/DEVELOPMENT.md

🛠️ Development Environment Setup

This document describes how to set up a development environment for the Homelab repository with automated validation, linting, and quality checks.

🚀 Quick Start

1. Clone the repository (if not already done):

   git clone https://git.vish.gg/Vish/homelab.git
   cd homelab
   

2. Run the setup script:

   ./scripts/setup-dev-environment.sh
   

3. Configure your environment:

   cp .env.example .env
   # Edit .env with your actual values
   

4. Test the setup:

   yamllint hosts/
   ./scripts/validate-compose.sh
   

📋 What Gets Installed

Core Tools

• yamllint: YAML file validation and formatting
• pre-commit: Git hooks for automated checks
• ansible-lint: Ansible playbook validation
• Docker Compose validation: Syntax checking for service definitions

Pre-commit Hooks

The following checks run automatically before each commit:

• ✅ YAML syntax validation
• ✅ Docker Compose file validation
• ✅ Trailing whitespace removal
• ✅ Large file detection (>10MB)
• ✅ Merge conflict detection
• ✅ Ansible playbook linting

🔧 Manual Commands

YAML Linting

# Lint all YAML files
yamllint .

# Lint specific directory
yamllint hosts/

# Lint specific file
yamllint hosts/atlantis/immich.yml

Docker Compose Validation

# Validate all compose files
./scripts/validate-compose.sh

# Validate specific file
./scripts/validate-compose.sh hosts/atlantis/immich.yml

# Validate multiple files
./scripts/validate-compose.sh hosts/atlantis/*.yml

Pre-commit Checks

# Run all checks on all files
pre-commit run --all-files

# Run checks on staged files only
pre-commit run

# Run specific hook
pre-commit run yamllint

# Skip hooks for a commit (use sparingly)
git commit --no-verify -m "Emergency fix"

🐳 DevContainer Support

For VS Code users, a DevContainer configuration is provided:

1. Install the "Dev Containers" extension in VS Code
2. Open the repository in VS Code
3. Click "Reopen in Container" when prompted
4. The environment will be automatically set up with all tools

DevContainer Features

• Ubuntu 22.04 base image
• Docker-in-Docker support
• Python 3.11 with all dependencies
• Pre-configured VS Code extensions
• Automatic pre-commit hook installation

📁 File Structure

homelab/
├── .devcontainer/          # VS Code DevContainer configuration
├── .pre-commit-config.yaml # Pre-commit hooks configuration
├── .yamllint               # YAML linting rules
├── .env.example           # Environment variables template
├── requirements.txt       # Python dependencies
├── scripts/
│   ├── setup-dev-environment.sh  # Setup script
│   └── validate-compose.sh       # Docker Compose validator
└── DEVELOPMENT.md         # This file

🔒 Security & Best Practices

Environment Variables

• Never commit .env files
• Use .env.example as a template
• Store secrets in your local .env file only

Pre-commit Hooks

• Hooks prevent broken commits from reaching the repository
• They run locally before pushing to Gitea
• Failed hooks will prevent the commit (fix issues first)

Docker Compose Validation

• Validates syntax before deployment
• Checks for common configuration issues
• Warns about potential problems (localhost references, missing restart policies)

🚨 Troubleshooting

Pre-commit Hook Failures

# If hooks fail, fix the issues and try again
git add .
git commit -m "Fix validation issues"

# To see what failed:
pre-commit run --all-files --verbose

Docker Compose Validation Errors

# Test a specific file manually:
docker-compose -f hosts/atlantis/immich.yml config

# Check the validation script output:
./scripts/validate-compose.sh hosts/atlantis/immich.yml

YAML Linting Issues

# See detailed linting output:
yamllint -f parsable hosts/

# Fix common issues:
# - Use 2 spaces for indentation
# - Remove trailing whitespace
# - Use consistent quote styles

Python Dependencies

# If pip install fails, try:
python3 -m pip install --user --upgrade pip
python3 -m pip install --user -r requirements.txt

# For permission issues:
pip install --user -r requirements.txt

🔄 Integration with Existing Workflow

This development setup does not interfere with your existing Portainer GitOps workflow:

• ✅ Portainer continues to poll and deploy as usual
• ✅ All existing services keep running unchanged
• ✅ Pre-commit hooks only add validation, no deployment changes
• ✅ You can disable hooks anytime with pre-commit uninstall

📈 Benefits

Before (Manual Process)

• Manual YAML validation
• Syntax errors discovered after deployment
• Inconsistent formatting
• No automated quality checks

After (Automated Process)

• ✅ Automatic validation before commits
• ✅ Consistent code formatting
• ✅ Early error detection
• ✅ Improved code quality
• ✅ Faster debugging
• ✅ Better collaboration

🆘 Getting Help

If you encounter issues:

1. Check the logs: Most tools provide detailed error messages
2. Run setup again: ./scripts/setup-dev-environment.sh
3. Manual validation: Test individual files with the validation tools
4. Skip hooks temporarily: Use git commit --no-verify for emergencies

🎯 Next Steps

Once the development environment is working:

1. Phase 2: Set up Gitea Actions for CI/CD
2. Phase 3: Add automated deployment validation
3. Phase 4: Implement infrastructure as code with Terraform

---

This development setup is designed to be non-intrusive and can be disabled at any time by running pre-commit uninstall.