init test commit

2026-11-10 20:36:01 -07:00
commit 8693b3bd8d
42 changed files with 311150 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,99 @@
+# Star Citizen Inventory
+
+A read-only item inventory website for Star Citizen players, built from the
+[scunpacked](https://github.com/richardthombs/scunpacked) game data (mirrored at
+[StarCitizenWiki/scunpacked-data](https://github.com/StarCitizenWiki/scunpacked-data)).
+
+Ships, ship equipment, and FPS items are browsable with search, manufacturer /
+type / size filters, pagination, and a detail view per item.
+
+## Stack
+
+| Piece    | Tech                                   | Role                                            |
+| -------- | -------------------------------------- | ----------------------------------------------- |
+| backend  | FastAPI (python:3.12-slim container)   | Serves normalized scunpacked JSON over `/api/v1` |
+| frontend | nginx:1.27-alpine + vanilla JS/CSS     | Inventory UI; proxies `/api/` and `/healthz`      |
+| deploy   | Ansible + Podman (containers.podman)   | Builds images and runs the two containers       |
+
+The backend image downloads the full scunpacked dataset (~83 MB) at build time,
+so no database is needed — the inventory is read-only game data.
+
+## Layout
+
+```
+playbook.yml               Ansible deployment (hosts: webservers)
+inventory.ini              Inventory (localhost + commented remote example)
+trade-hub/
+  podman-compose.yml       Local two-service stack (backend + frontend)
+  backend/                 FastAPI app, tests, data fetch script, Dockerfile
+  frontend/                nginx config + static inventory UI
+```
+
+## Run locally with Podman Compose
+
+```bash
+cd trade-hub
+podman-compose up -d --build
+# or: podman compose up -d --build
+```
+
+Then open http://localhost:8080
+
+## Deploy with Ansible
+
+Deploys to every host in the `webservers` group (defaults to localhost):
+
+```bash
+ansible-playbook playbook.yml
+```
+
+To deploy to a remote server, edit `inventory.ini`:
+
+```ini
+[webservers]
+server1 ansible_host=203.0.113.10 ansible_user=deploy
+```
+
+Then run the same command from this directory. The playbook:
+
+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),
+4. creates the `sc-inventory` podman network,
+5. runs both containers (only the frontend publishes a port: 8080),
+6. verifies `http://localhost:8080/healthz` returns 200.
+
+## Verify
+
+```bash
+curl -fsS http://localhost:8080/healthz
+curl -fsS http://localhost:8080/api/v1/stats
+curl -fsS "http://localhost:8080/api/v1/items?search=carrack"
+```
+
+## Backend development
+
+```bash
+cd 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          # 19 tests
+DATA_DIR=./data/samples .venv/bin/uvicorn main:app --port 8000
+```
+
+- `data/samples/` — small real-schema subset for local dev/tests
+- `scripts/fetch_data.py` — downloads the full dataset (used by the Dockerfile)
+
+## API
+
+```
+GET /healthz
+GET /api/v1/stats
+GET /api/v1/manufacturers
+GET /api/v1/items?category=&search=&manufacturer=&type=&size=&page=&page_size=
+GET /api/v1/items/{class_name}
+```
+
+Data source: scunpacked — unofficial Star Citizen fansite content, not
+affiliated with Cloud Imperium Games.