feat: create Ansible playbook for single-node PicoClaw deployment (#1)

[addidea]

Description

Complete Ansible automation for deploying PicoClaw on any Linux board (ARM64, RISC-V, x86_64).

Closes #1

What's Included

✅ Ansible Playbook (playbooks/deploy-picclaw.yml)

• System dependencies (curl, wget, systemd, UFW)
• PicoClaw binary download (architecture auto-detected)
• System user creation (picclaw account)
• Directory structure (/opt, /etc, /var/lib)
• Configuration templating (Jinja2)
• Systemd service setup
• UFW firewall configuration
• Health check verification

✅ Configuration Templates (2 files)

1. picclaw_config.yaml.j2 - Agent config (Fleet URL, Telegram, logging)
2. picclaw.service.j2 - Systemd unit (security hardened)

✅ Inventory Example (inventory/picclaw.ini)

• Raspberry Pi example
• VPS example
• Multi-node example
• Global variables

✅ Complete Documentation (playbooks/README.md)

• Quick start (3 commands)
• Configuration variables
• Multi-node deployment
• Troubleshooting (5 scenarios)
• Architecture support
• Uninstallation guide

Features

Multi-Architecture:

• ARM64 (Raspberry Pi 4/5, ARM servers)
• RISC-V (VisionFive 2, Milk-V)
• x86_64 (Intel/AMD servers, VPS)

Security Hardening:

• System user with no login shell
• Read-only system directories (ProtectSystem=strict)
• Isolated /tmp (PrivateTmp=true)
• No privilege escalation (NoNewPrivileges=true)
• UFW firewall (deny all except SSH + app port)
• Resource limits (files, processes)

Idempotent:

• Safe to run multiple times
• Only changes what's needed
• Handlers trigger only on config changes

Reliable:

• Binary download with 3 retries
• Health check with 5 retries
• Automatic service restart on failure

Usage

Quick Deploy

# 1. Edit inventory
nano inventory/picclaw.ini

# 2. Run playbook
ansible-playbook -i inventory/picclaw.ini playbooks/deploy-picclaw.yml

# 3. Verify
ssh user@node 'systemctl status picclaw'

Multi-Node Deploy

# Deploy to 10 nodes in parallel
ansible-playbook -i inventory/picclaw.ini playbooks/deploy-picclaw.yml -f 10

Custom Variables

ansible-playbook -i inventory/picclaw.ini playbooks/deploy-picclaw.yml \
  -e "picclaw_port=9090" \
  -e "enable_firewall=false"

Systemd Service

Security hardening:

NoNewPrivileges=true       # No privilege escalation
PrivateTmp=true            # Isolated /tmp
ProtectSystem=strict       # Read-only system dirs
ProtectHome=true           # No /home access
ReadWritePaths=/var/lib    # Only data dir writable

Resource limits:

LimitNOFILE=65536          # File descriptors
LimitNPROC=512             # Processes

Restart behavior:

Restart=on-failure
RestartSec=10

Firewall (UFW)

Default rules:

• Allow: SSH (port 22)
• Allow: PicoClaw (port 8080)
• Deny: All other incoming

Disable with: -e "enable_firewall=false"

Directory Structure

/opt/picclaw/              # Binary
/etc/picclaw/              # Config
  └── config.yaml          # Generated from template
/var/lib/picclaw/          # Data
  └── logs/                # Log files
/etc/systemd/system/       # Service
  └── picclaw.service      # Generated from template

Testing

Verified on:

• ✅ Raspberry Pi 4B (ARM64, Ubuntu 22.04)
• ✅ VisionFive 2 (RISC-V, Debian 12)
• ✅ DigitalOcean Droplet (x86_64, Ubuntu 24.04)

Troubleshooting

Health check timeout:

sudo journalctl -u picclaw -n 50
curl -v http://localhost:8080/healthz

Binary download fails:

ansible-playbook ... -e "picclaw_binary_url=file:///path/to/binary"

Permission denied:

ansible-playbook ... --ask-become-pass

Next Steps

• Add rollback playbook
• Support multi-node clusters
• Add monitoring stack (Prometheus + Grafana)
• Create pre-built SD card images

Production-ready automation! 🚀