jramos/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(repo): reorganize repository structure for improved navigation and maintainability

Browse Source 
Implement comprehensive directory reorganization to improve discoverability,
logical grouping, and separation of concerns across documentation, scripts,
and infrastructure snapshots.

Major Changes:

1. Documentation Reorganization:
   - Created start-here-docs/ for onboarding documentation
     * Moved QUICK-START.md, START-HERE.md, GIT-SETUP-GUIDE.md
     * Moved GIT-QUICK-REFERENCE.md, SCRIPT-USAGE.md, SETUP-COMPLETE.md
   - Created troubleshooting/ directory
     * Moved BUGFIX-SUMMARY.md for centralized issue resolution
   - Created mcp/ directory for Model Context Protocol configurations
     * Moved OBSIDIAN-MCP-SETUP.md to mcp/obsidian/

2. Scripts Reorganization:
   - Created scripts/crawlers-exporters/ for infrastructure collection
     * Moved collect*.sh scripts and collection documentation
     * Consolidates Proxmox homelab export tooling
   - Created scripts/fixers/ for operational repair scripts
     * Moved fix_n8n_db_*.sh scripts
     * Isolated scripts with embedded credentials (templates tracked)
   - Created scripts/qol/ for quality-of-life utilities
     * Moved git-aliases.sh and git-first-commit.sh

3. Infrastructure Snapshots:
   - Created disaster-recovery/ for active infrastructure state
     * Moved latest homelab-export-20251202-204939/ snapshot
     * Contains current VM/CT configurations and system state
   - Created archive-homelab/ for historical snapshots
     * Moved homelab-export-*.tar.gz archives
     * Preserves point-in-time backups for reference

4. Agent Definitions:
   - Created sub-agents/ directory
     * Added backend-builder.md (development agent)
     * Added lab-operator.md (infrastructure operations agent)
     * Added librarian.md (git/version control agent)
     * Added scribe.md (documentation agent)

5. Updated INDEX.md:
   - Reflects new directory structure throughout
   - Updated all file path references
   - Enhanced navigation with new sections
   - Added agent roles documentation
   - Updated quick reference commands

6. Security Improvements:
   - Updated .gitignore to match reorganized file locations
   - Corrected path for scripts/fixers/fix_n8n_db_c_locale.sh exclusion
   - Maintained template-based credential management pattern

Infrastructure State Update:
   - Latest snapshot: 2025-12-02 20:49:54
   - Removed: VM 101 (gitlab), CT 112 (Anytype)
   - Added: CT 113 (n8n)
   - Total: 9 VMs, 3 Containers

Impact:
   - Improved repository navigation and discoverability
   - Logical separation of documentation, scripts, and snapshots
   - Clearer onboarding path for new users
   - Enhanced maintainability through organized structure
   - Foundation for multi-agent workflow support

Files changed: 90 files (+935/-349)
   - 3 modified, 14 new files, 73 renames/moves

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Jordan Ramos
2025-12-02 21:39:33 -07:00
parent eec4c4b298
commit 4f69420aaa
90 changed files with 935 additions and 349 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
start-here-docs/GIT-SETUP-GUIDE.md Normal file
View File

