Star Citizen Inventory

A read-only item inventory website for Star Citizen players, built from the scunpacked game data (mirrored at 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

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

ansible-playbook playbook.yml

To deploy to a remote server, edit inventory.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

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

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.