Refactor user management in Ansible playbooks to standardize on keeper_user

- Updated user addition tasks across multiple playbooks (mcp_switchboard, mcpo, neo4j, neo4j_mcp, openwebui, postgresql, rabbitmq, searxng, smtp4dev) to replace references to ansible_user and remote_user with keeper_user.
- Modified PostgreSQL deployment to create directories and manage files under keeper_user's home.
- Enhanced documentation to clarify account taxonomy and usage of keeper_user in playbooks.
- Introduced new deployment for Agent S, including environment setup, desktop environment installation, XRDP configuration, and accessibility support.
- Added staging playbook for preparing release tarballs from local repositories.
- Created templates for XRDP configuration and environment activation scripts.
- Removed obsolete sunwait documentation.
This commit is contained in:
2026-03-05 10:37:41 +00:00
parent b4d60f2f38
commit 042df52bca
35 changed files with 610 additions and 298 deletions

View File

@@ -522,6 +522,69 @@ ansible-playbook myapp/deploy.yml
- [Ansible Vault Guide](https://docs.ansible.com/ansible/latest/vault_guide/index.html)
- [Inventory Organization](https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html)
## Account Taxonomy
Standardized account roles used across Ansible and Terraform. This taxonomy eliminates confusion between Ansible reserved connection keywords (`remote_user` in `ansible.cfg`) and infrastructure-managed account variables in playbooks.
| Role | Variable | Example | Home | Sudo | Purpose |
|------|----------|---------|------|------|---------|
| user | *(login name)* | robert:1000 | /home/robert | varies | Human user account |
| service_user | `{service}_user` | arke:500 | /srv/arke | no | Service daemon account |
| keeper_user | `keeper_user` | ponos:519 | /srv/ponos | yes | Ansible/Terraform management (sudo) |
| watcher_user | `watcher_user` | poros:520 | — | no | Non-sudo observation account |
| principal_user | `principal_user` | robert:1000 | /home/robert | varies | AI agent collaborative account |
### Key Rules
- **`keeper_user`** replaces all uses of `{{ ansible_user }}` and `{{ remote_user }}` as Jinja2 variables in playbooks
- **`ansible.cfg`** retains `remote_user = ponos` as the SSH connection keyword (Ansible built-in) — this is not a Jinja2 variable
- **`service_user`** accounts live in `/srv/{service}` — if currently in `/home`, they migrate on next re-provision
- **`watcher_user`** is provisioned by Ansible playbook when needed (not via cloud-init)
- **`principal_user`** is for AI agent hosts where the agent operates on behalf of a human user; define in `host_vars/{hostname}.yml`
- Do **not** use `vault_` prefix for any of these — that prefix is reserved for Ansible Vault variables
### Variable Definitions
All taxonomy variables are defined in `inventory/group_vars/all/vars.yml`:
```yaml
# Account Taxonomy
keeper_user: ponos
keeper_uid: 519
keeper_group: ponos
keeper_home: /srv/ponos
watcher_user: poros
watcher_uid: 520
```
`principal_user` is host-specific and defined in the relevant `host_vars` file:
```yaml
# inventory/host_vars/caliban.incus.yml
principal_user: robert
principal_uid: 1000
```
### Bootstrap Chain
1. **Terraform** provisions `ponos` (keeper_user) on all containers via `cloud-init`
- UID 519, home `/srv/ponos`, sudoers, SSH authorized keys at `/srv/ponos/.ssh/authorized_keys`
2. **`ansible.cfg`** sets `remote_user = ponos` so all Ansible connections use the keeper account
3. **Playbooks** reference `{{ keeper_user }}` for any task that needs the management account name
### Playbook Pattern
```yaml
- name: Add keeper_user to service group
become: true
ansible.builtin.user:
name: "{{ keeper_user }}"
groups: "{{ service_group }}"
append: true
```
**Never use** `{{ ansible_user }}` or `{{ remote_user }}` as Jinja2 template variables in tasks — these shadow Ansible built-in connection variables and cause unpredictable behaviour.
## Secret Management Patterns
### Ansible Vault (Sandbox Environment)