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
• Cloning Repositories
• Making Changes
• Pushing Changes
• Common Workflows
• Troubleshooting

---

Getting Started

About Your Gitea Server

• Server URL: http://100.120.125.113:3000
• 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

---

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:

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:

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 main workstation for editing
• Working on system configuration with version history

Clone Any Other Project Repository

For future projects, use the same pattern:

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:

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:

git diff docker-compose/docker-compose.yml

Or see all changes:

git diff

Creating a Local Branch (Optional)

For experimental work, create a separate branch:

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:

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:

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

Or add specific files:

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

Step 2: Commit Your Changes

Create a commit with a descriptive message:

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:

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:

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 Workstation, Push to Gitea

# On your main workstation
git clone http://100.120.125.113:3000/pdm/vps-system-apps.git ~/projects/system-apps

# Edit files in ~/projects/system-apps/
# Update docker-compose.yml, scripts, etc.

# Check what changed
git status

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

# Push to Gitea
git push origin main

Workflow 2: Update Agents on VPS

# On your VPS
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

# On your VPS
cd ~/projects/system-apps

# Make changes to configurations
nano 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

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

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

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

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

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

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:

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:

ping 100.120.125.113
curl -I http://100.120.125.113:3000

Verify remote URL:

git remote -v
# Should show: origin  http://100.120.125.113:3000/pdm/[project].git

Test Gitea access:

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

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

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

# See recent commits even if hidden
git reflog

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

---

Quick Reference Card

# 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

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

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