foliot docs

Guides / Start here / Quickstart

Quickstart

This runs Foliot from source, so it needs read access to the tinbee/foliot repository, which is private. You also need Node 22, pnpm, Go and Docker.

Start a Postgres with the foliot role and database, so the DATABASE_URL below works as written:

docker run -d --name foliot-postgres -p 5432:5432 \
  -e POSTGRES_USER=foliot -e POSTGRES_PASSWORD=foliot -e POSTGRES_DB=foliot postgres:16

Then fetch and build:

git clone https://github.com/tinbee/foliot.git && cd foliot
pnpm install
pnpm --filter @foliot/protocol build && pnpm --filter @foliot/sdk build

1. Start the server

# The console is on another origin, so name it or the browser is refused.
export FOLIOT_CORS_ORIGIN=http://localhost:4101
export DATABASE_URL=postgres://foliot:foliot@localhost:5432/foliot
export FOLIOT_OPERATOR_TOKENS=dev-operator-token:dev
pnpm dev:server                      # http://localhost:4100

The server creates its schema on first start. pnpm dev:server runs go run ./cmd/foliot and, in development, defaults FOLIOT_CORS_ORIGIN to the console’s origins when you have not set it.

▶ Note.

An unset FOLIOT_CORS_ORIGIN means the Go server sends no CORS headers, so a browser console is refused. The console shows this as “Load failed”.

2. Register the example app and run it

cd examples/order-fulfilment
FOLIOT_OPERATOR_TOKEN=dev-operator-token pnpm setup   # prints FOLIOT_TOKEN / FOLIOT_SIGNING_SECRET
export FOLIOT_URL=http://localhost:4100 FOLIOT_APP=orders FOLIOT_TOKEN=... FOLIOT_SIGNING_SECRET=...
pnpm dev                             # http://localhost:4200, handlers at /foliot

3. Place an order and watch it move

curl -s -XPOST localhost:4200/orders -H 'content-type: application/json' \
  -d '{"orderId":"o-1","customerEmail":"a@b.c","items":[{"sku":"sku-1","qty":1}],"amount":800,"card":"4242"}'
curl -s -XPOST localhost:4200/warehouse/shipped/o-1 -d '{"tracking":"TRK1"}' -H 'content-type: application/json'

4. Open Foliot Console

pnpm dev:console                   # http://localhost:4101

Open Settings and use the token dev-operator-token. The Get started page walks you through connecting and registering an app.

pnpm demo in the example walks both incident scenarios end to end: a payments outage that is repaired with a bulk redrive, and a bad deploy that is repaired by rewinding the affected runs onto fixed code.

Next