# 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 the play variable `POSTGRES_PASSWORD`,
then to `POSTGRES_PASSWORD` from the control node environment, then to the
development default `sc_inventory_dev`. If the password contains characters
that are significant in a URL (`@`, `:`, `/`, …), set `trade_hub_database_url`
explicitly as well.

## 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` | play var/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.