homelab-agents/HOW-TO-GUIDE.md

# Gitea How-To Guide

Quick reference guide for using Gitea at http://100.120.125.113:3000 to manage your homelab projects.

## Table of Contents
- [Getting Started](#getting-started)
- [Terminology](#terminology)
- [Cloning Repositories](#cloning-repositories)
- [Making Changes](#making-changes)
- [Pushing Changes](#pushing-changes)
- [Common Workflows](#common-workflows)
- [Troubleshooting](#troubleshooting)

---

## Getting Started

### About Your Gitea Server

**Note:** Access via Pangolin Tunnel at https://git.pdmarf.co.uk if outside the local network.

- **Server URL: http://100.120.125.113:3000 (or https://git.pdmarf.co.uk via Pangolin)
- **User**: pdm
- **Available Repositories**:
  - `homelab-agents` - Shared AI agent prompts (pull-only on VPS)
  - `vps-system-apps` - VPS system configuration (push for backup)
  - Additional project repositories as needed

---

## Terminology

### Workstation
Your **main development machine** where you do most of your work. This could be:
- Your laptop (MacBook, Windows laptop, Linux laptop)
- Your desktop computer
- Any machine you consider your primary development environment

**Not** a VPS - it's a machine you have physical access to or directly control.

### VPS
A **Virtual Private Server** - a remote machine hosted in the cloud or on another system. Examples:
- Your system-apps VPS at your hosting provider
- Remote servers you manage
- Machines you SSH into rather than use directly

### Repository
A project folder tracked by git with version history. Each repository can be:
- `homelab-agents` - The shared agents repository
- `vps-system-apps` - Your VPS configuration repository
- Any other project you create

---

## Cloning Repositories

Cloning creates a local copy of a repository on your workstation or VPS.

### Clone homelab-agents (Shared Prompts)

Use this to get the latest AI agent prompts on your VPS:

```bash
git clone http://100.120.125.113:3000/pdm/homelab-agents.git ~/.homelab-agents
```

This creates a `~/.homelab-agents` directory with all shared agent definitions and templates.

**Use Cases:**
- Getting agent prompts on a new VPS
- Keeping agents synchronized across systems
- Read-only reference for development

### Clone vps-system-apps (Project Configuration)

Use this to get your VPS configuration repository:

```bash
git clone http://100.120.125.113:3000/pdm/vps-system-apps.git ~/projects/system-apps
```

This creates a `~/projects/system-apps` directory with Docker, scripts, and documentation.

**Use Cases:**
- Setting up a new VPS with existing configuration
- Cloning on your workstation for editing
- Working on system configuration with version history

### Clone Any Other Project Repository

For future projects, use the same pattern:

```bash
git clone http://100.120.125.113:3000/pdm/[project-name].git ~/projects/[project-name]
```

---

## Making Changes

### Checking Repository Status

See what files have changed:

```bash
cd ~/projects/system-apps
git status
```

Output shows:
- Modified files (red) - existing files you changed
- Untracked files (red) - new files not yet in git
- Staged files (green) - files ready to commit

### Viewing Specific Changes

See exactly what changed in a file:

```bash
git diff docker-compose/docker-compose.yml
```

Or see all changes:

```bash
git diff
```

### Creating a Local Branch (Optional)

For experimental work, create a separate branch:

```bash
git checkout -b feature/new-monitoring-stack
# ... make your changes ...
git add .
git commit -m "Add Prometheus monitoring stack"
```

To switch back to main branch:

```bash
git checkout main
```

---

## Pushing Changes

### Basic Push Workflow

After making changes, follow these three steps:

#### Step 1: Stage Your Changes

Add all modified files to staging:

```bash
cd ~/projects/system-apps
git add -A
```

Or add specific files:

```bash
git add docker-compose/docker-compose.yml
git add scripts/deploy.sh
```

#### Step 2: Commit Your Changes

Create a commit with a descriptive message:

```bash
git commit -m "Add health checks to Docker services"
```

**Good commit message practices:**
- Start with action verb: "Add", "Fix", "Update", "Refactor"
- Be specific: what changed and why
- Keep it concise (under 72 characters for first line)

**Examples:**
```bash
git commit -m "Add Prometheus scrape config for Docker metrics"
git commit -m "Fix disk space alert threshold in monitoring"
git commit -m "Update deployment documentation with new workflow"
git commit -m "Refactor docker-compose.yml for better organization"
```

#### Step 3: Push to Gitea

Send your commits to the Gitea server:

```bash
git push origin main
```

**Success looks like:**
```
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 4 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 456 bytes, done.
Total 3 (delta 1), reused 0 (delta 0)
To http://100.120.125.113:3000/pdm/vps-system-apps.git
   abc1234..def5678  main -> main
```

---

## Common Workflows

### Workflow 1: Edit on Your Workstation, Push to Gitea

**Workstation** = Your main development machine (laptop, desktop, etc.)

```bash
# Step 1: On your workstation, clone the repository
# (e.g., your laptop or desktop computer)
git clone http://100.120.125.113:3000/pdm/vps-system-apps.git ~/projects/system-apps

# Step 2: Edit files on your workstation using vim, VS Code, or any editor
cd ~/projects/system-apps
vim docker-compose/docker-compose.yml
vim scripts/deploy.sh

# Step 3: Check what you changed
git status

# Step 4: Stage and commit
git add -A
git commit -m "Update Docker services with new health checks"

# Step 5: Push to Gitea
git push origin main

# Now your changes are backed up on Gitea and can be deployed to your VPS
```

**When to use this workflow:**
- Editing configuration files on your computer
- Writing scripts and documentation
- Testing changes before deploying to VPS

### Workflow 2: Update Agents on VPS

```bash
# On your VPS (remote server)
cd ~/.homelab-agents

# Get latest agents from Gitea
git pull origin main

# Now use the agents in your work
cat agents/sysadmin-session-closer.md
```

### Workflow 3: Work on VPS, Backup to Gitea

```bash
# On your VPS (remote server)
cd ~/projects/system-apps

# Make changes directly on the VPS
vim scripts/backup.sh
vim docker-compose/docker-compose.yml

# Back up your work to Gitea
git add -A
git commit -m "Update backup script with better error handling"
git push origin main

# Now your work is backed up and version-controlled on Gitea!
```

### Workflow 4: Create and Test New Feature

```bash
# Create a new branch for experimental work
git checkout -b feature/new-setup

# Make your changes
# Test everything locally

# If it works, merge back to main
git checkout main
git merge feature/new-setup

# Push to Gitea
git push origin main

# Delete the feature branch (optional)
git branch -d feature/new-setup
```

---

## Useful Git Commands

### View Commit History

See what changed and when:

```bash
# Show last 10 commits
git log --oneline -10

# Show commits with files changed
git log --stat -5

# Show specific commit details
git show abc1234
```

### Undo Changes

If you made a mistake:

```bash
# Discard changes to a specific file (not yet committed)
git checkout -- scripts/deploy.sh

# Discard all uncommitted changes
git reset --hard HEAD

# Undo the last commit (keep your changes)
git reset --soft HEAD~1

# Undo the last commit (discard changes)
git reset --hard HEAD~1
```

### Compare Versions

See differences between versions:

```bash
# Changes not yet committed
git diff

# Changes between two commits
git diff abc1234 def5678

# Changes between branches
git diff main feature/new-setup
```

### Sync with Latest Changes

Get updates from Gitea:

```bash
# Fetch latest without merging
git fetch origin

# Pull latest and merge (recommended)
git pull origin main
```

---

## Troubleshooting

### "fatal: could not read Username"

**Problem:** Git is asking for authentication but you don't have credentials saved.

**Solution 1 - Use HTTPS with saved credentials:**
```bash
git config --global credential.helper store
git clone http://100.120.125.113:3000/pdm/homelab-agents.git
# Enter username (pdm) and password when prompted
# Credentials are saved for future use
```

**Solution 2 - Configure git user:**
```bash
git config --global user.name "pdm"
git config --global user.email "your@email.com"
```

### "Permission denied" on push

**Problem:** Your push was rejected, possibly due to:
- Network access to Gitea server
- Repository permissions
- Authentication issue

**Check network access:**
```bash
ping 100.120.125.113
curl -I http://100.120.125.113:3000
```

**Verify remote URL:**
```bash
git remote -v
# Should show: origin  http://100.120.125.113:3000/pdm/[project].git
```

**Test Gitea access:**
```bash
# Try to fetch (read-only test)
git fetch origin
```

### "branch is behind" or merge conflicts

**Problem:** Someone else pushed changes, and you have local changes too.

**Solution:**
```bash
# Get latest from Gitea
git pull origin main

# If conflicts occur, manually edit the conflicted files
git add .
git commit -m "Resolve merge conflicts"
git push origin main
```

### Repository not found

**Problem:** Repository URL is incorrect or repository doesn't exist on Gitea.

**Solution:**
```bash
# Verify correct URL format:
# http://100.120.125.113:3000/pdm/[exact-project-name].git

# Check what repositories exist by visiting:
http://100.120.125.113:3000/pdm

# Update remote if needed
git remote set-url origin http://100.120.125.113:3000/pdm/correct-name.git
```

### Lost changes or need to recover

**Problem:** You made changes but accidentally ran `git reset --hard`

**Solution - Find your work:**
```bash
# See recent commits even if hidden
git reflog

# Restore to a specific commit
git reset --hard abc1234
```

---

## Quick Reference Card

```bash
# Cloning
git clone http://100.120.125.113:3000/pdm/homelab-agents.git ~/.homelab-agents
git clone http://100.120.125.113:3000/pdm/vps-system-apps.git ~/projects/system-apps

# Status and viewing changes
git status                    # See what changed
git diff                      # See exact changes
git log --oneline -10         # See recent commits

# Committing and pushing
git add -A                    # Stage all changes
git commit -m "Your message"  # Create commit
git push origin main          # Push to Gitea

# Getting updates
git pull origin main          # Get latest from Gitea
git fetch origin              # Check for updates without merging

# Branches
git checkout -b feature-name  # Create new branch
git checkout main             # Switch to main branch
git merge feature-name        # Merge branch into main

# Undoing
git reset --hard HEAD~1       # Undo last commit
git checkout -- filename      # Undo changes to file
git revert abc1234           # Create new commit undoing old one
```

---

## Tips and Best Practices

### ✓ Do
- **Pull before you push** - Get latest changes first: `git pull origin main`
- **Commit frequently** - Small, focused commits are easier to understand
- **Write good commit messages** - Future you will thank you
- **Test before pushing** - Verify changes work before committing
- **Use meaningful branch names** - `feature/monitoring-stack` not `test123`
- **Keep backups** - Push to Gitea regularly for safety

### ✗ Don't
- **Don't commit secrets** - Never commit passwords, API keys, or tokens
- **Don't push broken code** - Test locally first
- **Don't commit generated files** - Use `.gitignore` for compiled code, dependencies
- **Don't force push to main** - Unless you really know what you're doing
- **Don't let changes sit locally** - Push to Gitea for backup regularly
- **Don't ignore errors** - Read error messages carefully before asking for help

---

## Getting Help

### Git Help
```bash
git help [command]        # Get help for a command
git help commit           # Example: help for commit command
```

### Check Gitea Web Interface

Visit http://100.120.125.113:3000 to:
- Browse repository files
- View commit history
- See who changed what
- Manage repository settings

### Verify Your Setup

```bash
# Check git version
git --version

# Check global config
git config --global -l

# Test Gitea access
git clone http://100.120.125.113:3000/pdm/homelab-agents.git test-repo
# If successful, you're all set!
rm -rf test-repo
```

---

**Happy coding! Your homelab now has version control.** 🚀