Instalacja i konfiguracja lokalna

Ten przewodnik prowadzi przez uruchomienie pełnej platformy DataFlow AI na maszynie deweloperskiej — instalację wymagań wstępnych, zrozumienie układu monorepozytorium, postawienie całego stosu za pomocą Docker Compose oraz budowanie każdego komponentu osobno ze źródeł.

Wymagania wstępne

DataFlow AI to wielojęzyczne monorepozytorium, więc zbudowanie wszystkiego ze źródeł wymaga czterech zestawów narzędzi językowych. Aby po prostu uruchomić platformę, Docker i Docker Compose są jedynym twardym wymaganiem — build Compose obsługuje każdy zestaw narzędzi wewnątrz kontenerów.

Weryfikacja zestawów narzędzi

Przed budowaniem ze źródeł potwierdź, że każdy zestaw narzędzi udostępnia oczekiwaną wersję główną:

docker --version
docker compose version
java -version        # should report 21
node --version       # should report v20.x
python --version     # should report 3.12.x
go version           # should report go1.22

Układ repozytorium

Monorepozytorium jest zorganizowane według języka i środowiska uruchomieniowego. Katalogi najwyższego poziomu, z którymi będziesz pracować, to:

polcomtel/
├── backend/
│   ├── platform/           Kotlin / Spring Boot 3.3.5 multi-module Gradle build
│   │   ├── common/             shared security, models, exception handling (library)
│   │   ├── connector-sdk/      connector framework + 21 connector impls (library)
│   │   ├── pushdown-sql/       JSqlParser-based SQL dialect transpiler
│   │   ├── api-gateway/        reactive Spring Cloud Gateway — single ingress
│   │   ├── metadata-service/   catalog, connections, governance, GDPR, MCP server
│   │   ├── pipeline-engine/    pipeline DAG compilation, execution, scheduling
│   │   ├── lineage-service/    dataset/column lineage, OpenLineage ingestion
│   │   ├── monitor-service/    alerts, metrics, cost, SLA, notifications, SSE
│   │   └── integration-tests/  cross-service integration test module
│   ├── ai-services/        Python 3.12 / FastAPI services
│   │   ├── copilot/            NL-to-pipeline, NL-to-SQL, RAG, chat, RCA
│   │   └── migration-engine/   Informatica / Alteryx → DataFlow YAML conversion
│   ├── cli/                Go 1.22 Cobra command-line tool (`dataflow`)
│   ├── infrastructure/     Kubernetes manifests + Helm charts + Terraform
│   └── docker-compose.yml  orchestrates all 12 services for local / VPS
├── frontend/               React 19 + Vite 7 + TypeScript 5.9 SPA
├── browser-extension/      companion browser extension
└── deploy/                 VPS deployment scripts

Korzeniem buildu Gradle jest backend/platform. Spośród jego dziewięciu modułów pięć to usługi przeznaczone do wdrożenia (api-gateway, metadata-service, pipeline-engine, lineage-service, monitor-service), a pozostałe to biblioteki lub moduły testowe wbudowane w usługi.

Uruchamianie stosu za pomocą Docker Compose

backend/docker-compose.yml orkiestruje 12 kontenerów — osiem komponentów infrastruktury plus sześć usług aplikacyjnych i frontend — w pojedynczej sieci mostkowej Docker o nazwie dataflow-network. Każdy kontener rozwiązuje swoich sąsiadów po nazwie kontenera.

Konfiguracja zmiennych środowiskowych

Sekrety są odczytywane z plików .env (i .env.local) ignorowanych przez git, znajdujących się w backend/. Utwórz taki plik przed uruchomieniem stosu:

cd backend
cp .env.example .env

Minimalnie ustaw wartości używane przez platformę:

Copilot ładuje klucze dostawców LLM z .env.local z opcją required: false, więc stos nadal się uruchamia (z ograniczonymi funkcjami RAG copilota), gdy brakuje kluczy.

Uruchomienie stosu

Z katalogu backend/ postaw całość:

