Getting started

This sets up a development copy of Refract.Chat: the backend and web app running from source on your machine, with their supporting services in Docker.

What you need

• Node.js 26 (what CI uses; 22 is the oldest that works).
• Yarn Classic (1.x). Each package has its own package.json and yarn.lock; it's not a workspace.
• Docker with the Compose plugin, for Redis, LiveKit, Meilisearch, MinIO and Mailpit.

1. Install and build

The SDK is shared by every other package, so build it first. Yarn copies it into each package rather than linking it:

yarn --cwd sdk install
yarn --cwd sdk build
yarn --cwd backend install
yarn --cwd frontend install

2. Configure the backend

cd backend
cp .env.example .env
cp app.config.example.yaml app.config.yaml
cp livekit-server.example.yaml livekit-server.yaml

• In .env, set APP_CONFIG_PATH=./app.config.yaml.

• For calls, LiveKit runs in Docker and needs an address your browser can reach:

  • in livekit-server.yaml, set redis.address: livekit_redis:6379, rtc.node_ip to your machine's LAN address, and the webhook URL to http://<that address>:8779/livekit/webhook;
  • in .env, set LIVEKIT_PUBLIC_URL=ws://<that address>:7866.

  For calls only from a browser on the same machine, 127.0.0.1 works for both.

The other development defaults in .env.example already match the Docker services.

3. Start the services and the database

From backend/:

docker compose up -d
yarn migrate
yarn seed

docker compose up -d starts Redis (on port 6669), LiveKit (7866), Meilisearch (7700), MinIO (9000) and Mailpit (SMTP on 1025, its inbox at http://localhost:8025). The database is SQLite, in backend/.data/.

yarn seed adds demo accounts: admin@localhost, alice@localhost and bob@localhost, all with the password password. The backend won't start without at least one account.

4. Run it

In two terminals:

yarn --cwd backend start    # API on http://localhost:8778, restarts on changes
yarn --cwd frontend start   # web app on http://localhost:3001

Open http://localhost:3001 and sign in as one of the demo accounts. Vite proxies /api, including the socket, to the backend.

Changing the SDK

After editing sdk/, rebuild it and copy it into the packages that use it:

./sync-sdk.sh

Stop the frontend's dev server first, then restart it with yarn --cwd frontend start --force and hard-reload the browser, so Vite drops its cached copy. If the SDK's own dependencies changed, use ./relink-sdk.sh, which reinstalls everything.

On Windows

bash dev.sh start in Git Bash, with Docker Desktop running, starts an already configured checkout: it builds and syncs the SDK, starts the Docker services, applies migrations, and runs the backend and frontend in the background. bash dev.sh status, logs, restart and stop manage it. It uses NODE_ENV=development, ports 8778, 8779 and 3001, and expects LiveKit's webhook at http://host.docker.internal:8779/livekit/webhook.

Next

• Project structure: how the packages fit together.
• Checks & tests: what to run before you push.