username/ppf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update CLAUDE.md for playbook-based deployment

Browse Source 
Document WireGuard connectivity, playbook architecture, --check
flag, parallel execution, and updated ad-hoc ansible commands
using toolkit inventory.
This commit is contained in:
Username
2026-02-17 23:19:54 +01:00
parent df2078c7f7
commit b1de91a969
1 changed files with 33 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
CLAUDE.md
View File

@@ -37,30 +37,47 @@ All deployment and service management is handled by `tools/`:
``` ```
tools/ tools/
lib/ppf-common.sh shared library (hosts, wrappers, colors) lib/ppf-common.sh shared library (hosts, wrappers, colors)
ppf-deploy deploy code to nodes ppf-deploy deploy wrapper (local validation + playbook)
ppf-logs view container logs ppf-logs view container logs
ppf-service manage containers (status/start/stop/restart) ppf-service manage containers (status/start/stop/restart)
playbooks/
deploy.yml ansible playbook (sync, compose, restart)
inventory.ini hosts with WireGuard IPs + SSH key
group_vars/
all.yml shared vars (ppf_base, ppf_owner)
master.yml odin paths + compose file
workers.yml worker paths + compose file
``` ```
Symlinked to `~/.local/bin/` for direct use. Symlinked to `~/.local/bin/` for direct use.
### Connectivity
All tools connect over WireGuard (`10.200.1.0/24`) as user `ansible`
with the SSH key at `/opt/ansible/secrets/ssh/ansible`.
### Deployment ### Deployment
`ppf-deploy` validates syntax locally, then runs the Ansible playbook.
Hosts execute in parallel; containers restart only when files change.
```bash ```bash
ppf-deploy # all nodes: validate, sync, restart ppf-deploy # all nodes: validate, sync, restart
ppf-deploy odin # master only ppf-deploy odin # master only
ppf-deploy workers # cassius, edge, sentinel ppf-deploy workers # cassius, edge, sentinel
ppf-deploy cassius edge # specific hosts ppf-deploy cassius edge # specific hosts
ppf-deploy --no-restart # sync only, skip restart ppf-deploy --no-restart # sync only, skip restart
ppf-deploy --check # dry run (ansible --check --diff)
ppf-deploy -v # verbose ansible output
``` ```
Steps performed automatically: Playbook steps (per host, in parallel):
1. Validate Python syntax locally 1. Rsync `*.py` + `servers.txt` (role-aware destination via group_vars)
2. Rsync `*.py` + `servers.txt` (root for odin, `src/` for workers) 2. Copy compose file per role (`compose.master.yml` / `compose.worker.yml`)
3. Copy compose file per role (`compose.master.yml` / `compose.worker.yml`) 3. Fix ownership (`podman:podman`, recursive)
4. Fix ownership (`chown -R podman:podman`) 4. Restart containers via handler (only if files changed)
5. Restart containers and show status 5. Show container status
### Container Logs ### Container Logs
@@ -83,19 +100,19 @@ ppf-service start workers # start all workers
### Direct Ansible (for operations not covered by tools) ### Direct Ansible (for operations not covered by tools)
Tools use `/opt/ansible` venv and `ANSIBLE_REMOTE_TMP=/tmp/.ansible` Use the toolkit inventory for ad-hoc commands over WireGuard:
internally. For ad-hoc operations:
```bash ```bash
cd /opt/ansible && source venv/bin/activate cd /opt/ansible && source venv/bin/activate
INV=/home/user/git/ppf/tools/playbooks/inventory.ini
# Check worker config # Check worker config
ANSIBLE_REMOTE_TMP=/tmp/.ansible ansible cassius,edge,sentinel \ ansible -i $INV workers -m shell \
-m shell -a "grep -E 'threads|timeout|ssl' /home/podman/ppf/config.ini" -a "grep -E 'threads|timeout|ssl' /home/podman/ppf/config.ini"
# Modify config option # Modify config option
ANSIBLE_REMOTE_TMP=/tmp/.ansible ansible cassius,edge,sentinel \ ansible -i $INV workers -m lineinfile \
-m lineinfile -a "path=/home/podman/ppf/config.ini line='ssl_only = 1' insertafter='ssl_first'" -a "path=/home/podman/ppf/config.ini line='ssl_only = 1' insertafter='ssl_first'"
``` ```
## Podman User IDs ## Podman User IDs