From 0281f7d80626905e57ef45ddd790835f84598980 Mon Sep 17 00:00:00 2001 From: directlx Date: Mon, 9 Feb 2026 13:49:36 -0500 Subject: [PATCH] Add comprehensive CLAUDE.md project guidance Created comprehensive project configuration for Claude Code: - Complete infrastructure overview (16 servers) - Ansible command reference - Playbook execution patterns - Security operations guide - Configuration management patterns - Firewall, SSH, SSL offloading procedures - Troubleshooting guide - Common tasks with examples - Security best practices - Maintenance schedules This provides Claude Code with project-specific guidance when working in this repository, complementing the version-controlled configuration in dlx-claude repository. Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 373 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 373 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b6fe3f1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,373 @@ +# CLAUDE.md - dlx-ansible + +Infrastructure as Code for DirectLX - Ansible playbooks, roles, and inventory for managing a Proxmox-based homelab infrastructure with multiple services. + +## Project Overview + +This repository manages 16 servers across Proxmox hypervisors, databases, web services, infrastructure services, and applications using Ansible automation. + +## Infrastructure + +### Server Inventory + +**Proxmox Cluster**: +- proxmox-00 (192.168.200.10) - Primary hypervisor +- proxmox-01 (192.168.200.11) - Secondary hypervisor +- proxmox-02 (192.168.200.12) - Tertiary hypervisor + +**Database Servers**: +- postgres (192.168.200.103) - PostgreSQL database +- mysql (192.168.200.110) - MySQL/MariaDB database +- mongo (192.168.200.111) - MongoDB database + +**Web/Proxy Servers**: +- nginx (192.168.200.65) - Web server +- npm (192.168.200.71) - Nginx Proxy Manager for SSL termination + +**Infrastructure Services**: +- docker (192.168.200.200) - Docker host for various containerized services +- pihole (192.168.200.100) - DNS server and ad-blocking +- gitea (192.168.200.102) - Self-hosted Git service +- jenkins (192.168.200.91) - CI/CD server + SonarQube + +**Application Servers**: +- hiveops (192.168.200.112) - HiveOps incident management (Spring Boot) +- smartjournal (192.168.200.114) - Journal tracking application +- odoo (192.168.200.61) - ERP system + +**Control**: +- ansible-node (192.168.200.106) - Ansible control node + +### Common Access Patterns + +- **User**: dlxadmin (passwordless sudo on all servers) +- **SSH**: Key-based authentication (password disabled on most servers) +- **Exception**: Jenkins server has password auth enabled for AWS Jenkins Master connection +- **Firewall**: UFW managed via common role + +## Quick Start Commands + +### Basic Ansible Operations + +```bash +# Check connectivity to all servers +ansible all -m ping + +# Check connectivity to specific group +ansible webservers -m ping + +# Run ad-hoc command +ansible all -m shell -a "uptime" -b + +# Gather facts about servers +ansible all -m setup +``` + +### Playbook Execution + +```bash +# Run main site playbook +ansible-playbook playbooks/site.yml + +# Limit to specific servers +ansible-playbook playbooks/site.yml -l jenkins,npm + +# Limit to server group +ansible-playbook playbooks/site.yml -l webservers + +# Use tags +ansible-playbook playbooks/site.yml --tags firewall + +# Dry run (check mode) +ansible-playbook playbooks/site.yml --check + +# Verbose output +ansible-playbook playbooks/site.yml -v +ansible-playbook playbooks/site.yml -vvv # very verbose +``` + +### Security Operations + +```bash +# Run comprehensive security audit +ansible-playbook playbooks/security-audit-v2.yml + +# View audit results +cat /tmp/security-audit-*/report.txt +cat docs/SECURITY-AUDIT-SUMMARY.md + +# Apply security updates +ansible all -m apt -a "update_cache=yes upgrade=dist" -b + +# Check firewall status +ansible all -m shell -a "ufw status verbose" -b + +# Configure Docker server firewall (when ready) +ansible-playbook playbooks/secure-docker-server-firewall.yml +``` + +### Server Management + +```bash +# Reboot servers +ansible all -m reboot -b + +# Check disk space +ansible all -m shell -a "df -h" -b + +# Check memory usage +ansible all -m shell -a "free -h" -b + +# Check running services +ansible all -m shell -a "systemctl status" -b + +# Update packages +ansible all -m apt -a "update_cache=yes" -b +``` + +## Directory Structure + +``` +dlx-ansible/ +├── inventory/ +│ └── hosts.yml # Server inventory with IPs and groups +│ +├── host_vars/ # Per-host configuration +│ ├── jenkins.yml # Jenkins-specific vars (firewall ports) +│ ├── npm.yml # NPM firewall configuration +│ ├── hiveops.yml # HiveOps settings +│ └── ... +│ +├── group_vars/ # Per-group configuration +│ +├── roles/ # Ansible roles +│ └── common/ # Common configuration for all servers +│ ├── tasks/ +│ │ ├── main.yml +│ │ ├── packages.yml +│ │ ├── security.yml # Firewall, SSH hardening +│ │ ├── users.yml +│ │ └── timezone.yml +│ └── defaults/ +│ └── main.yml # Default variables +│ +├── playbooks/ # Ansible playbooks +│ ├── site.yml # Main playbook (includes all roles) +│ ├── security-audit-v2.yml # Security audit +│ ├── secure-docker-server-firewall.yml +│ └── ... +│ +├── templates/ # Jinja2 templates +│ +└── docs/ # Documentation + ├── SECURITY-AUDIT-SUMMARY.md + ├── JENKINS-CONNECTIVITY-FIX.md + └── ... +``` + +## Key Configuration Patterns + +### Firewall Management + +Firewall is managed by the common role. Configuration is per-host in `host_vars/`: + +```yaml +# Example: host_vars/jenkins.yml +common_firewall_enabled: true +common_firewall_allowed_ports: + - "22/tcp" # SSH + - "8080/tcp" # Jenkins + - "9000/tcp" # SonarQube +``` + +**Firewall Disabled Hosts**: +- docker, hiveops, smartjournal, odoo (disabled for Docker networking) + +### SSH Configuration + +Most servers use key-only authentication: +```yaml +PasswordAuthentication no +PubkeyAuthentication yes +PermitRootLogin no # (except Proxmox nodes) +``` + +**Exception**: Jenkins has password authentication enabled for AWS Jenkins Master. + +### Spring Boot SSL Offloading + +For Spring Boot applications behind Nginx Proxy Manager: + +```yaml +environment: + SERVER_FORWARD_HEADERS_STRATEGY: native + SERVER_USE_FORWARD_HEADERS: true +``` + +This prevents redirect loops when NPM terminates SSL. + +### Docker Compose + +When .env is not in same directory as compose file: +```bash +docker compose -f docker/docker-compose.yml --env-file .env up -d +``` + +**Container updates**: Always recreate (not restart) when changing environment variables. + +## Critical Knowledge + +See `~/.claude/projects/-source-dlx-src-dlx-ansible/memory/MEMORY.md` for detailed infrastructure knowledge including: + +- SSL offloading configuration +- Jenkins connectivity troubleshooting +- Storage remediation procedures +- Security audit findings +- Common fixes and solutions + +## Common Tasks + +### Add New Server + +1. Add to `inventory/hosts.yml`: + ```yaml + newserver: + ansible_host: 192.168.200.xxx + ``` + +2. Create `host_vars/newserver.yml` (if custom config needed) + +3. Run setup: + ```bash + ansible-playbook playbooks/site.yml -l newserver + ``` + +### Update Firewall Rules + +1. Edit `host_vars/.yml`: + ```yaml + common_firewall_allowed_ports: + - "22/tcp" + - "80/tcp" + - "443/tcp" + ``` + +2. Apply changes: + ```bash + ansible-playbook playbooks/site.yml -l --tags firewall + ``` + +### Enable Automatic Security Updates + +```bash +ansible all -m apt -a "name=unattended-upgrades state=present" -b +ansible all -m copy -a "dest=/etc/apt/apt.conf.d/20auto-upgrades content='APT::Periodic::Update-Package-Lists \"1\";\nAPT::Periodic::Unattended-Upgrade \"1\";' mode=0644" -b +``` + +### Run Monthly Security Audit + +```bash +ansible-playbook playbooks/security-audit-v2.yml +cat docs/SECURITY-AUDIT-SUMMARY.md +``` + +## Git Workflow + +- **Main Branch**: Production-ready configurations +- **Commit Messages**: Descriptive, include what was changed and why +- **Co-Authored-By**: Include for Claude-assisted work +- **Testing**: Always test with `--check` before applying changes + +Example commit: +```bash +git add playbooks/new-playbook.yml +git commit -m "Add playbook for X configuration + +This playbook automates Y to solve Z problem. + +Co-Authored-By: Claude Sonnet 4.5 " +``` + +## Troubleshooting + +### SSH Connection Issues + +```bash +# Test SSH connectivity +ansible -m ping + +# Check SSH with verbose output +ssh -vvv dlxadmin@ + +# Test from control machine +ansible -m shell -a "whoami" -b +``` + +### Firewall Issues + +```bash +# Check firewall status +ansible -m shell -a "ufw status verbose" -b + +# Temporarily disable (for debugging) +ansible -m ufw -a "state=disabled" -b + +# Re-enable +ansible -m ufw -a "state=enabled" -b +``` + +### Playbook Failures + +```bash +# Run with verbose output +ansible-playbook playbooks/site.yml -vvv + +# Check syntax +ansible-playbook playbooks/site.yml --syntax-check + +# List tasks +ansible-playbook playbooks/site.yml --list-tasks + +# Start at specific task +ansible-playbook playbooks/site.yml --start-at-task="task name" +``` + +## Security Best Practices + +1. **Always test with --check first** +2. **Limit scope with -l when testing** +3. **Keep firewall rules minimal** +4. **Use key-based SSH authentication** +5. **Enable automatic security updates** +6. **Run monthly security audits** +7. **Document changes in memory** +8. **Never commit secrets** (use Ansible Vault when needed) + +## Important Notes + +- Jenkins password auth is intentional (for AWS Jenkins Master access) +- Firewall disabled on hiveops/smartjournal/odoo for Docker networking +- Proxmox nodes may require root login for management +- NPM server (192.168.200.71) handles SSL termination for web services +- Pi-hole (192.168.200.100) provides DNS for internal services + +## Resources + +- **Documentation**: `docs/` directory +- **Security Audit**: `docs/SECURITY-AUDIT-SUMMARY.md` +- **Claude Memory**: `~/.claude/projects/-source-dlx-src-dlx-ansible/memory/MEMORY.md` +- **Version Controlled Config**: http://192.168.200.102/directlx/dlx-claude + +## Maintenance Schedule + +- **Daily**: Monitor server health, check failed logins +- **Weekly**: Review and apply security updates +- **Monthly**: Run security audit, review firewall rules +- **Quarterly**: Review and update documentation + +--- + +**Last Updated**: 2026-02-09 +**Repository**: http://192.168.200.102/directlx/dlx-ansible (Gitea) +**Claude Memory**: Maintained in ~/.claude/projects/ +**Version Controlled**: http://192.168.200.102/directlx/dlx-claude