added trade-hub role and files

roles/trade_hub/README.md

@@ -0,0 +1,82 @@
+# trade_hub
+
+Deploys the Free People of the Verse trade hub: a FastAPI backend, an nginx
+frontend and PostgreSQL, all run by podman on the target host. The role stages
+its own copy of the application source from `files/trade-hub/` and builds the
+backend and frontend images locally, so it does not need a registry.
+
+## Usage
+
+Add the role to an existing play. It is safe to run after a `packages` role that
+already installs podman:
+
+```yaml
+- hosts: internal-apps
+  become: true
+  vars_files:
+    - ./vars.yml
+  roles:
+    - role: packages
+      tags: [packages]
+    # ...
+    - role: trade_hub
+      tags: [trade_hub]
+```
+
+The play-level `become: true` makes podman run as root. If you run the role
+without become, podman runs rootless and the containers belong to the connecting
+user.
+
+The playbook's `Pull images` task is unrelated to this role: the role builds its
+own backend/frontend images from the staged source. The PostgreSQL image is
+pulled by the role if it is not already present.
+
+## Required variables
+
+Set a real database password in `vars.yml` (or the environment of the control
+node):
+
+```yaml
+trade_hub_postgres_password: "choose-something-strong"
+```
+
+If it is omitted, the role falls back to `POSTGRES_PASSWORD` from the control
+node environment, then to the development default `sc_inventory_dev`.
+
+## Common variables
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `trade_hub_app_dir` | `/opt/trade-hub` | Where the build context is staged |
+| `trade_hub_install_podman` | `false` | Install podman if it is missing |
+| `trade_hub_build_images` | `true` | Build backend/frontend images on the target |
+| `trade_hub_force_rebuild` | `false` | Rebuild images and restart containers |
+| `trade_hub_image_tag` | `latest` | Tag applied to built images |
+| `trade_hub_backend_image` | `localhost/sc-inventory-backend` | Backend image name |
+| `trade_hub_frontend_image` | `localhost/sc-inventory-frontend` | Frontend image name |
+| `trade_hub_postgres_image` | `docker.io/library/postgres:16-alpine` | Database image |
+| `trade_hub_postgres_user` | `sc_inventory` | Database user |
+| `trade_hub_postgres_db` | `sc_inventory` | Database name |
+| `trade_hub_postgres_password` | env `POSTGRES_PASSWORD` or `sc_inventory_dev` | Database password |
+| `trade_hub_network` | `sc-inventory` | Podman network name |
+| `trade_hub_volume` | `sc-inventory-data` | PostgreSQL data volume |
+| `trade_hub_frontend_bind` | `0.0.0.0` | Address the frontend publishes on |
+| `trade_hub_frontend_port` | `8080` | Host port for the frontend |
+| `trade_hub_cookie_secure` | `false` | Mark session cookies `Secure` (enable behind TLS) |
+| `trade_hub_healthcheck_url` | `http://127.0.0.1:<port>/healthz` | Post-deploy check |
+| `trade_hub_remove_legacy_apache` | `false` | Remove a container named `my-apache-server` |
+| `trade_hub_enable_restart_service` | `false` | Enable `podman-restart.service` |
+
+The container names also default to `sc-inventory-db`, `sc-inventory-backend`
+and `sc-inventory-frontend`, matching the previous standalone playbook so an
+existing installation is upgraded in place.
+
+## Example deployment
+
+```bash
+ansible-playbook site.yml --tags trade_hub -e trade_hub_postgres_password='...'
+```
+
+The role verifies `http://127.0.0.1:8080/healthz` after starting the containers.
+Only the frontend publishes a port; the database and backend stay on the
+internal podman network.