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)

# 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

# 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:

   # Example: Adding a new service to the main NAS
   touch hosts/synology/atlantis/my-new-service.yml
   

3. Write your Docker Compose configuration:

   # 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:

# 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

# 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

# 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:

   # 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:

   services:
     my-service:
       env_file:
         - my-service.env
   

3. Add to .gitignore (for secrets):

   echo "hosts/synology/atlantis/my-service.env" >> .gitignore
   

Multi-Host Deployments

For services that span multiple hosts:

# 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

# 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

# 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

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