Quick Start: Docker Setup
Relevant source files
The following files were used as context for generating this wiki page:
The kodus-runtime project provides a comprehensive Docker setup, which is the recommended method for getting the application running quickly. This setup uses Docker Compose to orchestrate all the necessary services, including the Node.js API, the React Dashboard, and persistent data volumes. It supports both production and development environments, with the latter offering features like hot-reloading.
This guide covers the architecture of the Docker setup, the different environments, and the scripts provided to manage the container lifecycle. The main goal is to simplify the installation and setup process, allowing developers to start the entire system with a single command.
Sources: README.md:50-52
Prerequisites
Before you begin, ensure you have the following tools installed on your system:
- Docker
- Docker Compose
Sources: README.md:44-47, tools/docker/docker-up.sh:10-13
Docker Architecture
The Docker environment is defined using docker-compose.yml for production and docker-compose.dev.yml for development. It consists of multiple services that work together to provide the full functionality of Kodus Runtime.
The following diagram illustrates the high-level architecture of the services orchestrated by Docker Compose.
Services
The Docker setup defines the following services:
| Service | Container Name | Ports | Description | Source File |
|---|---|---|---|---|
| API | kodus-api | 3201:3201 | The Node.js (Elysia) backend API. It handles event processing, authentication, and communicates with the data store. | tools/docker/docker-compose.yml:5-26 |
| Dashboard | kodus-dashboard | 80:80 | The React frontend application, served via Nginx in production. | tools/docker/docker-compose.yml:29-43 |
| Database | kodus-database | N/A | A placeholder service. The actual database is Sled, which is embedded within the API service and persists data to a shared volume. | tools/docker/docker-compose.yml:47-58 |
Data Persistence and Configuration
- Data Persistence: A local Docker volume named
datais used to persist application data. This volume is mounted to/app/datainside theapicontainer and/datain thedatabaseplaceholder container. This ensures that data, such as events stored by Sled, is not lost when containers are stopped or recreated. - Configuration: A
config.jsonfile from the host machine is mounted into theapicontainer at/app/config.json. If this file does not exist, the startup scripts will create it fromconfig/config.example.json.
Sources: tools/docker/docker-compose.yml:22-23, tools/docker/docker-up.sh:18-22, tools/docker/docker-compose.dev.yml:22-24
Environment Setups
The project provides two distinct Docker environments: Production and Development.
Production Environment
This is the recommended setup for a stable, production-like deployment. It uses pre-built application artifacts.
- Compose File:
tools/docker/docker-compose.yml - Startup Script:
npm run docker:upor./tools/docker/docker-up.sh - Key Features:
- The API runs a pre-built
distversion usingnode. - The Dashboard is served by a lightweight Nginx server.
- Includes health checks for both
apianddashboardservices.
- The API runs a pre-built
The following diagram shows the startup flow for the production environment.
Sources: tools/docker/docker-up.sh, package.json:28
Development Environment
This setup is optimized for active development, featuring hot-reloading for both the API and the Dashboard.
- Compose File:
tools/docker/docker-compose.dev.yml - Startup Script:
npm run docker:devor./tools/docker/docker-dev.sh - Key Features:
- The entire project directory is mounted as a volume, allowing for live code changes.
- The API runs using
tsx watchfor automatic restarts on file changes. - The Dashboard runs using the Vite development server (
vite) for Hot Module Replacement (HMR). - The API is accessible on port
3201and the Dashboard on5173.
Sources: tools/docker/docker-compose.dev.yml, package.json:30, tools/docker/docker-dev.sh
Environment Variables
Configuration is managed via environment variables passed to the containers.
| Variable | Service | Example Value | Description |
|---|---|---|---|
NODE_ENV | api, dashboard | production / development | Sets the application environment. |
PORT | api | 3201 | The port the API server listens on. |
CORS_ORIGIN | api | http://localhost:80 | Configures the allowed origin for CORS. |
JWT_ACCESS_SECRET | api | dev-access-secret | Secret key for signing JWT access tokens. |
JWT_REFRESH_SECRET | api | dev-refresh-secret | Secret key for signing JWT refresh tokens. |
DATABASE_URL | api | /app/data | Path to the Sled database directory inside the container. |
VITE_API_URL | dashboard (dev) | http://localhost:3201 | The base URL for the API, used by the dev dashboard. |
Sources: tools/docker/docker-compose.yml:12-17, tools/docker/docker-compose.dev.yml:13-18, 40-41
Managing Services
A set of NPM scripts are provided in the root package.json to simplify the management of the Docker containers.
| Command | Description | Underlying Script/Command |
|---|---|---|
npm run docker:up | Builds and starts all services in detached mode for production. | ./tools/docker/docker-up.sh |
npm run docker:down | Stops and removes all services defined in the production compose file. | ./tools/docker/docker-down.sh |
npm run docker:dev | Starts all services in attached mode for development (with hot-reload). | ./tools/docker/docker-dev.sh |
npm run docker:build | Builds or rebuilds the production service images. | docker-compose -f tools/docker/docker-compose.yml build |
npm run docker:logs | Tails the logs from all running production services. | docker-compose -f tools/docker/docker-compose.yml logs -f |
npm run docker:status | Shows the status of the production services. | docker-compose -f tools/docker/docker-compose.yml ps |
npm run docker:clean | Stops containers, removes volumes, and prunes the system. | docker-compose ... down -v ... && docker system prune -f |
Sources: package.json:27-33, README.md:112-125
Accessing the Application
Once the services are running using npm run docker:up, you can access them at the following URLs:
- Dashboard:
http://localhost - API:
http://localhost:3201 - API Health Check:
http://localhost:3201/api/health
For the development environment (npm run docker:dev), the Dashboard is available at http://localhost:5173.
Sources: README.md:59-62, tools/docker/docker-up.sh:40-43, tools/docker/docker-compose.dev.yml:38