trade/trade-frontend
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
444f42742048aae67cfa4791dfd591b68559be04
trade-frontend/doc/workflow.md
u1 f3c4a999c3 docs: add workflow playbook
2026-01-07 19:49:59 +00:00

3.8 KiB
Raw Blame History

Workflow pracy w projekcie trade (dev → staging na VPS) + snapshot/rollback

Ten plik jest “source of truth” dla sposobu pracy nad zmianami w trade.
Cel: zero ręcznych zmian na VPS, każdy deploy jest snapshoot’em, do którego można wrócić.

Dla agenta / po restarcie sesji

  1. Przeczytaj ten plik: doc/workflow.md.
  2. Kontekst funkcjonalny: README.md, info.md.
  3. Kontekst stacka: doc/workflow-api-ingest.md oraz devops/*/README.md.
  4. Stan VPS/k3s + GitOps: doc/migration.md i log zmian: doc/steps.md.

Zasady (must-have)

  • Nie edytujemy “na żywo” VPS (żadnych ręcznych poprawek w kontenerach/plikach na serwerze) → tylko Git + CI + Argo.
  • Sekrety nie trafiają do gita: tokens/*.json są gitignored; w dokumentacji/logach redagujemy hasła/tokeny.
  • Brak latest: obrazy w deployu są przypięte do sha-<shortsha> albo digesta.
  • Każda zmiana = snapshot: “wersja” to commit w repo deploy + przypięte obrazy.

Standardowy flow zmian (polecany)

  1. Zmiana w kodzie lokalnie.
    • Nie musisz odpalać lokalnego Dockera; na start rób szybkie walidacje (build/typecheck).
  2. Commit + push (najlepiej przez PR).
  3. CI:
    • build → push obrazów (tag sha-* lub digest),
    • aktualizacja trade-deploy (bump obrazu/rewizji).
  4. Argo CD (auto-sync na staging) wdraża nowy snapshot w trade-staging.
  5. Test na VPS:
    • API: /healthz, /v1/ticks, /v1/chart
    • UI: trade.rv32i.pl
    • Ingest: logi trade-ingestor + napływ ticków do tabeli.

Snapshoty i rollback (playbook)

Rollback szybki (preferowany)

  • Cofnij snapshot w repo deploy:
    • git revert commita, który podbił obrazy, albo
    • w Argo cofnij do poprzedniej rewizji (ten sam efekt).

Efekt: Argo wraca do poprzedniego “dobrego” zestawu obrazów i konfiguracji.

Rollback bezpieczny dla “dużych” zmian (schema/ingest)

Jeśli zmiana dotyka danych/ingestu, rób ją jako nową wersję vN:

  • nowa tabela: drift_ticks_vN
  • nowa funkcja: get_drift_candles_vN
  • osobny deploy API/UI (inne porty/sufiksy), a ingest przełączany “cutover”.

W razie problemów: robisz “cut back” vN → v1 (stare dane zostają nietknięte).

Lokalne uruchomienie (opcjonalne, do debugowania)

Dokładna instrukcja: doc/workflow-api-ingest.md.

Skrót:

npm install
docker compose -f devops/db/docker-compose.yml up -d
docker compose -f devops/tools/bootstrap/docker-compose.yml run --rm db-init
docker compose -f devops/tools/bootstrap/docker-compose.yml run --rm hasura-bootstrap
docker compose -f devops/app/docker-compose.yml up -d --build api
npm run token:api -- --scopes write --out tokens/alg.json
npm run token:api -- --scopes read --out tokens/read.json
docker compose -f devops/app/docker-compose.yml up -d --build frontend
docker compose -f devops/app/docker-compose.yml --profile ingest up -d --build

Frontend dev (Vite) z backendem na VPS (staging)

Jeśli chcesz szybko iterować nad UI bez deploya, możesz odpalić lokalny Vite i podpiąć go do backendu na VPS przez istniejący proxy /api na trade.rv32i.pl.

  • Vite trzyma VITE_API_URL=/api (default) i proxy’uje /api/* do VPS.
  • Na VPS trade-frontend proxy’uje dalej do trade-api i wstrzykuje read-token server-side (token nie trafia do przeglądarki).

Przykład:

cd apps/visualizer
API_PROXY_TARGET=https://trade.rv32i.pl/api \
API_PROXY_BASIC_AUTH='USER:PASS' \
npm run dev

Alternatywnie dla basic auth możesz użyć pliku JSON: API_PROXY_BASIC_AUTH_FILE=tokens/frontend.json (pola username/password).

Definicja “done” dla zmiany

  • Jest snapshot (commit w deploy) i można wrócić jednym ruchem.
  • Staging działa (API/ingest/UI) i ma podstawowe smoke-checki.
  • Sekrety nie zostały dodane do repo ani do logów/komentarzy.