pdm/homelab-agents
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add comprehensive Gitea how-to guide

Browse Source 
- 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.
This commit is contained in:
Homelab Automation
2025-11-23 14:51:01 +00:00
parent c4a1c15c61
commit 8112530f7b
1 changed files with 503 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

503
HOW-TO-GUIDE.md Normal file
View File

@@ -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.** 🚀