feat: Add paperclip-docker Ansible role for RTX 3090

Deploy Paperclip AI with PostgreSQL, nginx reverse proxy, and Cloudflare
SSL/TLS on illuminations.wdw-labs.cloud. Configured for local_trusted
mode (LAN-only, no auth) with host networking and auto-generated secrets.

Stack: PostgreSQL 16 + Paperclip + nginx + certbot
Hostname: muppet-vision.wdw-labs.cloud
vLLM endpoint: localhost:8000 (DeepSeek-R1-32B Q4)

ansible/roles/paperclip-docker/INSTALLATION.md

@@ -0,0 +1,191 @@
+# Installation Guide - Paperclip Docker Role
+
+## File Placement
+
+Copy the files from this directory to your ansible repo as follows:
+
+### Role Files
+
+Create the role directory structure:
+
+```bash
+mkdir -p roles/paperclip-docker/{defaults,handlers,tasks,templates}
+```
+
+Then copy:
+
+| From | To |
+|------|-----|
+| `defaults_main.yml` | `roles/paperclip-docker/defaults/main.yml` |
+| `handlers_main.yml` | `roles/paperclip-docker/handlers/main.yml` |
+| `tasks_main.yml` | `roles/paperclip-docker/tasks/main.yml` |
+| `docker-compose.yml.j2` | `roles/paperclip-docker/templates/docker-compose.yml.j2` |
+| `nginx.conf.j2` | `roles/paperclip-docker/templates/nginx.conf.j2` |
+| `certbot-init.sh.j2` | `roles/paperclip-docker/templates/certbot-init.sh.j2` |
+| `README.md` | `roles/paperclip-docker/README.md` |
+
+### Host Variables
+
+Create the host directory:
+
+```bash
+mkdir -p host_vars/illuminations.wdw-labs.cloud
+```
+
+Then copy:
+
+| From | To |
+|------|-----|
+| `host_vars_illuminations.yml` | `host_vars/illuminations.wdw-labs.cloud/vars.yml` |
+
+### Playbook
+
+Copy:
+
+| From | To |
+|------|-----|
+| `deploy_paperclip_stack.yml` | `playbooks/deploy_paperclip_stack.yml` |
+
+## Complete Installation Command
+
+```bash
+# From your ansible repo root
+
+# Create directories
+mkdir -p roles/paperclip-docker/{defaults,handlers,tasks,templates}
+mkdir -p host_vars/illuminations.wdw-labs.cloud
+
+# Copy files (adjust path to where you downloaded them)
+cp /path/to/defaults_main.yml roles/paperclip-docker/defaults/main.yml
+cp /path/to/handlers_main.yml roles/paperclip-docker/handlers/main.yml
+cp /path/to/tasks_main.yml roles/paperclip-docker/tasks/main.yml
+cp /path/to/docker-compose.yml.j2 roles/paperclip-docker/templates/
+cp /path/to/nginx.conf.j2 roles/paperclip-docker/templates/
+cp /path/to/certbot-init.sh.j2 roles/paperclip-docker/templates/
+cp /path/to/README.md roles/paperclip-docker/
+cp /path/to/host_vars_illuminations.yml host_vars/illuminations.wdw-labs.cloud/vars.yml
+cp /path/to/deploy_paperclip_stack.yml playbooks/
+
+# Verify structure
+tree roles/paperclip-docker
+tree host_vars/illuminations.wdw-labs.cloud
+ls -la playbooks/deploy_paperclip_stack.yml
+```
+
+## Final Directory Structure
+
+After installation, your ansible repo should have:
+
+```
+.
+├── roles/
+│   └── paperclip-docker/
+│       ├── README.md
+│       ├── defaults/
+│       │   └── main.yml
+│       ├── handlers/
+│       │   └── main.yml
+│       ├── tasks/
+│       │   └── main.yml
+│       └── templates/
+│           ├── certbot-init.sh.j2
+│           ├── docker-compose.yml.j2
+│           └── nginx.conf.j2
+├── playbooks/
+│   ├── deploy_paperclip_stack.yml
+│   └── (other existing playbooks)
+├── host_vars/
+│   ├── illuminations.wdw-labs.cloud/
+│   │   └── vars.yml
+│   └── (other existing host vars)
+├── group_vars/
+│   └── (existing group vars)
+├── inventory.yml
+├── ansible.cfg
+└── (other existing files)
+```
+
+## Next Steps
+
+1. **Copy the files** as described above
+2. **Review variables** in `host_vars/illuminations.wdw-labs.cloud/vars.yml` - update if needed
+3. **Verify vault** contains `vault_cloudflare_api_token`
+4. **Test connectivity**:
+   ```bash
+   ansible -i inventory.yml illuminations.wdw-labs.cloud -m ping
+   ```
+5. **Run the playbook**:
+   ```bash
+   ansible-playbook playbooks/deploy_paperclip_stack.yml -i inventory.yml -K
+   ```
+   (The `-K` prompts for become password)
+
+**Note:** The playbook automatically calls the `docker-host` role first to ensure Docker is installed. No manual Docker setup needed.
+
+## Verification After Installation
+
+```bash
+# Verify the role exists
+ls -la roles/paperclip-docker/
+
+# Verify host vars exist
+cat host_vars/illuminations.wdw-labs.cloud/vars.yml
+
+# Verify playbook exists
+cat playbooks/deploy_paperclip_stack.yml
+
+# Test syntax
+ansible-playbook playbooks/deploy_paperclip_stack.yml --syntax-check
+
+# Dry run
+ansible-playbook playbooks/deploy_paperclip_stack.yml -i inventory.yml --check
+```
+
+## Troubleshooting Installation
+
+### Role not found error
+```
+ERROR! the role 'paperclip-docker' was not found
+```
+
+**Solution:** Ensure `roles/paperclip-docker/` exists with `tasks/main.yml` inside.
+
+### Template not found error
+```
+ERROR! Unable to find template paperclip-docker/docker-compose.yml.j2
+```
+
+**Solution:** Ensure templates are in `roles/paperclip-docker/templates/` with `.j2` extension.
+
+### Vault variable not found
+```
+fatal: [illuminations]: FAILED! => error: Undefined variable: vault_cloudflare_api_token
+```
+
+**Solution:** Ensure `vault_cloudflare_api_token` is defined in your vault file:
+```bash
+ansible-vault view group_vars/all/vault
+```
+
+### Host not in inventory
+```
+ERROR! Unable to parse illuminations.wdw-labs.cloud as an inventory address
+```
+
+**Solution:** Ensure your `inventory.yml` contains the host:
+```yaml
+all:
+  hosts:
+    illuminations.wdw-labs.cloud:
+      ansible_host: <ip_address>
+```
+
+## Files Reference
+
+All files are self-contained and ready to use. No modifications needed unless:
+
+- You want to change the domain (edit `host_vars/illuminations.wdw-labs.cloud/vars.yml`)
+- You want to change ports (edit `roles/paperclip-docker/defaults/main.yml`)
+- You want to change the certbot email (edit host_vars)
+
+For complete documentation, see `roles/paperclip-docker/README.md` after installation.