docker compose up -d

Kolejność uruchamiania jest wymuszana przez healthchecki kontenerów oraz depends_on: najpierw startuje PostgreSQL, następnie Keycloak, Kafka i Redis, potem sześć usług aplikacyjnych, a na końcu frontend. Dwa trwałe wolumeny — pgdata i miniodata — przetrwają restarty.

Migracje Flyway uruchamiają się automatycznie przy starcie każdej usługi JVM. Obserwuj logi, aż usługi aplikacyjne zgłoszą gotowość:

docker compose logs -f api-gateway metadata-service pipeline-engine

Zatrzymywanie i resetowanie

docker compose down            # stop containers, keep volumes
docker compose down -v         # stop and DELETE pgdata + miniodata volumes

Porty usług i infrastruktury

Wewnątrz sieci Docker każda usługa JVM nasłuchuje na porcie 8080, a usługi AI na 8000. Publikowane porty po stronie hosta wymienione poniżej służą wyłącznie do bezpośredniego dostępu deweloperów — normalny ruch zawsze przepływa przez bramę.

Usługi aplikacyjne

Komponenty infrastruktury

Dostęp do uruchomionej platformy

Gdy stos jest gotowy, otwórz w przeglądarce poniższe adresy URL:

Logowanie odbywa się przez Keycloak: SPA wykonuje przekierowanie OIDC do Keycloak, realm dataflow uwierzytelnia użytkownika, a keycloak-js wymienia kod autoryzacyjny na JWT. Brama waliduje ten JWT i wstrzykuje nagłówki tożsamości X-User-* przy każdym wywołaniu w dół stosu.

Szybkie sprawdzenie kondycji bramy:

curl -s http://localhost:8085/actuator/health

Budowanie komponentów ze źródeł

Możesz zbudować i uruchomić dowolny komponent poza jego kontenerem, aby przyspieszyć iterację. Stos Compose może nadal dostarczać infrastrukturę (PostgreSQL, Keycloak, Kafka, Redis), podczas gdy uruchamiasz pojedynczą usługę ze źródeł.

Usługi platformowe JVM (Gradle)

Usługi Kotlin współdzielą pojedynczy wielomodułowy build Gradle z korzeniem w backend/platform. Użyj dołączonego wrappera:

cd backend/platform
./gradlew build                          # compile + Detekt + tests for all modules
./gradlew :metadata-service:bootRun       # run one service from source
./gradlew :api-gateway:test               # run a single module's tests

Współdzielony platform/Dockerfile jest wieloetapowy — builder gradle:8.5-jdk21 produkuje plik jar, który działa na środowisku uruchomieniowym eclipse-temurin:21-jre-alpine jako użytkownik bez uprawnień roota. Argument buildu BUILD_MODULE wybiera, który moduł Gradle ma zostać spakowany.

Usługi AI (Poetry)

Każda usługa Python jest niezależnym projektem Poetry. Z katalogu backend/ai-services/copilot (lub migration-engine):

poetry install                            # install dependencies
poetry run uvicorn app.main:app --reload  # run the FastAPI service
poetry run pytest                         # run the test suite
poetry run ruff check .                   # lint

Usługi Python używają wieloetapowego obrazu python:3.12-slim i działają pod uvicorn.

Frontend (Vite)

SPA React buduje się za pomocą Vite. Z katalogu frontend/:

npm ci          # install exactly what's in package-lock.json
npm run dev     # Vite dev server with hot reload
npm run build   # production build — runs `tsc -b && vite build`
npm test        # Vitest unit tests

Serwer deweloperski proxuje wywołania API; klient axios SPA używa bazowego URL /api/v1, więc oczekuje, że brama będzie osiągalna.

Go CLI (moduły Go)

CLI dataflow buduje się standardowym zestawem narzędzi Go. Z katalogu backend/cli:

go build ./...                # build the CLI
go vet ./...                  # static checks
go test -race ./...           # tests with the race detector

Rozwiązywanie problemów