homelab-optimized/docs/admin/DEPLOYMENT_WORKFLOW.md

# 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.*