created new role

README.md

@@ -33,18 +33,35 @@ does.
 ## Layout
 
 ```
-playbook.yml               Ansible deployment (hosts: webservers)
-inventory.ini              Inventory (localhost + commented remote example)
-trade-hub/
-  podman-compose.yml       Local three-service stack (db + backend + frontend)
-  backend/                 FastAPI app, tests, data fetch script, Dockerfile
-  frontend/                nginx config + static inventory UI
+playbook.yml                     Example play using the role (hosts: webservers)
+inventory.ini                    Inventory (localhost + commented remote example)
+teardown.yml                     Removes this project's containers and data
+roles/trade_hub/
+  README.md                      Role usage and variables
+  defaults/main.yml              Configurable defaults
+  tasks/main.yml                 Stage source, build images, run containers
+  files/trade-hub/
+    podman-compose.yml           Local three-service stack (db + backend + frontend)
+    backend/                     FastAPI app, tests, data fetch script, Dockerfile
+    frontend/                    nginx config + static inventory UI
 ```
 
+The Ansible deployment is a self-contained role. To deploy it from an existing
+playbook, copy `roles/trade_hub` into that repository's `roles/` directory and
+add the role to the play:
+
+```yaml
+    - role: trade_hub
+      tags: [trade_hub]
+```
+
+See `roles/trade_hub/README.md` for the variables. The play-level `become: true`
+used by a typical server play makes podman run as root.
+
 ## Run locally with Podman Compose
 
 ```bash
-cd trade-hub
+cd roles/trade_hub/files/trade-hub
 podman-compose up -d --build
 # or: podman compose up -d --build
 ```
@@ -60,7 +77,8 @@ POSTGRES_PASSWORD='choose-something-strong' podman-compose up -d --build
 
 ## Deploy with Ansible
 
-Deploys to every host in the `webservers` group (defaults to localhost):
+The example play deploys the role to every host in the `webservers` group
+(defaults to localhost):
 
 ```bash
 POSTGRES_PASSWORD='choose-something-strong' ansible-playbook playbook.yml
@@ -73,16 +91,22 @@ To deploy to a remote server, edit `inventory.ini`:
 server1 ansible_host=203.0.113.10 ansible_user=deploy
 ```
 
-Then run the same command from this directory. The playbook:
+Then run the same command from this directory. The role:
 
-1. installs podman if missing,
-2. removes the legacy `my-apache-server` container if present,
-3. builds `sc-inventory-backend` / `sc-inventory-frontend` images (skipped when
-   they already exist; set `-e force_rebuild=true` to rebuild),
+1. installs podman if missing (only when `trade_hub_install_podman: true`),
+2. optionally removes the legacy `my-apache-server` container
+   (`trade_hub_remove_legacy_apache: true`),
+3. stages the application source in `/opt/trade-hub` and builds the
+   `sc-inventory-backend` / `sc-inventory-frontend` images (skipped when the
+   source is unchanged and the images already exist; set
+   `-e trade_hub_force_rebuild=true` to force it),
 4. creates the `sc-inventory` podman network and the `sc-inventory-data` volume,
 5. runs PostgreSQL, the backend, and the frontend containers (only the frontend
    publishes a port: 8080),
-6. verifies `http://localhost:8080/healthz` returns 200.
+6. verifies `http://127.0.0.1:8080/healthz` returns 200.
+
+The old standalone playbook's variables (`force_rebuild`, `cookie_secure`, …)
+became `trade_hub_*` variables; see `roles/trade_hub/README.md`.
 
 ## Reset for testing (remove everything)
 
@@ -165,7 +189,8 @@ The stack publishes plain HTTP on port 8080. Session cookies therefore travel
 in cleartext, and `COOKIE_SECURE` defaults to `false` so local development works.
 Before putting this on the open internet, terminate TLS in front of the
 frontend (Caddy, nginx with certificates, or a load balancer) and set
-`COOKIE_SECURE=true` (compose env var) or `-e cookie_secure=true` (Ansible).
+`COOKIE_SECURE=true` (compose env var) or
+`-e trade_hub_cookie_secure=true` (Ansible).
 Also change `POSTGRES_PASSWORD` from its development default.
 
 ## Verify
@@ -195,7 +220,7 @@ curl -fsS -b cookies.txt http://localhost:8080/api/v1/me/inventory
 ## Backend development
 
 ```bash
-cd trade-hub/backend
+cd roles/trade_hub/files/trade-hub/backend
 python3 -m venv .venv
 .venv/bin/pip install -r requirements.txt -r requirements-dev.txt
 .venv/bin/python -m pytest tests/ -q          # 83 tests, no database needed