---
id: TECH-CODEBASE-MAP
type: technical
status: active
title: Codebase Map
created: '2026-09-09'
updated: '2026-09-09'
tags:
- technical
- codebase
related:
- TECH-ARCHITECTURE
- SCAN-20260909
source_paths: []
confidence: confirmed
---

# Codebase Map

Ansible repository, no application source code. Structure as of 2026-09-09.

## Root Files

| Path | Purpose |
| --- | --- |
| `ansible.cfg` | Global Ansible config: no host key checking, `roles_path=./roles`, `forks=20`, smart gathering, SSH pipelining |
| `bootstrap.yml` | Top-level playbook, binds the `bootstrap` role with Debian guard |
| `execute.sh` | Starts the interactive Docker runtime container (`ansible:deb13`) |
| `vault.yml` | Ansible-Vault encrypted secrets (tracked, encrypted) |
| `setenv.sh` | Proxmox credentials (git-ignored, not in repo) |
| `.vault_pass`, `.zabbix-psk/`, `logs/` | Vault password, per-host PSKs, update logs (git-ignored) |

## Directories

```
docker/                  Dockerfile (debian:trixie-slim + ansible-core 2.20.x),
                         requirements.yml (pinned collections), ansible-functs.sh
                         (aliases ap/ag/av)
inventory/               cloudlorean.yml, home.yml, external.yml + group_vars/
playbooks/               docker.yml, monitoring.yml, os-updates-deb.yml,
                         upgrade-hawser.yml, hardening/manage-ssh-keys.yml
roles/bootstrap/         tasks/ (8 subtasks), templates/ (4), handlers/, README.md
roles/docker/            tasks/ (2), templates/sources.list.j2, handlers/, README.md
roles/hawser/            tasks/ (2), templates/docker-compose.yml.j2, handlers/, README.md
roles/healthcheck/       tasks/main.yml, defaults/, README.md (no handlers/templates)
roles/manage-ssh-keys/   tasks/ (4), handlers/, defaults/, README.md
roles/monitoring/        tasks/ (8), templates/ (2: zabbix_agent2.conf.j2, docker.conf.j2),
                         handlers/, README.md
roles/os-updates/        tasks/ (6), templates/ (2: sources.list.j2, sources.list-deb822.j2),
                         handlers/, README.md
```

## Entry Points

| Playbook | Role(s) | Notes |
| --- | --- | --- |
| `bootstrap.yml` | bootstrap (+ docker, monitoring) | Full initial setup |
| `playbooks/docker.yml` | docker | Docker Engine install |
| `playbooks/monitoring.yml` | monitoring | Loads `../vault.yml` |
| `playbooks/os-updates-deb.yml` | os-updates, healthcheck | Update + quality gate |
| `playbooks/upgrade-hawser.yml` | hawser | Compose stack update |
| `playbooks/hardening/manage-ssh-keys.yml` | manage-ssh-keys | No Debian guard, no become |

## Conventions (Observed)

- Roles split logic into `tasks/<name>.yml` subtasks; `tasks/main.yml` only
  imports/includes (`bootstrap`, `os-updates`) or delegates to a single
  subtask (`docker`, `hawser`).
- Newer tasks use FQCN; older tasks (apt, file, blockinfile, set_fact,
  include_role) still use short names.
- Per-role README documents variables, templates, handlers, tags.
- Tags observed: `motd`, `ssh`, `bashrc`, `sysctl` (bootstrap),
  `monitoring` (monitoring role).

## Tests

- No automated test suite. Verification is manual: run in the Docker
  container, optional `ansible-lint`, `--check` dry runs. See
  [Testing](./testing.md).

## Inventories

| Site | File | Groups | Hosts |
| --- | --- | --- | --- |
| cloudlorean | `inventory/cloudlorean.yml` | debian (13), proxmox (2: dmc12, pbs) | 192.168.212.0/24 |
| home | `inventory/home.yml` | debian (6), proxmox (1: tardis) | 10.13.37.0/24 |
| external | `inventory/external.yml` | debian (4) | IPv6-only |

Per-site `group_vars/<site>.yml` override Zabbix servers, API URL, proxy,
host groups and templates. See [Architecture](./architecture.md).