# Ansible

Two playbooks families live here: one for **updating** Docker Compose stacks day-to-day, and one for **provisioning** a fresh server from scratch. Both are designed to run through [Semaphore](../docs/Semaphore.md).

## Directory structure

```
ansible/
├── update-playbooks/              # day-to-day Docker Compose stack updates
│   ├── roles/
│   │   └── docker_compose_update/
│   │       ├── defaults/          # role defaults (currently empty — vars come from playbooks)
│   │       └── tasks/
│   │           └── main.yml       # shared pull → recreate → health-check → prune logic
│   ├── ping.yml                   # connectivity check
│   ├── update-agent-canvas.yml
│   ├── update-filebrowser.yml
│   ├── update-grafana.yml
│   ├── update-n8n.yml
│   ├── update-npm.yml
│   ├── update-pihole.yml
│   ├── update-plex.yml
│   ├── update-portainer.yml
│   ├── update-prowlarr.yml
│   ├── update-radarr.yml
│   ├── update-samba.yml
│   ├── update-sentinel.yml
│   ├── update-smartctl.yml
│   ├── update-sonarr.yml
│   └── update-whisparr.yml
│
└── preparing-playbook/            # one-time server provisioning (learning lab / Vagrant testing)
    └── reza-ansible/
        ├── ansible.cfg
        ├── preparing.yaml         # playbook: harden + Docker install
        ├── repo-server.yaml       # playbook: Nexus + Traefik repo server
        ├── .vault.pass            # ⚠️  gitignored — must be created locally
        ├── inventory/
        │   ├── host.yaml          # inventory — hosts and connection details
        │   ├── group_vars/
        │   │   └── all/
        │   │       ├── preparing.yaml   # packages, sshd, iptables, sysctl, auditd
        │   │       ├── docker.yaml      # Docker daemon config (proxy, registry mirror)
        │   │       ├── proxy.yaml       # HTTP proxy credentials
        │   │       ├── repo-server.yaml # Nexus/Traefik/domain config
        │   │       ├── backup.yaml      # backup volume/path config
        │   │       └── vault.yaml       # 🔒 Ansible Vault encrypted secrets
        │   └── host_vars/
        │       └── vagrant-test.yaml    # Vagrant-specific overrides
        └── roles/
            ├── preparing_server/        # packages, sshd, iptables, fail2ban, auditd, lynis, sysctl
            ├── docker/                  # Docker CE + Compose plugin install + daemon config
            └── repo-server/             # Nexus3 + Traefik + Docker registry setup
```

## update-playbooks — how it works

Every always-on Docker Compose stack has a thin playbook that delegates to the shared `docker_compose_update` role. Each playbook is intentionally minimal:

```yaml
---
- hosts: all
  become: true
  vars:
    compose_dir: "/home/rezayaghobi/docker/<service>"
    service_name: "<Friendly Name>"
  roles:
    - docker_compose_update
```

The shared role runs the same sequence for every stack:

1. **Records start time** for a duration summary
2. **Snapshots `docker system df`** before the pull
3. **Runs `docker compose pull`** in the stack's directory
4. **Snapshots `docker system df`** again — before/after comparison catches unexpectedly large pulls
5. **Runs `docker compose up -d`** to recreate containers with new images
6. **Waits 5 seconds**, then checks `docker compose ps`
7. **Asserts every container is up** — fails the run (and skips cleanup) if anything shows `Exit`, `Created`, or `Restarting`
8. **Runs `docker image prune -f`** to reclaim space — only if the health check passed
9. **Prints a summary** — duration, cleanup result, pass/fail

If any step fails, Ansible stops immediately rather than continuing to prune images out from under a broken deployment.

### Adding a new stack

Copy any existing playbook, change `compose_dir` and `service_name`. No changes to the role itself.

## preparing-playbook — server provisioning

A full server preparation pipeline for fresh Ubuntu/Debian installs, designed for testing against the Vagrant VM before running on real hardware.

### `preparing.yaml`

Runs two roles in sequence:

1. **`preparing_server`** — installs base packages, configures sshd, sets up iptables rules, enables fail2ban, configures auditd, tunes sysctl, installs lynis for security auditing
2. **`docker`** — installs Docker CE + Compose plugin from Docker's official repo, configures daemon with proxy/mirror settings

### `repo-server.yaml`

Runs the **`repo-server`** role — pulls Nexus3, Traefik, and supporting images, then configures and starts them as a self-hosted artifact repository with TLS via Traefik.

### Inventory

- `inventory/host.yaml` — defines the `repo-servers` group (currently just `vagrant-test` on `127.0.0.1:2222`)
- `inventory/group_vars/all/` — shared variables for all hosts
- `inventory/host_vars/vagrant-test.yaml` — Vagrant-specific overrides (sshd port, iptables trusted ranges)

### Running locally against Vagrant

```bash
cd ansible/preparing-playbook/reza-ansible

# provision the server (packages + hardening + Docker)
ansible-playbook preparing.yaml -i inventory/host.yaml

# set up the repo server (Nexus + Traefik)
ansible-playbook repo-server.yaml -i inventory/host.yaml

# connectivity check only
ansible all -m ping -i inventory/host.yaml
```

## ⚠️ Before pushing to GitHub

The `preparing-playbook/` contains hardcoded credentials and personal infrastructure details that must be sanitized before making this repo public:

| File | Contains | What to do |
|---|---|---|
| `.vault.pass` | Plaintext vault password | Already in `.gitignore` — must be recreated locally |
| `group_vars/all/vault.yaml` | Encrypted secrets | Safe to commit (Ansible Vault encrypted) |
| `group_vars/all/proxy.yaml` | Proxy username + password in plaintext | Move credentials to `vault.yaml`, reference as `{{ vault_proxy_user }}:{{ vault_proxy_pass }}` |
| `group_vars/all/docker.yaml` | Proxy IP, registry mirror URL | Replace with `{{ vault_docker_proxy }}` / `{{ vault_registry_mirror }}` |
| `group_vars/all/preparing.yaml` | Trusted IP addresses | Replace with `{{ vault_trusted_ips }}` |
| `group_vars/all/repo-server.yaml` | Domain name, emails, usernames | Replace with vault variables |
| `inventory/host.yaml` | SSH key file path | Replace with `{{ vault_ssh_key_path }}` or a generic path |

The **update-playbooks/** are safe as-is — they only contain `compose_dir` paths with the local username and `service_name` labels.

## Running via Semaphore

Both playbook families are executed through [Semaphore](../docs/Semaphore.md) — no manual `ansible-playbook` on the server. Each playbook is set up as a Task Template pointed at this repo. See [Ansible Playbooks](../docs/AnsiblePlaybooks.md) for the full workflow and the [Semaphore Guide](../docs/Semaphore.md) for setup details.

[← Back to Home](../docs/Home.md)