jramos/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
18 Commits 1 Branch 0 Tags
07f9638d8be8ca3c128337f779fc12ea54c694b2
Commit Graph

2 Commits

Author SHA1 Message Date
Jordan Ramos
4f69420aaa refactor(repo): reorganize repository structure for improved navigation and maintainability 
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>
 2025-12-02 21:39:33 -07:00
Jordan Ramos
a626c48e7b docs(n8n): complete PostgreSQL 15+ troubleshooting and add operational scripts 
This commit documents the comprehensive troubleshooting session that identified
and resolved the n8n 502 Bad Gateway issue, along with production-ready fix scripts.

Root Cause Identified:
- PostgreSQL 15+ removed default CREATE privilege on public schema
- n8n_user unable to create tables during database migration
- Service trapped in crash loop (805+ restart cycles over 6 minutes)
- Error: "permission denied for schema public"

CLAUDE_STATUS.md Updates:
- Executive summary with key findings and 95% deployment confidence
- Complete error log evidence (exact error messages from 805+ restart cycles)
- Detailed root cause analysis of PostgreSQL 15+ breaking change
- Fix script validation by backend-builder (92/100 rating)
- Quick deployment guide with pre/post-deployment procedures
- Communication log documenting all three agent contributions
- Lessons learned for future Debian 12 + PostgreSQL 16 deployments

Scripts Added (All Sanitized):
1. fix_n8n_db_permissions.sh
   - Fixes PostgreSQL 15+ permission issue for n8n database
   - Creates backups before changes (pg_dump to /var/backups/n8n/)
   - Recreates database with proper ownership and explicit schema grants
   - Tests permissions before restarting service
   - Parameterized password (via N8N_DB_PASSWORD env var)
   - Comprehensive logging to /var/log/n8n_db_fix_*.log
   - Production-ready with error handling and validation

2. export_cf_dns.py (Cloudflare DNS Export Tool)
   - Exports Cloudflare DNS records and zone settings
   - Supports pagination for large zone configurations
   - Parameterized credentials (CF_ZONE_ID, CF_API_TOKEN)
   - Useful for backup/disaster recovery workflows
   - Includes validation function to prevent misconfiguration

3. scripts/README.md
   - Comprehensive documentation for all scripts
   - Usage examples with environment variable approach
   - Security notes and best practices
   - Directory structure and use cases

Security Measures:
- All scripts parameterized (no hardcoded credentials)
- Updated .gitignore to exclude script variants with embedded credentials
- Added patterns for *_with_creds.*, *.local.*, *_prod.* variants
- Documentation emphasizes environment variable usage

Agent Contributions:
- Lab-Operator: Analyzed error logs, identified PostgreSQL 15+ permission issue (100% confidence)
- Backend-Builder: Created fix script, validated against errors (92/100 rating, 95% deployment confidence)
- Scribe: Documented complete troubleshooting session with evidence and deployment guides
- Librarian: Sanitized scripts, managed git operations, ensured no credential exposure

Files Changed:
- Modified: CLAUDE_STATUS.md (+313 lines comprehensive troubleshooting documentation)
- Modified: .gitignore (+9 lines for script credential protection)
- New: scripts/fix_n8n_db_permissions.sh (349 lines, production-ready)
- New: scripts/crawlers-exporters/export_cf_dns.py (144 lines, sanitized)
- New: scripts/README.md (138 lines documentation)
- New: scripts/crawlers-exporters/*.json (DNS export examples)

Ready for Deployment: User can now execute fix script with 95% confidence
Expected Result: n8n service will successfully complete database migrations and start

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-12-01 17:16:20 -07:00