100 lines
4.5 KiB
Markdown
100 lines
4.5 KiB
Markdown
# 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.
|
||
|
||
## Domyślne środowisko pracy (ważne)
|
||
|
||
- **Frontend**: domyślnie pracujemy lokalnie (Vite) i łączymy się z backendem na VPS (staging) przez proxy. Deploy frontendu na VPS robimy tylko jeśli jest to wyraźnie powiedziane (“wdrażam na VPS”).
|
||
- **Backend (trade-api + ingestor)**: zmiany backendu weryfikujemy/wdrażamy na VPS (staging), bo tam działa ingestor i tam są dane. Nie traktujemy lokalnego uruchomienia backendu jako domyślnego (tylko na wyraźną prośbę do debugowania).
|
||
|
||
## 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.mpabi.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:
|
||
```bash
|
||
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.mpabi.pl`.
|
||
|
||
- Vite trzyma `VITE_API_URL=/api` (default) i proxy’uje `/api/*` do VPS.
|
||
- Auth w staging jest w trybie `session` (`/auth/login`, cookie `trade_session`), więc w dev proxy’ujemy też `/whoami`, `/auth/*`, `/logout`.
|
||
- Dev proxy usuwa `Secure` z `Set-Cookie`, żeby cookie działało na `http://localhost:5173`.
|
||
- Na VPS `trade-frontend` proxy’uje dalej do `trade-api` i wstrzykuje read-token **server-side** (token nie trafia do przeglądarki).
|
||
|
||
Przykład:
|
||
|
||
```bash
|
||
cd apps/visualizer
|
||
API_PROXY_TARGET=https://trade.mpabi.pl \
|
||
npm run dev
|
||
```
|
||
|
||
Jeśli staging ma dodatkowy basic auth (np. Traefik `basicAuth`), dodaj:
|
||
`API_PROXY_BASIC_AUTH='USER:PASS'` albo `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.
|