Pragm

TIB-Trader Project PRAGM (Pragmatic Reference and Guidance Manual)

Purpose

• Single-source snapshot of how the stack is built, deployed, operated, and extended (desktop-only UI).
• Optimised for repeatable setup on developer laptops and the TIB-Trader host (see env/.env.tib for target host).

Architecture (containers)

• django (TIB-APP): Django 6 + Gunicorn; serves the app and static files via Whitenoise (behind nginx).
• nginx (TIB-WEBSERVICE): reverse proxy/SSL terminator for app/wiki/pgadmin.
• postgres (TIB-DATABASE): primary DB (app + accounts databases).
• redis (TIB-REDIS): cache backend (sessions, fragments); default URL redis://redis:6379/1. Use TLS+auth in prod (rediss://).
• fluent-bit (TIB-LOGGING): central log shipper; docker fluentd driver points here.
• pgadmin (TIB-PGADMIN): optional DB UI.
• certbot-renew (TIB-SSL): automated renewals; certbot-init one-shot for issuance.
• wiki (TIB-WIKI): static HTML wiki.
• docs-builder (profile docs): optional helper to regenerate wiki HTML from docs/*.md.

Environments

• Local dev (WSL/Windows/mac/Linux): make rebuild (or full-rebuild), then python -m console.menu → option 7 (migrate + UI sync + seed Admin/Andrew/tib).
• TIB host: same make targets; issue certs with env/.env.tib and certbot-init; DNS should be set for app/wiki.tib-trader.com.

Build & run flow

1) make rebuild (keeps data volumes) or make full-rebuild (wipes containers/images, keeps certs/backups).
2) python scripts/python/10_bootstrap_dev.py (or menu option 7) → migrate, sync UI elements, seed Admin/Andrew/tib.
3) Health check: ./scripts/shell/20_health_check.sh (override BASE_URL as needed).
4) UI smoke: HOST_HEADER=app.tib-trader.com BASE_URL=http://127.0.0.1 ./scripts/shell/30_smoke_playwright.sh.

Data & models (high level)

• Preferences: UserPreference key/values per user (e.g., theme).
• UI index: UiElement table stores data-ui keys for wiki cross-reference.

UI / Layout

• Desktop-only layout tuned for 1080p at 125% Windows DPI (effective 1536x864 CSS px).
• Grid and button sizing optimized for wide cards and 3-button rows without horizontal scroll.

Security / secrets

• Secrets live in env/.env*; never in docs. Required: DJANGO_SECRET_KEY, ENCRYPTION_KEY, DANGER_ZONE_PASSWORD, DB creds.
• Redis: keep on private network; use TLS+auth in prod.
• Certs: stored in certs/letsencrypt (git-ignored); don’t delete volumes.

Observability

• Logs: Docker fluentd driver → fluent-bit → docker/fluent-bit/logs/containers.log (rotated).
• Playwright smokes write to docker/fluent-bit/logs/playwright-smoke.log.
• Health: /healthz/ from nginx/django.

Testing

• Django unit tests: docker compose exec -T django python manage.py test pmcore.tests.
• Playwright smokes: ./scripts/shell/30_smoke_playwright.sh (uses Host override by default).
• Migration drift: manage.py showmigrations --plan (used in ci.sh).

Docs / wiki automation

• Source: docs/*.md.
• Generate static wiki HTML: ./scripts/shell/50_build_wiki.sh (uses local Python markdown); or containerised docker compose run --rm docs-builder (profile docs).
• Output: docker/wiki/html/guides/*.html and TOC updated.

Backup & safety

• DB volume: TIB-Database-Data. Backups via ./scripts/backup_pg.sh.
• Danger wipe keeps auth/users; gated by DANGER_ZONE_PASSWORD.
• Keep cert volumes (TIB-SSL-*) intact when resetting data.

Next automation ideas

• Optional Celery/Redis worker for async tasks (import queues, email).
• Sentry (or self-hosted) for error monitoring.
• GitHub Actions to run ci.sh + Playwright in headless container with Host override.

References

• React reference: https://react.dev/reference/react

Back to wiki home