# Setup

Repository forken, CLIs installieren und Datenbank starten.

Source: https://learn.datacontract.com/de/setup/

Richten wir deine Umgebung ein.
Du arbeitest in **deinem eigenen Fork** des Workshop-Repositorys. So kannst du deine Kontrakte nach GitHub pushen und in [Teil C](https://learn.datacontract.com/de/ci-cd/) per CI/CD testen.

**You will learn:**
- Das Workshop-Repository forken und klonen
- Data Contract CLI und Data Product CLI installieren
- Die PostgreSQL-Datenbank mit den Beispieldaten starten
- VS Code für YAML einrichten

## Voraussetzungen

### Voraussetzungen prüfen

Du brauchst:

- einen **GitHub-Account** ([registrieren](https://github.com/signup)),
- **git**,
- **Docker** mit Docker Compose, gestartet,
- **[uv](https://docs.astral.sh/uv/)**, den Python-Paketmanager, der die CLIs installiert,
- einen Editor, wir empfehlen **[VS Code](https://code.visualstudio.com/)**.

**macOS / Linux:**

- **git**: auf den meisten Systemen vorinstalliert. Fehlt es unter macOS, führe `xcode-select --install` aus.
- **Docker**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) (macOS) oder Docker Engine mit dem Compose-Plugin (Linux).

**Windows:**

- **git**: installiere [Git for Windows](https://gitforwindows.org/).
- **Docker**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) mit dem WSL-2-Backend.
- **Terminal**: nutze **PowerShell**, am besten im [Windows Terminal](https://aka.ms/terminal). Jeder Befehl in diesem Tutorial hat eine PowerShell-Variante. Git Bash brauchst du nicht.

Installiere **uv**:

macOS / Linux:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Windows (PowerShell):

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Output:

```text
downloading uv 0.12.19
installing to ~/.local/bin
  uv
  uvx
everything's installed!
```

Prüfe in einem neuen Terminal:

macOS / Linux:

```bash
git --version
docker compose version
uv --version
```

Windows (PowerShell):

```powershell
git --version
docker compose version
uv --version
```

Output:

```text
git version 2.54.0
Docker Compose version v5.1.4
uv 0.12.19
```

Deine Versionsnummern können abweichen. Schlägt `docker compose version` fehl, starte Docker Desktop.

## Repository holen

### Repository forken

Öffne [github.com/datacontract/learn.datacontract.com](https://github.com/datacontract/learn.datacontract.com) und klicke auf **Fork**, dann auf **Create fork**.
Deine Kopie liegt unter `github.com/<dein-username>/learn.datacontract.com`.

Mit der [GitHub CLI](https://cli.github.com/) forkst und klonst du in einem Schritt (dann überspringe den nächsten Schritt):

macOS / Linux:

```bash
gh repo fork datacontract/learn.datacontract.com --clone
```

Windows (PowerShell):

```powershell
gh repo fork datacontract/learn.datacontract.com --clone
```

Output:

```text
✓ Created fork you/learn.datacontract.com
Cloning into 'learn.datacontract.com'...
✓ Cloned fork
```

> **Warum ein Fork?**
>
> Datenkontrakte leben in Git, neben dem Code, der die Daten erzeugt. So sind sie versioniert und lassen sich reviewen.
> In deinem Fork kannst du pushen, Pull Requests öffnen und GitHub Actions ausführen, wie in einem echten Projekt.

### Deinen Fork klonen

Klone **deinen Fork** (ersetze `<dein-username>`) und wechsle in den Ordner:

macOS / Linux:

```bash
git clone https://github.com/<dein-username>/learn.datacontract.com.git
cd learn.datacontract.com
```

Windows (PowerShell):

```powershell
git clone https://github.com/<dein-username>/learn.datacontract.com.git
cd learn.datacontract.com
```

Output:

```text
Cloning into 'learn.datacontract.com'...
remote: Enumerating objects: 512, done.
Receiving objects: 100% (512/512), done.
Resolving deltas: 100% (231/231), done.
```

Führe alle Befehle in diesem Tutorial in diesem Ordner aus, dem Root des Repositorys.

## Werkzeuge installieren

### CLIs installieren

Das Installationsskript installiert mit uv die **Data Contract CLI** (`datacontract`), die **Data Product CLI** (`dataproduct`) und die **Entropy Data CLI** (`entropy-data`, nur für Teil D). Außerdem lädt es das PostgreSQL-Image vorab.

macOS / Linux:

```bash
scripts/install.sh
```

Windows (PowerShell):

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
```

Output:

```text
Resolved 182 packages in 2.41s
…
Installed 1 executable: datacontract
…
Installed 1 executable: dataproduct
…
Installed 1 executable: entropy-data
1.2.2
0.2.0
…
Status: Downloaded newer image for postgres:17
docker.io/library/postgres:17
```

Das dauert ein paar Minuten: Die Data Contract CLI bringt Treiber für viele Datenbanken mit.

### CLIs prüfen

Öffne ein **neues Terminal** (damit dein `PATH` aktuell ist), wechsle in den Root des Repositorys und führe aus:

macOS / Linux:

```bash
datacontract --version
dataproduct --version
```

Windows (PowerShell):

```powershell
datacontract --version
dataproduct --version
```

Output:

```text
1.2.2
0.2.0
```

`command not found`? Führe `uv tool update-shell` aus und öffne ein neues Terminal.

> **Tip**
>
> Jeder Befehl unterstützt `--help`, z. B. `datacontract test --help`.

## Datenbank starten

### PostgreSQL starten

Die `docker-compose.yml` startet PostgreSQL 17 auf Port **5433** mit E-Commerce-Beispieldaten:

macOS / Linux:

```bash
docker compose up -d
```

Windows (PowerShell):

```powershell
docker compose up -d
```

Output:

```text
 Network learndatacontractcom_default Creating
 Network learndatacontractcom_default Created
 Container odcs-odps-workshop-postgres Creating
 Container odcs-odps-workshop-postgres Created
 Container odcs-odps-workshop-postgres Starting
 Container odcs-odps-workshop-postgres Started
```

Teste mit einer kurzen Abfrage:

macOS / Linux:

```bash
docker compose exec postgres psql -U workshop -d workshop -c "SELECT COUNT(*) FROM orders_v1.orders;"
```

Windows (PowerShell):

```powershell
docker compose exec postgres psql -U workshop -d workshop -c "SELECT COUNT(*) FROM orders_v1.orders;"
```

Output:

```text
 count
-------
  5000
(1 row)
```

Port belegt? Beende, was auf Port 5433 läuft, und versuch es nochmal.

Die Datenbank hat zwei Schemas, `orders_v1` und `orders_v2`, jeweils mit den Tabellen `orders` und `line_items`.
Alles zurücksetzen: erst `docker compose down`, dann `docker compose up -d`.

### Die .env-Datei ansehen

Öffne die `.env` im Root des Repositorys. Sie enthält die Zugangsdaten zur Datenbank:

```text title=.env
DATACONTRACT_POSTGRES_USERNAME=workshop
DATACONTRACT_POSTGRES_PASSWORD=workshop
```

Beide CLIs lesen die `.env` automatisch, wenn du sie im Root des Repositorys ausführst. Du musst nichts konfigurieren.

> **Warning**
>
> `.env` ist in Git eingecheckt. Für die lokalen Workshop-Zugangsdaten ist das okay, aber **trage niemals echte Secrets wie API-Keys ein**: Dein Fork ist öffentlich.

## Editor einrichten

### Repository in VS Code öffnen

Öffne den Ordner des Repositorys in VS Code:

macOS / Linux:

```bash
code .
```

Windows (PowerShell):

```powershell
code .
```

Installiere die **[YAML-Erweiterung von Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)** (VS Code schlägt sie beim Öffnen des Ordners vor).
Das Repository bringt die offiziellen Schemas in `schemas/` mit und verknüpft sie in `.vscode/settings.json`. So bekommst du Autovervollständigung und Validierung für alle `*.odcs.yaml`- und `*.odps.yaml`-Dateien.

`code: command not found`? Öffne den Ordner über **File → Open Folder…**.

**Quick check:** Warum arbeitest du in deinem eigenen Fork, statt die Dateien nur herunterzuladen?

- Forks laufen schneller
- Damit du deine Kontrakte versionierst und in Teil C GitHub Actions darauf laufen lässt (correct)
- Die CLIs funktionieren nur in einem Git-Repository
- Um deine Lösungen im Original-Repository einzureichen

Kontrakte gehören wie Code in Git. In deinem Fork kannst du committen, Änderungen in Pull Requests prüfen und in Teil C Tests mit GitHub Actions automatisieren.

Alles bereit. Zeit für deinen ersten Datenkontrakt!