ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/project-docs/architecture.md
ilia c3e6caf9e8
All checks were successful
CI / skip-ci-check (push) Successful in 1m18s
Details
CI / lint-and-test (push) Successful in 1m23s
Details
CI / ansible-validation (push) Successful in 3m2s
Details
CI / secret-scanning (push) Successful in 1m19s
Details
CI / dependency-scan (push) Successful in 1m24s
Details
CI / sast-scan (push) Successful in 2m32s
Details
CI / license-check (push) Successful in 1m23s
Details
CI / vault-check (push) Successful in 2m22s
Details
CI / playbook-test (push) Successful in 2m25s
Details
CI / container-scan (push) Successful in 1m51s
Details
CI / sonar-analysis (push) Successful in 2m32s
Details
CI / workflow-summary (push) Successful in 1m17s
Details
refactor-servers-workstations-shell-monitoring (#4) 
### Summary

This PR refactors the playbook layout to reduce duplication and make host intent clearer (servers vs workstations), splits monitoring by host type, and restores full Zsh setup for developers while keeping servers aliases-only.

### Key changes

- **New playbooks**
  - `playbooks/servers.yml`: baseline for server-class hosts (no desktop apps)
  - `playbooks/workstations.yml`: baseline for dev/desktop/local + **desktop apps only on `desktop` group**

- **Monitoring split**
  - `roles/monitoring_server`: server monitoring + intrusion prevention (includes `fail2ban`, sysstat)
  - `roles/monitoring_desktop`: desktop-oriented monitoring tooling
  - Updated playbooks to use the correct monitoring role per host type

- **Shell role: server-safe + developer-friendly**
  - `roles/shell` now supports two modes:
    - `shell_mode: minimal` (default): aliases-only, does not overwrite `.zshrc`
    - `shell_mode: full`: installs Oh My Zsh + Powerlevel10k + plugins and deploys a managed `.zshrc`
  - `playbooks/development.yml` and `playbooks/workstations.yml` use `shell_mode: full`
  - `playbooks/servers.yml` remains **aliases-only**

- **Applications**
  - Applications role runs only on `desktop` group (via `workstations.yml`)
  - Removed Brave installs/repo management
  - Added **CopyQ** to desktop apps (`applications_desktop_packages`)

- **Docs + architecture**
  - Added canonical doc tree under `project-docs/` (overview/architecture/standards/workflow/decisions)
  - Consolidated architecture docs: `docs/reference/architecture.md` is now a pointer to `project-docs/architecture.md`
  - Fixed broken doc links by adding the missing referenced pages under `docs/`

### Behavior changes (important)

- Desktop GUI apps install **only** on the `desktop` inventory group (not on servers, not on dev VMs unless they are in `desktop`).
- Dev/workstation Zsh is now provisioned in **full mode** (managed `.zshrc` + p10k).

### How to test (local CI parity)

```bash
make test
npm test
```

Optional dry runs (interactive sudo may be required):

```bash
make check
make check-local
```

### Rollout guidance

- Apply to a single host first:
  - Workstations: `make workstations HOST=<devhost>`
  - Servers: `make servers HOST=<serverhost>`
- Then expand to group runs.

Reviewed-on: #4
2026-01-01 22:11:24 -05:00

2.6 KiB
Raw Permalink Blame History

Architecture

High-level map (modules and relationships)

  • Inventory: inventories/production/

    • hosts: groups like dev, desktop, services, qa, ansible, tailscale, local
    • group_vars/all/main.yml: shared configuration (including app_projects)
    • group_vars/all/vault.yml: encrypted secrets (Ansible Vault)
    • host_vars/*: per-host overrides (some encrypted)

  • Playbooks: playbooks/

    • playbooks/site.yml: dispatcher (imports other playbooks)
    • playbooks/servers.yml: baseline for servers (services:qa:ansible:tailscale)
    • playbooks/workstations.yml: baseline for dev:desktop:local + desktop apps for desktop group only
    • playbooks/development.yml: dev machines baseline (no desktop apps)
    • playbooks/local.yml: localhost baseline (no desktop apps)
    • playbooks/app/*: Proxmox app-project provisioning/configuration suite

  • Roles: roles/*

    • Baseline/security: base, user, ssh
    • Dev tooling: development, datascience, docker
    • Shell: shell (minimal aliases-only)
    • Monitoring split:
      • monitoring_server (fail2ban + sysstat)
      • monitoring_desktop (desktop-oriented monitoring tooling)
    • Proxmox guests: proxmox_vm
    • App guest configuration: base_os, app_setup, pote

Proxmox “app projects” flow (data model + execution)

  • Data model: app_projects in inventories/production/group_vars/all/main.yml

    • Defines projects and per-env (dev/qa/prod) guest parameters (ip, branch, vmid, etc.)

  • Provision: playbooks/app/provision_vms.yml

    • Loops app_projects → envs → calls role: proxmox_vm to create LXC guests
    • Adds dynamic inventory groups:
      • app_all
      • app_<project>_all
      • app_<project>_<env>

  • Configure: playbooks/app/configure_app.yml

    • Builds a dynamic inventory from app_projects (so it can run standalone)
    • Applies:
      • role: base_os (baseline OS for app guests)
      • role: app_setup (deploy + systemd) or role: pote for the POTE project

Boundaries

  • Inventory/vars define desired state and credentials.
  • Playbooks define “what path to run” (role ordering, target groups, tags).
  • Roles implement actual host configuration (idempotent tasks, handlers).

External dependencies

  • Ansible collections: collections/requirements.yml
  • Ansible Vault: inventories/production/group_vars/all/vault.yml
  • Proxmox API: used by community.proxmox.* modules in provisioning

References

  • Playbook execution graphs and tags: docs/reference/playbooks-and-tags.md
  • Legacy pointer (do not update): docs/reference/architecture.md → project-docs/architecture.md