Sanitized mirror from private repository - 2026-03-20 08:50:12 UTC

docs/admin/DEVELOPMENT.md

@@ -0,0 +1,222 @@
+# 🛠️ 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`.*