homelab/ansible/roles/paperclip-docker/INSTALLATION.md

# 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.