added the a preparing ansible playbooks for automating new servers

docs/AnsiblePlaybooks.md

@@ -1,6 +1,6 @@
 # Ansible Playbooks
 
-How updates get applied across the homelab: one shared role, one thin playbook per stack, triggered through Semaphore.
+How updates get applied across the homelab: one shared role, one thin playbook per stack, triggered through Semaphore. A separate provisioning playbook handles fresh server setup.
 
 ## Why
 
@@ -10,29 +10,47 @@ Updating each Docker Compose stack by hand — SSH in, `cd` into the folder, `do
 
 ```
 ansible/
-└── playbooks/
-    ├── roles/
-    │   └── docker_compose_update/
-    │       └── tasks/
-    │           └── main.yml       # the shared update logic
-    ├── update-filebrowser.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
-    ├── update-agent-canvas.yml
-    ├── update-grafana.yml
-    └── ping.yml
+├── README.md                                  # full directory documentation
+├── update-playbooks/                          # day-to-day stack updates
+│   ├── roles/
+│   │   └── docker_compose_update/
+│   │       └── tasks/main.yml                 # the shared update logic
+│   ├── update-filebrowser.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
+│   ├── update-agent-canvas.yml
+│   ├── update-grafana.yml
+│   └── ping.yml
+│
+└── preparing-playbook/                        # one-time server provisioning
+    └── reza-ansible/
+        ├── ansible.cfg
+        ├── preparing.yaml                     # harden + Docker install
+        ├── repo-server.yaml                   # Nexus + Traefik setup
+        ├── inventory/
+        │   ├── host.yaml
+        │   ├── group_vars/all/                # shared variables
+        │   └── host_vars/vagrant-test.yaml    # Vagrant overrides
+        └── roles/
+            ├── preparing_server/              # packages, sshd, iptables, auditd, lynis
+            ├── docker/                        # Docker CE + Compose plugin
+            └── repo-server/                   # Nexus3 + Traefik + registry
 ```
 
+See the [ansible/ README](../ansible/README.md) for the full breakdown of every file and role.
+
+## update-playbooks — how it works
+
 One role, reused by every playbook. Each playbook is intentionally tiny:
 
 ```yaml
@@ -64,7 +82,27 @@ Adding a new stack means adding a new playbook like the one above — no changes
 
 If any step fails (a bad pull, a container that won't start), Ansible stops the play immediately rather than continuing on to prune images out from under a broken deployment.
 
-## Running it via Semaphore
+## 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. See the [ansible/ README](../ansible/README.md) for details on each role.
+
+### `preparing.yaml`
+
+Runs two roles: **preparing_server** (packages, sshd, iptables, fail2ban, auditd, sysctl, lynis) then **docker** (Docker CE + Compose plugin install + daemon config).
+
+### `repo-server.yaml`
+
+Runs the **repo-server** role — pulls and configures Nexus3, Traefik, and a Docker registry as a self-hosted artifact repository.
+
+### Running locally
+
+```bash
+cd ansible/preparing-playbook/reza-ansible
+ansible-playbook preparing.yaml -i inventory/host.yaml
+ansible-playbook repo-server.yaml -i inventory/host.yaml
+```
+
+## Running via Semaphore
 
 Semaphore ([see Semaphore Guide](Semaphore.md)) is what actually executes these — no manual `ansible-playbook` on the server. Each playbook is set up as a Task Template pointed at this repo, so updating a stack is a matter of picking its template and hitting run.
 
@@ -77,5 +115,6 @@ The Semaphore dashboard gives a quick visual of run history — successes in gre
 - Keeping the update logic in a single role instead of copy-pasting it into every playbook means a fix or improvement (like the disk-usage snapshots) only has to happen once — see the role's own history for an example of that in practice.
 - The `docker system df` before/after comparison earns its place: it's what made an unexpectedly large image pull for OpenHands/Ollama visible immediately, instead of just being a mystery bandwidth spike after the fact.
 - The health-check assert before pruning matters — pruning images out from under a stack that failed to come back up would make debugging (and rolling back) harder, not easier.
+- Testing provisioning playbooks against a disposable Vagrant VM first catches issues like sshd port mismatches and iptables misconfigurations before they lock you out of real hardware.
 
 [← Back to Home](Home.md)