fpov-exchange/roles/trade_hub/README.md

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:

- 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):

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

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.