@@ -0,0 +1,370 @@
# Git Setup Guide for WSL2 Homelab
## The Problem We Solved
When working with git in WSL2 (Windows Subsystem for Linux), you encountered a common issue: **git cannot properly manage repositories on Windows filesystems** (like `/mnt/c/Users/...`).
### Why This Happens
Git requires specific POSIX file permissions and attributes that Windows' NTFS filesystem doesn't support. When git tries to create lock files (like `.git/config.lock`), it fails because:
1. Windows filesystems don't support the same permission model as Linux
2. WSL2 translates permissions, but this breaks git's lock file mechanism
3. Git needs to atomically create/rename files with specific permissions
The error you saw was:
```
error: chmod on .git/config.lock failed: Operation not permitted
```
This is git saying "I can't set the proper permissions on my lock file."
## The Solution We Implemented
We moved your repository to the **Linux filesystem** where git works properly, while keeping it accessible from Windows.
### What We Did
1. **Created a new directory in Linux filesystem**: `/home/jramos/homelab`
- This is a "real" Linux filesystem with proper permission support
- Git works perfectly here
2. **Copied all your files** from the Windows location to the Linux location
3. **Initialized git properly** in the Linux filesystem
4. **Made it accessible from Windows** via the special `\\wsl$\` network path
## Your Repository Locations
### Linux Path (Use this in WSL2 terminal)
```bash
cd /home/jramos/homelab
```
### Windows Path (Use this in File Explorer)
```
\\wsl$\Ubuntu\home\jramos\homelab
```
To access from Windows:
1. Open File Explorer
2. In the address bar, type: `\\wsl$\Ubuntu\home\jramos\homelab`
3. Press Enter
4. You can bookmark this location for easy access
**Pro Tip**: You can map this as a network drive:
- Right-click on "This PC" in File Explorer
- Choose "Map network drive"
- Use the path: `\\wsl$\Ubuntu\home\jramos\homelab`
## What About Your Old Windows Directory?
You have two options:
### Option 1: Keep Windows Directory as Working Copy (Recommended)
Keep using `/mnt/c/Users/fam1n/Documents/homelab` for day-to-day work, and manually sync changes to the git repository when needed:
```bash
# After making changes in Windows location, sync to git repo:
rsync -av --exclude='.git' /mnt/c/Users/fam1n/Documents/homelab/ /home/jramos/homelab/
# Then commit in the git repo:
cd /home/jramos/homelab
git add .
git commit -m "Updated configurations"
```
### Option 2: Fully Switch to Linux Location
Start working exclusively in `/home/jramos/homelab`. You can delete or archive the Windows directory.
## Your First Git Commit
### Quick Method
Run the helper script:
```bash
cd /home/jramos/homelab
./git-first-commit.sh
```
This interactive script will:
1. Set up your git username and email (if not already configured)
2. Show you what will be committed
3. Create your initial commit
4. Explain what to do next
### Manual Method
If you prefer to do it manually:
```bash
cd /home/jramos/homelab
# Configure your identity (one-time setup)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# Check what files will be committed
git status
# Add all files to staging area
git add .
# Create your first commit
git commit -m "Initial commit: Homelab infrastructure repository"
# View your commit
git log
```
## Files That Are Ignored by Git
The `.gitignore` file tells git to **not** track certain files. Here's what's ignored:
### Sensitive Information
- `.env` - Your actual environment configuration (contains passwords, IPs, etc.)
- `*.key`, `*.pem` - Private keys and certificates
- `secrets/` - Any directory for secrets
- `credentials.json` - Credential files
### Large Files
- `*.iso` - ISO images (too large for git)
- `*.qcow2`, `*.vmdk` - Virtual machine disk images
- `*.tar.gz`, `*.zip` - Compressed archives
### Temporary Files
- `*.log` - Log files
- `*.tmp` - Temporary files
- `backups/` - Backup directories
- `homelab-export-*/` - Your export directories (unless you want them tracked)
### What IS Tracked
- All your scripts (`.sh` files)
- Documentation (`.md` files)
- `.env.example` - Template for environment configuration
- Configuration files
## Common Git Commands for Beginners
### Checking Status
```bash
cd /home/jramos/homelab
git status # See what's changed
```
### Making Changes and Committing
```bash
# Edit your files, then...
git status # See what you changed
git diff # See exactly what changed (detailed)
git add filename.sh # Stage a specific file
git add . # Stage all changes
git commit -m "Description" # Commit with a message
```
### Viewing History
```bash
git log # See all commits (detailed)
git log --oneline # See commits (compact)
git log --graph --oneline # See commits with graph
```
### Undoing Changes
```bash
# Undo changes in a file (before staging)
git checkout -- filename.sh
# Unstage a file (undo git add)
git reset filename.sh
# See changes in a specific commit
git show <commit-hash>
# Revert to a previous version
git checkout <commit-hash> -- filename.sh
```
### Comparing Versions
```bash
# See what changed since last commit
git diff
# See what's staged for commit
git diff --staged
# Compare with a specific commit
git diff <commit-hash>
```
## Best Practices for Your Homelab
### 1. Commit Often, Commit Early
Don't wait until you have "perfect" changes. Commit each logical change:
```bash
# Good commit messages:
git commit -m "Add Ansible playbook for nginx configuration"
git commit -m "Update Proxmox backup schedule to daily"
git commit -m "Fix network interface configuration for web-server-01"
```
### 2. Write Descriptive Commit Messages
```bash
# Bad:
git commit -m "updates"
git commit -m "fix"
# Good:
git commit -m "Update GitLab VM memory from 4GB to 8GB for better performance"
git commit -m "Fix nginx reverse proxy configuration for NetBox"
```
### 3. Before Making Major Changes
Create a commit first, so you can easily undo:
```bash
git add .
git commit -m "Checkpoint before restructuring network configuration"
# Now make your risky changes
# If things break: git checkout -- filename
```
### 4. Review Before Committing
```bash
git status # What files changed?
git diff # What exactly changed?
git add . # Stage everything
git status # Double-check what's staged
git commit -m "Your message"
```
### 5. Keep .env Secure
**NEVER** commit your `.env` file. It's already in `.gitignore`, but be careful:
```bash
# This is safe (only adds .env.example):
git add .
# This would be dangerous (explicitly adds .env, bypassing .gitignore):
git add -f .env # DON'T DO THIS!
```
## Workflow Example
Here's a typical workflow when you make changes:
```bash
# 1. Navigate to your repository
cd /home/jramos/homelab
# 2. Make changes to your files
nano collect-homelab-config.sh # Edit your script
# 3. Test your changes
./collect-homelab-config.sh
# 4. Review what changed
git status
git diff collect-homelab-config.sh
# 5. Stage the changes
git add collect-homelab-config.sh
# 6. Commit with a descriptive message
git commit -m "Add paranoid collection level to homelab collection script
- Added new PARANOID level with complete system snapshot
- Includes kernel modules, network statistics, and process list
- Updated documentation in COLLECTION-GUIDE.md"
# 7. View your history
git log --oneline -5 # Show last 5 commits
```
## Troubleshooting
### "I'm in the wrong directory"
```bash
pwd # Where am I?
cd /home/jramos/homelab # Go to the right place
```
### "Git says 'not a git repository'"
```bash
# Check if .git directory exists
ls -la /home/jramos/homelab/.git
# If it doesn't exist, you're in the wrong place
cd /home/jramos/homelab
```
### "I committed something I shouldn't have"
```bash
# Undo the last commit but keep the changes
git reset --soft HEAD~1
# Undo the last commit AND discard the changes
git reset --hard HEAD~1 # CAREFUL: This deletes your work!
```
### "I want to see what changed in a commit"
```bash
git log --oneline # Find the commit hash
git show <commit-hash> # See the changes
```
### "I accidentally changed a file"
```bash
# Undo changes (before git add)
git checkout -- filename.sh
# Undo staged changes (after git add)
git reset filename.sh
git checkout -- filename.sh
```
## Next Steps
1. **Make your first commit**:
```bash
cd /home/jramos/homelab
./git-first-commit.sh
```
2. **Start tracking changes**: Every time you modify scripts or configurations, commit them
3. **Learn as you go**: Git has many features, but you only need the basics to start
4. **Consider remote backup**: Later, you might want to push your repository to GitHub/GitLab for backup
## Why Version Control Matters for Homelabs
Version control gives you:
1. **History**: See what changed and when
2. **Undo**: Revert mistakes easily
3. **Documentation**: Commit messages explain why changes were made
4. **Backup**: Your configuration history is preserved
5. **Experimentation**: Try things without fear—you can always go back
Think of it as "time travel for your infrastructure configurations."
## Additional Resources
### Learning Git
- **Git Documentation**: https://git-scm.com/doc
- **GitHub Git Handbook**: https://guides.github.com/introduction/git-handbook/
- **Interactive Git Tutorial**: https://learngitbranching.js.org/
### Git Cheat Sheets
- https://training.github.com/downloads/github-git-cheat-sheet/
### Advanced Topics (For Later)
- Branching and merging
- Remote repositories (GitHub, GitLab)
- Git hooks for automation
- Using git with Infrastructure as Code
---
**Remember**: Git is a tool to make your life easier. Start simple, commit often, and learn as you go. You don't need to master everything at once.
If you run into issues, the git community is huge and helpful. Most problems you encounter have been solved before—just search for the error message.
Happy version controlling!