Skip to main content
Use the local development setup when you want to modify the Go backend, tweak the React dashboard, or experiment with the codebase.

​
Requirements

Go 1.22+

The backend is written in Go and requires CGO (for SQLite). Make sure gcc is available on your system.

Node.js 20+ & pnpm

The dashboard and client SDK are built with Vite and managed in a pnpm workspace.

Task

Task is the task runner used for all dev and build commands. Install it from taskfile.dev.

pnpm

Install pnpm globally: npm install -g pnpm

​
Starting the Development Servers

The backend and dashboard are started in separate terminals. They run independently and communicate over HTTP.
1

Install JavaScript dependencies

From the repository root, install all workspace packages:
pnpm install
2

Start the Go backend (Terminal 1)

task dev:backend
This runs go run main.go from the cmd/server directory. The backend starts on :8080 and logs the address and database path:
Iris Analytics listening on :8080 (DB: ./data/iris.db)
The server creates ./data/iris.db (relative to cmd/server/) on first run. This file is your local SQLite database.
3

Start the React dashboard (Terminal 2)

task dev:dashboard
This runs pnpm dev inside the dashboard/ package. Vite starts the dev server on :5173 and automatically proxies all /api requests to the backend on :8080.Open http://localhost:5173/ to view the dashboard with hot-module replacement.

​
How the Two Processes Fit Together

ProcessCommandPortWhat it does
Go backendtask dev:backend:8080Serves /api/* routes and reads/writes iris.db
Vite dashboardtask dev:dashboard:5173Serves the React app with HMR; proxies /api to :8080
The Vite dev server proxy means you only need to open :5173 — API calls from the dashboard are forwarded to the running Go server transparently.
You can also run task dev to start both the backend and dashboard concurrently in a single terminal. This is equivalent to opening two terminals and running task dev:backend and task dev:dashboard separately.

​
Database File Location

When running task dev:backend, the SQLite database is created at: 
cmd/server/data/iris.db
This path is relative to the cmd/server directory (the dir set in Taskfile.yml). The data/ directory is created automatically if it does not exist.
You can override the database path with the DB_PATH environment variable — for example, to share one database between multiple run configurations.

​
Building for Production

To produce a production-ready build of the entire project (Go binary + compiled dashboard), run: 
task build
This runs both build:backend and build:js in parallel: 
task build:backend
# Outputs: dist/iris-server
The compiled Go binary is written to dist/iris-server. The dashboard static files are written to dashboard/dist/. These match the paths expected by the Dockerfile when building the Docker image. To publish the client SDK to npm, run: 
task publish:js
This runs pnpm build then npm publish from the web/ directory, which publishes @bigchill101/iris to the npm registry.

​
Taskfile Reference

Taskfile.yml
version: '3'

tasks:
  default:
    cmds:
      - task: build

  dev:
    desc: Run backend + dashboard dev server concurrently
    deps: [dev:backend, dev:dashboard]

  dev:backend:
    dir: cmd/server
    cmds:
      - go run main.go

  dev:dashboard:
    dir: dashboard
    cmds:
      - pnpm dev

  build:backend:
    cmds:
      - mkdir -p dist
      - go build -o dist/iris-server ./cmd/server

  install:js:
    cmds:
      - pnpm install

  build:js:
    cmds:
      - pnpm --filter @bigchill101/iris build
      - pnpm --filter @iris/dashboard build

  build:
    deps: [build:backend, build:js]

  publish:js:
    desc: Build and publish the npm package
    dir: web
    cmds:
      - pnpm build
      - npm publish

Build docs developers (and LLMs) love

Get started for freeTalk to us