# First Steps

This is the shortest path from a fresh clone to a working FourIA environment.
Each step links to deeper documentation.

## 1. Prerequisites

| Tool | Why | Install |
| --- | --- | --- |
| **Bun** | Runtime, package manager, and test runner for all TypeScript packages. | <https://bun.sh/> |
| **Node.js 22** | Required by some dependencies. | <https://nodejs.org/> |
| **Docker** | Builds and runs the Sandbox container image locally. | <https://docs.docker.com/get-docker/> |
| **Cloudflare account** | Workers Paid plan for Sandbox containers. | <https://dash.cloudflare.com/> |
| **Nix** *(optional)* | Root/Elixir shells and the docs site toolchain. | <https://nixos.org/download> |

## 2. Clone and install

```bash
git clone <repo-url> fouria
cd fouria
bun install
bun run build:all
```

`build:all` builds the shared packages (cost calculator, moltlazy) and the
Worker dashboard bundle.

## 3. Configure local environment

```bash
cp apps/fouria/.dev.vars.example apps/fouria/.dev.vars

# and CF_AI_GATEWAY_GATEWAY_ID at minimum.
```

See [Platform → Environment Variables](/latest/platform/reference/env-variables/) for the full
reference.

## 4. Run the services

```bash
# Terminal 1 — Worker dashboard (Vite, hot reload on :8787)
cd apps/fouria && bun run dev

# Terminal 2 — Worker backend (Cloudflare Vite plugin, :8788)
cd apps/fouria && bun run dev:worker
```

For the **Lerma** dashboard, see [Lerma → Overview](/latest/platform/apps/lerma/) and its
[DEPLOY guide](/latest/platform/apps/lerma/deploy/).

## 5. Verify your setup

```bash
# TypeScript packages
bun run lint
bun run test

# Elixir workspace (inside `nix develop .` from the repo root)
mix deps.get
mix workspace.run -t deps.get
mix check
```

## 6. Build the docs site

The site you are reading is built from the repo markdown with Zola:

```bash
cd webs/fouria-docs
nix develop --command bun run docs:sync   # repo markdown → Zola content
nix develop --command zola build          # static site → webs/fouria-docs/public
nix develop --command zola serve          # live preview
```

## 7. Go deeper

- [Platform architecture](/latest/platform/reference/cloud-architecture/) — how the pieces fit together.
- [Development guide](/latest/platform/reference/development/) — component reference and workflows.
- [Testing guide](/latest/platform/reference/testing/) — unit, integration, and E2E suites.
- [Contributing](/latest/platform/reference/contributing/) — TDD, pre-commit, and PR expectations.
