117 lines
No EOL
3.8 KiB
Markdown
117 lines
No EOL
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Repository Overview
|
|
|
|
This is an Ansible infrastructure management repository that manages a mixed environment including network services, monitoring, VPN infrastructure, and web applications. The codebase supports multiple operating systems (Debian, Ubuntu, AlmaLinux) and uses a role-based architecture for modularity.
|
|
|
|
Note: Flatcar Container Linux VMs are provisioned by OpenTofu and configured via Butane/Ignition — they are NOT managed by Ansible.
|
|
|
|
## Common Commands
|
|
|
|
### Bootstrap New Hosts
|
|
```bash
|
|
# Initial bootstrap (requires password)
|
|
make bootstrap-init HOSTNAME=hostname ANSIBLE_HOST=ip_address
|
|
|
|
# Full bootstrap with network config and reboot
|
|
make bootstrap HOSTNAME=hostname ANSIBLE_HOST=ip_address
|
|
```
|
|
|
|
### Run playbooks
|
|
```bash
|
|
# Run main playbook
|
|
./run.sh
|
|
|
|
# Run all plays on specific host
|
|
ansible-playbook -l hostname playbook.yml
|
|
|
|
# Run specific tags
|
|
ansible-playbook -t caddy playbook.yml
|
|
```
|
|
|
|
### Development Tasks
|
|
```bash
|
|
# Gather facts from all hosts
|
|
ansible -m setup all
|
|
|
|
# Test changes on specific host
|
|
ansible-playbook -l hostname playbook.yml
|
|
|
|
# Check syntax
|
|
ansible-playbook --syntax-check playbook.yml
|
|
|
|
# Dry run
|
|
ansible-playbook --check playbook.yml
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Playbook Structure
|
|
- `playbook.yml` - Main playbook for all configuration (common, firewall, DNS, Caddy, general, monitoring, PostgreSQL, prometheus stack, etc.)
|
|
- `bootstrap.yml` - Initial host preparation
|
|
- `netbox.yml` - Standalone NetBox deployment
|
|
|
|
### Role Organization
|
|
Roles follow a standard structure with:
|
|
- `tasks/main.yml` - Main task list
|
|
- `handlers/main.yml` - Service restart handlers
|
|
- `templates/` - Jinja2 templates for config files
|
|
- `vars/` - Role-specific variables
|
|
- `defaults/` - Default variable values
|
|
|
|
### Key Roles
|
|
- `base` - Combined base configuration (users, SSH, sudo, packages)
|
|
- `general` - General system configurations (motd, network, syslog, NFS, K3s)
|
|
- `caddy` - Web server and reverse proxy
|
|
- `firewall` - UFW/firewalld rule management
|
|
- `ns` - BIND9 nameserver configuration
|
|
- `tailscale` - Tailscale VPN setup
|
|
- `monitor` - Icinga2 monitoring master
|
|
- `prometheus` / `alertmanager` / `loki` / `grafana` / `node_exporter` - Prometheus monitoring stack
|
|
- `netbox` - NetBox IPAM/DCIM
|
|
- `pgbouncer` - PostgreSQL connection pooler
|
|
- `librenms` - LibreNMS network monitoring
|
|
- `mailcow` - Mailcow email server
|
|
- `dokku` - Dokku PaaS
|
|
- `aprsc` - APRS-IS server
|
|
- `uisp` - Ubiquiti UISP
|
|
- `syncthing` - Syncthing file sync
|
|
|
|
### Variable Precedence
|
|
1. Host-specific vars in `host_vars/`
|
|
2. Group vars in `group_vars/`
|
|
3. Role defaults in `roles/*/defaults/`
|
|
4. Base variables in `vars/`
|
|
|
|
### Service Dependencies
|
|
- SSH configuration managed by base role
|
|
- Firewall rules (UFW/firewalld) applied before service configs
|
|
- Handlers ensure services restart when configs change
|
|
- Tailscale VPN requires `TAILSCALE_AUTHKEY` (or `TAILSCALE_KEY`) environment variable
|
|
- SSH key path defaults to `~/.ssh/ansible`; override via `ANSIBLE_SSH_PRIVATE_KEY_FILE` env var
|
|
|
|
## Key Patterns
|
|
|
|
### User Management
|
|
- Ansible user (UID 10001) created on all hosts
|
|
- SSH keys fetched from GitHub for authentication
|
|
- Passwordless sudo configured for automation
|
|
|
|
### Network Services
|
|
- DNS resolvers are Flatcar VMs managed via OpenTofu + Butane (see ../tofu/)
|
|
- Nameservers configured via ns role
|
|
- Caddy serves as reverse proxy for web services
|
|
- Tailscale provides VPN connectivity
|
|
|
|
### Configuration Management
|
|
- Templates use host-specific variables
|
|
- Handlers manage service restarts
|
|
- Fact caching improves performance
|
|
- Collections required: ansible.posix, community.general, kubernetes.core, community.postgresql, community.proxmox, community.mysql
|
|
|
|
## Memories
|
|
|
|
### Playbook Defaults
|
|
- The default ansible playbook is `playbook.yml` |