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):
   ```bash
   git clone https://git.vish.gg/Vish/homelab.git
   cd homelab
   ```

2. **Run the setup script**:
   ```bash
   ./scripts/setup-dev-environment.sh
   ```

3. **Configure your environment**:
   ```bash
   cp .env.example .env
   # Edit .env with your actual values
   ```

4. **Test the setup**:
   ```bash
   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
```bash
# Lint all YAML files
yamllint .

# Lint specific directory
yamllint hosts/

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

### Docker Compose Validation
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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`.*