homelab/ansible/archive/documentation/README.md

Ansible Documentation

This folder contains Ansible-specific technical documentation for the homelab automation framework.

Documentation Organization

The homelab uses a domain-based separation for documentation:

Ansible-Specific Documentation (This Folder)

Documentation about how Ansible works in this homelab:

• ansible-knowledge/ — Ansible syntax, YAML/Jinja2 reference, technical constraints
• playbooks/ — Operational guides for running specific playbooks
• playbooks/README.md — Playbook runbook index, including Watchtower monitoring onboarding and self-healing
• standards/ansible-quality-gates.md — Ansible linting rules, security checklist, review workflow

Homelab-Wide Documentation (Root /documentation/)

Documentation about what the homelab allows and architectural decisions:

• /documentation/architecture/ — Architectural contracts (control-plane, compute-plane, networking, storage, access-identity)
• /documentation/standards/ — Homelab-wide standards (naming conventions, environment constraints, architecture decisions)
• /documentation/policies/ — Operational policies (networking policy, etc.)
• /documentation/handover.md — Primary project handover document

Quick Reference

When Troubleshooting Ansible Issues

1. Syntax errors? → ansible-knowledge/ansible-syntax.md
2. Playbook not working? → playbooks/README.md for operational guides
3. Monitoring stack onboarding? → playbooks/watchtower-monitoring-onboarding.md
4. Linting failures? → standards/ansible-quality-gates.md

When Designing Infrastructure

1. What services can run where? → /documentation/architecture/compute-plane.md
2. Network topology? → /documentation/architecture/networking.md
3. Storage architecture? → /documentation/architecture/storage.md
4. Naming conventions? → /documentation/standards/naming-conventions.md

Files in This Folder

ansible/documentation/
├── README.md                    # You are here
├── ansible-knowledge/           # Ansible syntax and technical reference
│   └── ansible-syntax.md
├── playbooks/                   # Operational guides for playbooks
│   ├── README.md
│   ├── manage_docker_environment.md
│   ├── mount_nfs_shares.md
│   ├── onboard_new_host.md
│   ├── onboard-ansible-secrets.md
│   └── watchtower-monitoring-onboarding.md
├── reports/                     # Analysis and audit reports
│   └── prompt-analysis-2026-01-09.md
└── standards/                   # Ansible-specific standards
    └── ansible-quality-gates.md

Contributing

When adding new documentation:

• Ansible-specific content (syntax, modules, playbook operations) → Add to this folder
• Homelab-wide content (architecture, contracts, policies) → Add to /documentation/ at the repository root

If unsure, ask: "Is this about how Ansible works, or about what the homelab architecture allows?"