# Setup

Fork the repository, install the CLIs, and start the database.

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

Let's get your environment ready.
You work in **your own fork** of the workshop repository, so you can push your contracts to GitHub and run them in CI/CD in [Part C](https://learn.datacontract.com/en/ci-cd/).

**You will learn:**
- Fork and clone the workshop repository
- Install the Data Contract CLI and the Data Product CLI
- Start the PostgreSQL database with the sample data
- Set up VS Code for editing YAML

## Prerequisites

### Check the prerequisites

You need:

- a **GitHub account** ([sign up](https://github.com/signup)),
- **git**,
- **Docker** with Docker Compose, running,
- **[uv](https://docs.astral.sh/uv/)**, the Python package manager that installs the CLIs,
- an editor, we recommend **[VS Code](https://code.visualstudio.com/)**.

**macOS / Linux:**

- **git**: preinstalled on most systems. On macOS, run `xcode-select --install` if it's missing.
- **Docker**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) (macOS), or Docker Engine with the Compose plugin (Linux).

**Windows:**

- **git**: install [Git for Windows](https://gitforwindows.org/).
- **Docker**: [Docker Desktop](https://www.docker.com/products/docker-desktop/) with the WSL 2 backend.
- **Terminal**: use **PowerShell**, ideally in [Windows Terminal](https://aka.ms/terminal). Every command in this tutorial has a PowerShell variant. No Git Bash needed.

Install **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!
```

Verify in a new 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
```

Your version numbers may differ. If `docker compose version` fails, start Docker Desktop.

## Get the repository

### Fork the repository

Open [github.com/datacontract/learn.datacontract.com](https://github.com/datacontract/learn.datacontract.com) and click **Fork**, then **Create fork**.
Your copy lives at `github.com/<your-username>/learn.datacontract.com`.

With the [GitHub CLI](https://cli.github.com/), you can fork and clone in one go (then skip the next step):

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
```

> **Why a fork?**
>
> Data contracts live in Git, next to the code that produces the data. That makes them reviewable and versioned.
> In your fork you can push changes, open pull requests, and run GitHub Actions, like in a real project.

### Clone your fork

Clone **your fork** (replace `<your-username>`) and change into the folder:

macOS / Linux:

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

Windows (PowerShell):

```powershell
git clone https://github.com/<your-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.
```

Run all commands in this tutorial from this folder, the repository root.

## Install the tools

### Install the CLIs

The install script uses uv to install the **Data Contract CLI** (`datacontract`), the **Data Product CLI** (`dataproduct`), and the **Entropy Data CLI** (`entropy-data`, only for Part D). It also pre-pulls the PostgreSQL image.

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
```

This takes a few minutes: the Data Contract CLI ships drivers for many databases.

### Verify the CLIs

Open a **new terminal** (to update your `PATH`), go to the repository root, and run:

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`? Run `uv tool update-shell` and open a new terminal.

> **Tip**
>
> Every command supports `--help`, e.g. `datacontract test --help`.

## Start the database

### Start PostgreSQL

The `docker-compose.yml` starts PostgreSQL 17 on port **5433** with e-commerce sample data:

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
```

Run a quick query:

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 already in use? Stop whatever runs on port 5433 and try again.

The database has two schemas, `orders_v1` and `orders_v2`, each with an `orders` and a `line_items` table.
To reset everything, run `docker compose down`, then `docker compose up -d`.

### Look at the .env file

Open `.env` in the repository root. It holds the database credentials:

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

Both CLIs read `.env` automatically when run from the repository root. Nothing to configure.

> **Warning**
>
> `.env` is tracked in Git. Fine for the local workshop credentials, but **never put real secrets such as API keys into it**: your fork is public.

## Set up your editor

### Open the repository in VS Code

Open the repository folder in VS Code:

macOS / Linux:

```bash
code .
```

Windows (PowerShell):

```powershell
code .
```

Install the **[YAML extension by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)** (VS Code suggests it when you open the folder).
The repository ships the official schemas in `schemas/` and maps them in `.vscode/settings.json`, so you get autocompletion and validation for every `*.odcs.yaml` and `*.odps.yaml` file.

`code: command not found`? Use **File → Open Folder…** instead.

**Quick check:** Why do you work in your own fork instead of just downloading the files?

- Forks run faster
- So you can version your contracts and run GitHub Actions on them in Part C (correct)
- The CLIs only work inside a Git repository
- To submit your solutions to the original repository

Contracts belong in Git like code. In your fork you can commit, review changes in pull requests, and automate tests with GitHub Actions in Part C.

You're all set. Time to write your first data contract!