Getting Started

The Evidential suite has a backend API server (FastAPI) and a frontend web-app (NextJS).

Note

Note: See our Reading List for links to documentation on our open-source tech stack.

Contributing from outside the team?

The clone commands below use the upstream repositories. If you're an external contributor, fork first and clone your fork instead — you won't have push access to the upstream repos.

Setting up on Windows?

Windows needs a few extra steps first. Start with Windows Setup — it sets up WSL and installs everything in Prerequisites for you — then continue with Setup inside WSL.

Prerequisites

Install Task.
Install Docker.
Install Git LFS.
Install pnpm. pnpm will select the Node.js version required by the frontend.
Install prek.

Setup

Run these steps on macOS, on Linux, or inside WSL on Windows.

Backend

Follow the steps below to get a local development environment running.

Clone the https://github.com/agency-fund/evidential-be repository:
```
gh repo clone agency-fund/evidential-be
cd evidential-be
```
Set up the prek git hooks in your local checkout:
```
uv run prek install
```
Install dependencies (Atlas, uv, Python dependencies) by running:
```
git lfs install
task install-dependencies
```
Run the unit tests:
```
task test-airplane
```
Get familiar with the task runner. Most of the commands you will run are defined in Taskfile.yml. Run:
```
task --list
```
Start the backend server:
```
task start-airplane
```
This will start the server at http://localhost:8000. It stores its state in a local Postgres instance, running in Docker, on localhost:5499.
Visit the local interactive OpenAPI docs page: http://localhost:8000/docs

Frontend

Clone the https://github.com/agency-fund/evidential-fe repository:
```
gh repo clone agency-fund/evidential-fe
cd evidential-fe
```
Set up the prek git hooks in your local checkout:
```
prek install
```
Confirm that pnpm selects and runs the required Node.js version:
```
pnpm exec node --version
```
Start the frontend server:
```
task start-airplane
```

Windows Setup

From Command Prompt, install WSL 2:

wsl --set-default-version 2
wsl --install -d ubuntu-24.04

From Command Prompt, configure WSL networking so that servers running in WSL are reachable from Windows. Open the WSL config file:
```
notepad %USERPROFILE%\.wslconfig
```
Add the following, then save and close the file:
```
[wsl2]
networkingMode=mirrored
dnsTunneling=true
firewall=true
autoProxy=true
```
Restart WSL to apply the change, then reopen WSL when you're ready to continue.

Install the prerequisites by running tools/windows_setup.sh from the backend repo:

curl -fsSL https://raw.githubusercontent.com/agency-fund/evidential-be/main/tools/windows_setup.sh -o /tmp/windows_setup.sh
chmod +x /tmp/windows_setup.sh
/tmp/windows_setup.sh

Go back to Setup and follow the remaining steps from inside WSL.