Przejdź do treści

Wdrożenia — Convex, Windmill, Dashboard

Trzy niezależne ścieżki wdrożeniowe — każda dla innej warstwy systemu. Łączna deploy-skrypt bash scripts/deploy-all.sh all (lub just deploy) uruchamia je sekwencyjnie: Convex → Dashboard → Windmill.

Krótko

  • Convex (convex/) — schema + queries/mutations/actions. Komenda: npx convex deploy -y lub just deploy-convex.
  • Dashboard (dashboard/) — obraz Dockera SvelteKit, build → push → restart kontenera panel. Komenda: just deploy-dashboard.
  • Windmill (windmill/) — skrypty + flowy + harmonogramy. Komenda: just wmill-push "TASK-XXX: opis" (NIE raw wmill sync push).
  • Pełnowymiarowa deploy-skrypt: just deploy — łączy całość.

Przed wdrożeniem — bramy walidacji

Zawsze uruchom lokalnie zanim wypchniesz:

just check     # npx convex typecheck + dashboard check + check-windmill-paths + check-windmill-helpers

Co to robi:

Krok Polecenie Co weryfikuje
Convex typecheck npx convex typecheck Schema + funkcje TS w convex/ kompilują się bez błędów
Dashboard check cd dashboard && npm run check svelte-check + TS strict mode
Convex string-paths python3 scripts/validate-convex-paths.py Każdy convex.run("module:fn") w skryptach Windmilla wskazuje na realną funkcję (TASK-307)
Windmill helpers bash scripts/check-windmill-helpers.sh Kod dashboardu nie ma hand-rolled /api/w/<ws>/jobs/run/... URL-i (TASK-309)

Walidacja Windmilla — wmill generate-metadata przed pushem

just check NIE odpala wmill generate-metadata. Jeśli edytowałeś jakiś .py / .ts w windmill/, uruchom cd windmill && wmill generate-metadata przed pushem — to regeneruje .script.yaml + .script.lock ze świeżych importów. Pominięcie tego kroku produkuje ostrzeżenia w wmill sync push --dry-run ("Stale scripts metadata found...") i może wypchnąć stare zależności.

Convex — npx convex deploy

Convex deploy podmienia schema + funkcje atomowo. Stan bazy nie jest dotykany (poza migracjami schema, które Convex wymusza per-pole).

Komenda kanoniczna

just deploy-convex
# pod spodem: bash scripts/deploy-convex.sh

Skrypt:

  1. Wczytuje sekrety prod z convex/.env.prod.sops.yaml (decrypt SOPS w locie).
  2. npx convex typecheck.
  3. npx convex deploy -y — flaga -y jest konieczna (brak TTY → interaktywne potwierdzenie schema-change zawiesza deploy, patrz scripts/deploy-convex.sh).

Co się dzieje pod spodem

  • Convex sprawdza diff schema. Jeśli nowe wymagane pole bez v.optional() → deploy odmawia (zerwałby istniejące dokumenty). Rozwiązanie: dodaj jako v.optional() najpierw, backfill, potem usuń optional().
  • Funkcje są wymieniane atomowo — nie ma okna „pół deploya".
  • Stare funkcje znikające z tego deploya wypadają z runtime'u natychmiast — wszystko, co je woła z innych domen (Windmill, Dashboard), poleci. Zsynchronizuj zmiany breaking-API w jednym sprincie.

Kiedy ręcznie

cd convex
npx convex deploy --env-file .env.prod -y --cmd-url-env-var-name CONVEX_URL

Albo just prod-convex-query <path> / just prod-convex-run <path> dla pojedynczych odczytów / mutacji bez pełnego deploya — patrz justfile w korzeniu repo.

Dashboard — build obrazu + restart kontenera

Najbardziej skomplikowana ścieżka, bo dotyka żywego kontenera produkcyjnego.

Komenda kanoniczna

just deploy-dashboard
# pod spodem: bash scripts/deploy-dashboard.sh

Skrypt (scripts/deploy-dashboard.sh):

  1. docker buildx build --output type=docker --load -t panel-dashboard:latest -f dashboard/Dockerfile . — build z kontekstem repo-root (Dockerfile importuje convex/convex/support/nodeCatalog.ts jako SSoT).
  2. Zapisuje Created timestamp lokalnego obrazu (freshness guard, TASK-191).
  3. docker save | gzip > /tmp/panel-image.tar.gz → scp → aio-dad:/tmp/.
  4. SSH do aio-dad → incus file push do kontenera panel → docker load.
  5. Sprawdza, czy Created na zdalnym = Created lokalny. Jeśli różny — abort (stary obraz).
  6. docker compose up -d --no-deps --force-recreate panel w kontenerze panel.
  7. sleep 3 + docker ps — sanity check.

Pułapki

buildx + containerd snapshotter

Pod containerd snapshotterem zwykły docker build zostawia stary obraz w docker-store i docker save eksportuje stary tag. Stąd buildx --output type=docker --load — wymusza zapis do docker-store (TASK-191).

stdin w heredoc + incus

Każdy sudo incus exec ... wewnątrz heredoc-a SSH potrzebuje `