From 8112530f7b124d4d15f43ae7efe831ba2ae9b340 Mon Sep 17 00:00:00 2001 From: Homelab Automation Date: Sun, 23 Nov 2025 14:51:01 +0000 Subject: [PATCH] Add comprehensive Gitea how-to guide - Basic clone commands for homelab-agents and vps-system-apps - Step-by-step workflow for making and pushing changes - Common workflows for different scenarios - Useful git commands reference - Troubleshooting section for common issues - Quick reference card for frequently used commands - Best practices and tips This guide provides everything needed to get started with Gitea for managing homelab projects and agent repositories. --- HOW-TO-GUIDE.md | 503 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 503 insertions(+) create mode 100644 HOW-TO-GUIDE.md diff --git a/HOW-TO-GUIDE.md b/HOW-TO-GUIDE.md new file mode 100644 index 0000000..1d6de5c --- /dev/null +++ b/HOW-TO-GUIDE.md @@ -0,0 +1,503 @@ +# 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) +- [Cloning Repositories](#cloning-repositories) +- [Making Changes](#making-changes) +- [Pushing Changes](#pushing-changes) +- [Common Workflows](#common-workflows) +- [Troubleshooting](#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: + +```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 main 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 Workstation, Push to Gitea + +```bash +# 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 + +```bash +# 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 + +```bash +# 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 + +```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.** 🚀