Sanitized mirror from private repository - 2026-03-21 10:17:56 UTC

docs/admin/DEPLOYMENT_WORKFLOW.md

@@ -0,0 +1,298 @@
+# Homelab Deployment Workflow Guide
+
+This guide walks you through deploying services in your homelab using Gitea, Portainer, and the new development tools.
+
+## 🎯 Overview
+
+Your homelab uses a **GitOps workflow** where:
+1. **Gitea** stores your Docker Compose files
+2. **Portainer** automatically deploys from Gitea repositories
+3. **Development tools** ensure quality before deployment
+
+## 📋 Prerequisites
+
+### Required Access
+- [ ] **Gitea access** - Your Git repository at `git.vish.gg`
+- [ ] **Portainer access** - Web UI for container management
+- [ ] **SSH access** - To your homelab servers (optional but recommended)
+
+### Required Tools
+- [ ] **Git client** - For repository operations
+- [ ] **Text editor** - VS Code recommended (supports DevContainer)
+- [ ] **Docker** (optional) - For local testing
+
+## 🚀 Quick Start: Deploy a New Service
+
+### Step 1: Set Up Your Development Environment
+
+#### Option A: Using VS Code DevContainer (Recommended)
+```bash
+# Clone the repository
+git clone https://git.vish.gg/Vish/homelab.git
+cd homelab
+
+# Open in VS Code
+code .
+
+# VS Code will prompt to "Reopen in Container" - click Yes
+# This gives you a pre-configured environment with all tools
+```
+
+#### Option B: Manual Setup
+```bash
+# Clone the repository
+git clone https://git.vish.gg/Vish/homelab.git
+cd homelab
+
+# Install development tools (if needed)
+# Most tools are available via Docker or pre-installed
+
+# Set up Git hooks (optional)
+pre-commit install
+
+# Set up environment
+cp .env.example .env
+# Edit .env with your specific values
+```
+
+### Step 2: Create Your Service Configuration
+
+1. **Choose the right location** for your service:
+   ```
+   hosts/
+   ├── synology/atlantis/     # Main Synology NAS
+   ├── synology/calypso/      # Secondary Synology NAS
+   ├── vms/homelab-vm/        # Primary VM
+   ├── physical/concord-nuc/  # Physical NUC server
+   └── edge/rpi5-vish/        # Raspberry Pi edge device
+   ```
+
+2. **Create your Docker Compose file**:
+   ```bash
+   # Example: Adding a new service to the main NAS
+   touch hosts/synology/atlantis/my-new-service.yml
+   ```
+
+3. **Write your Docker Compose configuration**:
+   ```yaml
+   # hosts/synology/atlantis/my-new-service.yml
+   version: '3.8'
+   
+   services:
+     my-service:
+       image: my-service:latest
+       container_name: my-service
+       restart: unless-stopped
+       ports:
+         - "8080:8080"
+       volumes:
+         - /volume1/docker/my-service:/data
+       environment:
+         - PUID=1000
+         - PGID=1000
+         - TZ=America/New_York
+       networks:
+         - homelab
+   
+   networks:
+     homelab:
+       external: true
+   ```
+
+### Step 3: Validate Your Configuration
+
+The new development tools will automatically check your work:
+
+```bash
+# Manual validation (optional)
+./scripts/validate-compose.sh hosts/synology/atlantis/my-new-service.yml
+
+# Check YAML syntax
+yamllint hosts/synology/atlantis/my-new-service.yml
+
+# The pre-commit hooks will run these automatically when you commit
+```
+
+### Step 4: Commit and Push
+
+```bash
+# Stage your changes
+git add hosts/synology/atlantis/my-new-service.yml
+
+# Commit (pre-commit hooks run automatically)
+git commit -m "feat: Add my-new-service deployment
+
+- Add Docker Compose configuration for my-service
+- Configured for Atlantis NAS deployment
+- Includes proper networking and volume mounts"
+
+# Push to Gitea
+git push origin main
+```
+
+### Step 5: Deploy via Portainer
+
+1. **Access Portainer** (usually at `https://portainer.yourdomain.com`)
+
+2. **Navigate to Stacks**:
+   - Go to "Stacks" in the left sidebar
+   - Click "Add stack"
+
+3. **Configure Git deployment**:
+   - **Name**: `my-new-service`
+   - **Repository URL**: `https://git.vish.gg/Vish/homelab`
+   - **Repository reference**: `refs/heads/main`
+   - **Compose path**: `hosts/synology/atlantis/my-new-service.yml`
+   - **Automatic updates**: Enable if desired
+
+4. **Deploy**:
+   - Click "Deploy the stack"
+   - Monitor the deployment logs
+
+## 🔧 Advanced Workflows
+
+### Local Testing Before Deployment
+
+```bash
+# Test your compose file locally
+cd hosts/synology/atlantis/
+docker compose -f my-new-service.yml config  # Validate syntax
+docker compose -f my-new-service.yml up -d   # Test deployment
+docker compose -f my-new-service.yml down    # Clean up
+```
+
+### Using Environment Variables
+
+1. **Create environment file**:
+   ```bash
+   # hosts/synology/atlantis/my-service.env
+   MYSQL_ROOT_PASSWORD="REDACTED_PASSWORD"
+   MYSQL_DATABASE=myapp
+   MYSQL_USER=myuser
+   MYSQL_PASSWORD="REDACTED_PASSWORD"
+   ```
+
+2. **Reference in compose file**:
+   ```yaml
+   services:
+     my-service:
+       env_file:
+         - my-service.env
+   ```
+
+3. **Add to .gitignore** (for secrets):
+   ```bash
+   echo "hosts/synology/atlantis/my-service.env" >> .gitignore
+   ```
+
+### Multi-Host Deployments
+
+For services that span multiple hosts:
+
+```bash
+# Create configurations for each host
+hosts/synology/atlantis/database.yml      # Database on NAS
+hosts/vms/homelab-vm/app-frontend.yml     # Frontend on VM
+hosts/physical/concord-nuc/app-api.yml    # API on NUC
+```
+
+## 🛠️ Troubleshooting
+
+### Pre-commit Hooks Failing
+
+```bash
+# See what failed
+git commit -m "my changes"  # Will show errors
+
+# Fix issues and try again
+git add .
+git commit -m "my changes"
+
+# Skip hooks if needed (not recommended)
+git commit -m "my changes" --no-verify
+```
+
+### Portainer Deployment Issues
+
+1. **Check Portainer logs**:
+   - Go to Stacks → Your Stack → Logs
+
+2. **Verify file paths**:
+   - Ensure the compose path in Portainer matches your file location
+
+3. **Check Git access**:
+   - Verify Portainer can access your Gitea repository
+
+### Docker Compose Validation Errors
+
+```bash
+# Get detailed error information
+docker compose -f your-file.yml config
+
+# Common issues:
+# - Indentation errors (use spaces, not tabs)
+# - Missing quotes around special characters
+# - Invalid port mappings
+# - Non-existent volume paths
+```
+
+## 📚 Best Practices
+
+### File Organization
+- **Group related services** in the same directory
+- **Use descriptive filenames** (`service-name.yml`)
+- **Include documentation** in comments
+
+### Security
+- **Never commit secrets** to Git
+- **Use environment files** for sensitive data
+- **Set proper file permissions** on secrets
+
+### Networking
+- **Use the `homelab` network** for inter-service communication
+- **Document port mappings** in comments
+- **Avoid port conflicts** across services
+
+### Volumes
+- **Use consistent paths** (`/volume1/docker/service-name`)
+- **Set proper ownership** (PUID/PGID)
+- **Document data locations** for backups
+
+## 🔗 Quick Reference
+
+### Common Commands
+```bash
+# Validate all compose files
+./scripts/validate-compose.sh
+
+# Check specific file
+./scripts/validate-compose.sh hosts/synology/atlantis/service.yml
+
+# Run pre-commit checks manually
+pre-commit run --all-files
+
+# Update pre-commit hooks
+pre-commit autoupdate
+```
+
+### File Locations
+- **Service configs**: `hosts/{host-type}/{host-name}/service.yml`
+- **Documentation**: `docs/`
+- **Scripts**: `scripts/`
+- **Development tools**: `.devcontainer/`, `.pre-commit-config.yaml`, etc.
+
+### Portainer Stack Naming
+- Use descriptive names: `atlantis-media-stack`, `homelab-monitoring`
+- Include host prefix for clarity
+- Keep names consistent with file names
+
+## 🆘 Getting Help
+
+1. **Check existing services** for examples
+2. **Review validation errors** carefully
+3. **Test locally** before pushing
+4. **Use the development environment** for consistent tooling
+
+---
+
+*This workflow ensures reliable, tested deployments while maintaining the flexibility of your GitOps setup.*