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:

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:

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

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

   ansible -i inventory.yml illuminations.wdw-labs.cloud -m ping
   

5. Run the playbook:

   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

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

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:

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.