Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides instructions for setting up the kodus-runtime project for local development. The project is a monorepo containing a Rust-based event processing runtime, a Node.js API, and a React dashboard. Developers can choose between a simplified Docker-based setup or a manual setup for more granular control over individual services.
The setup process involves installing prerequisites, configuring environment variables, building the necessary components, and running the services. This document covers both methods, along with key scripts for development, testing, and maintenance.
Sources: README.md:3-5, 101-102
Prerequisites
Before starting, ensure the following tools are installed on your system:
- Node.js: Version 22+
- Rust: Version 1.70+ (installed via
rustup) - Docker: For the containerized setup method
- Docker Compose: For the containerized setup method
Sources: README.md:105-110, package.json:44-46
Monorepo Structure
The project is organized as a monorepo, with applications, shared packages, and tools located in distinct directories.
kodus-runtime/
├── 📁 apps/ # All applications
│ ├── api/ # API Node.js (Elysia)
│ ├── dashboard/ # Dashboard React (Vite)
│ └── runtime/ # Runtime Rust (event-driven)
├── 📁 packages/ # Shared packages
│ ├── auth/ # Authentication utilities
│ ├── config/ # Shared configurations
│ ├── types/ # TypeScript types
│ └── ui/ # React components
├── 📁 tools/ # Development tools
│ ├── scripts/ # Automation scripts
│ └── docker/ # Docker configurations
├── 📁 config/ # Global configurations
└── package.json # Root package configuration
This diagram illustrates the high-level directory structure of the monorepo.
Sources: README.md:68-84, package.json
Docker Method (Recommended)
The easiest way to get the entire system running is by using Docker Compose. This method builds and runs all services in isolated containers.
Sources: README.md:112-113
Running with Docker Compose
Two primary commands are available for running the application with Docker:
- Production Mode: Starts all services.
npm run docker:up - Development Mode: Starts all services with hot-reloading enabled for the Node.js API and React Dashboard.
npm run docker:dev
The following diagram shows the services managed by Docker Compose.
Sources: README.md:117-123, package.json:35-38
Access URLs
Once the containers are running, the services are accessible at the following URLs:
- Dashboard:
http://localhost - API:
http://localhost:3201 - API Health Check:
http://localhost:3201/api/health
Sources: README.md:125-129
Docker Commands
The root package.json provides several scripts for managing the Docker environment:
| Command | Description |
|---|---|
npm run docker:up | Starts all services in production mode. |
npm run docker:down | Stops all services. |
npm run docker:dev | Starts all services in development mode with hot-reload. |
npm run docker:build | Builds the Docker images for the services. |
npm run docker:logs | Tails the logs from all running containers. |
npm run docker:status | Shows the status of the containers. |
npm run docker:clean | Stops and removes containers, volumes, and unused images. |
Sources: README.md:175-189, package.json:35-41
Manual Method
The manual setup provides more direct control over each component of the system and is ideal for focused development on a specific service.
Sources: README.md:138-139
Installation Flow
The following diagram outlines the manual installation process.
Sources: README.md:143-154
Step-by-Step Installation
- Clone the repository:
git clone <repository-url> cd kodus-runtime - Configure environment variables: Copy the example environment file and edit it as needed.
cp config/environment.example .env - Install Node.js dependencies: This will install dependencies for all workspaces (API, dashboard, shared packages).
yarn install - Build the Rust runtime:
cargo build --release - Run all services: This command concurrently starts the API and the dashboard.
yarn run dev:all
Sources: README.md:144-154, package.json:28-34
Environment Configuration
Create a .env file in the root directory by copying config/environment.example. Key variables to configure include:
| Variable | Description | Default/Example |
|---|---|---|
PORT | The port for the API server. | 3000 |
JWT_ACCESS_SECRET | Secret key for signing JWT access tokens. | your-secret-key-here |
OTEL_EXPORTER_OTLP_ENDPOINT | Endpoint for OpenTelemetry data. | http://localhost:4317 |
Sources: README.md:158-165
Running Services Individually
You can run each service independently using the following commands from the root directory:
-
API only: Starts the Elysia API server.
yarn dev:api- Access at:
http://localhost:3201 - Sources: package.json:32, apps/api/package.json:11, README.md:170
- Access at:
-
Dashboard only: Starts the React/Vite development server.
yarn dev:dashboard- Access at:
http://localhost:5173 - Sources: package.json:33, apps/dashboard/package.json:8, README.md:173
- Access at:
Verification
After starting the services, you can verify the setup by making requests to the API:
- Check API health:
curl http://localhost:3201/api/health - Log in to get a token:
curl -X POST http://localhost:3201/api/auth/login \ -H "Content-Type: application/json" \ -d '{"email": "admin@kodus.dev", "password": "admin123"}' - Create an event using the token:
curl -X POST http://localhost:3201/api/events \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"payload": {"test": "ok"}, "source": "setup-test"}'
Sources: README.md:193-207
Data Management
The Rust runtime persists data to the local filesystem.
Data Directory Structure
data/: Contains the Sled database files (db,snap.*,blobs/). This directory is not tracked by Git.
Sources: README.md:211-217
Cleaning Development Data
A script is provided to remove all generated data, build artifacts, and logs. This is useful for starting with a clean slate.
# Run the cleanup script
./tools/scripts/cleanup.sh
The script performs the following actions:
- Removes
data/,target/testdb/ - Removes build artifacts like
target/,dist/,build/ - Removes log files
- Removes
node_modules/and other Node.js temporary files