Skip to main content

Daikoku Development Guide

This guide aims at helping people willing to contribute to the Daikoku codebase. This guide will help you set up a full Daikoku development environment — including PostgreSQL (via Docker), the frontend (Vite), and the backend (Scala + Play) — with live reload enabled.

With mise​

The easiest way to get started with Daikoku is through the use of mise.

This section assumes that you have mise installed.

Installing dependencies​

Below command wil install frontend dependencies, doc dependencies, playwright, backend dependencies & pull needed docker images.

mise run install

Running Daikoku with demo data​

Below command will run Daikoku in a dev setup.

mise run dev

Once everything is started, browser to http://localhost:5173 to get started.

In this mode source code update will trigger frontend hot reload / backend recompilation.

To login see demo-data.

Running Daikoku without demo data​

Below command will run Daikoku in a dev setup without any data.

mise run dev --mode empty

Once everything is started, browser to http://localhost:5173 to get started.

In this mode source code update will trigger frontend hot reload / backend recompilation.

Default user is admin@daikoku.io and default password is password.

Running tests​

Backend tests​

Below command will run backend test (one shot):

mise run test:back

Alternatively, below command will start backend test dependencies, this will allow you to run/debug tests yourself (throught sbt test or Intellij).

mise run pg

Frontend tests​

LDAP​

Below command will run all necessary dependencies and open Playwright UI for LDAP tests

mise run dev --mode ldap --test

You can browse to http://localhost:5173 to use frontend.

Moreover, as for previous dev command, source code update will trigger frontend hot reload / backend recompilation.

If you just want to start test setup without playwright UI, you can just run

mise run dev --mode ldap

OIDC​

Below command will run all necessary dependencies and open Playwright UI for OIDC tests

mise run dev --mode oidc --test

You can browse to http://localhost:5173 to use frontend.

Moreover, as for previous dev command, source code update will trigger frontend hot reload / backend recompilation.

As for ldap, you can juste start test setup without playwright UI by running :

mise run dev --mode oidc

Documentation​

Below command will start documentation in dev mode

mise run doc

Once everything is started, browse to http://localhost:3000/daikoku/

Keep postgres instance running​

If you want to keep a postgres instance running accross your dev / test tasks, run below command in a separated terminal.

mise run pg

All above mise command will detect that a postgres is already running and won't shut it down when terminated.

Without Mise​

Replace or export $DAIKOKU_PROJECT_ROOT with your local daikoku project path, for example ~/projects/daikoku in case you did something like git clone git@github.com:MAIF/daikoku.git ~/projects/daikoku

Prerequisites​

Make sure you have the following installed:

  • JDK 21+
  • sbt 1.X
  • Node LTS & npm (Vite requires a modern Node version)
  • Docker/colima/podman/... (to run PostgreSQL, Otoroshi and other needed containers for various need)

Installing dependencies​

Frontend depdendencies​

cd $DAIKOKU_PROJECT_ROOT/daikoku/javascript
npm install
npx playwright install chromium

Doc dependencies​

cd $DAIKOKU_PROJECT_ROOT/manual
npm install

Run daikoku in dev mode​

Potsgres​

Run a local PostgreSQL dedicated to Daikoku, you should keep this running in a dedicated shell all the time (for dev & tests).

cd
docker-compose -f $DAIKOKU_PROJECT_ROOT/dev/docker-compose-pg.yml up
Default connection info
  • Host: localhost
  • Port: 5432
  • Database: daikoku (or daikoku_test for tests)
  • User / Password: postgres / postgres

Frontend​

cd $DAIKOKU_PROJECT_ROOT/daikoku/javascript
npm run dev

By default, the UI will run on http://localhost:5173.

Backend​

First start a sbt shell with below commands

cd $DAIKOKU_PROJECT_ROOT/daikoku
sbt

Then in sbt shell start backend with "hot reload":

if you want demo data already loaded, use below command:

~run -Dconfig.resource=local.conf -Ddaikoku.init.data.from=../dev/config/daikoku_state_light.ndjson

if you prefer a fresh daikoku instance, use below command:

~run -Dconfig.resource=local.conf

This will automatically reload the backend each time you change Scala or configuration files.

Open the Application​

  • Frontend (Vite): http://localhost:5173
  • Backend (Play): runs on its default port (typically 9000, depending on config)

👉 Open your browser at http://localhost:5173 to start working. An error may be displayed at first while Daikoku backend setups the database. Just wait a few seconds an refresh to see Daikoku UI.

Login​

With some demo data​

See demo-data.

Without demo data​

If you started your Daikoku instance without demo data, a default password will be generated, and user / password will be visible in Daikoku logs.

Running backend tests​

To tun backend test, you'll first need to run postgres (if not already done) :

cd
docker-compose -f $DAIKOKU_PROJECT_ROOT/dev/docker-compose-pg.yml up

Then you can run backend test using either your IDE or

cd $DAIKOKU_PROJECT_ROOT/daikoku
sbt test

Running frontend tests​

First of all, you'll need a running postgres instance (if not already started):

cd
docker-compose -f $DAIKOKU_PROJECT_ROOT/dev/docker-compose-pg.yml up

LDAP​

First start backend

cd $DAIKOKU_PROJECT_ROOT/daikoku
DAIKOKU_POSTGRES_DATABASE=daikoku_test DAIKOKU_INIT_ADMIN_PASSWORD=password DAIKOKU_OTOROSHI_SYNC_CRON=false DAIKOKU_TENANT_PROVIDER=hostname DAIKOKU_EXPOSED_ON=5173 DAIKOKU_INIT_DATA_FROM=javascript/tests/config/daikoku/daikoku_state_local_test.ndjson DAIKOKU_MODE=dev DAIKOKU_HEALTH_ACCESS_KEY=secret sbt "~run"

Finally start frontend

cd $DAIKOKU_PROJECT_ROOT/daikoku/javascript
npm run dev

You can start tests, for instance with UI:

cd $DAIKOKU_PROJECT_ROOT/daikoku/javascript
npx playwright test --workers 1 --config ./tests/playwright.config.js --ui --project chromium

OIDC​

First start backend

cd $DAIKOKU_PROJECT_ROOT/daikoku
DAIKOKU_POSTGRES_DATABASE=daikoku_test DAIKOKU_INIT_ADMIN_PASSWORD=password DAIKOKU_OTOROSHI_SYNC_CRON=false DAIKOKU_TENANT_PROVIDER=hostname DAIKOKU_EXPOSED_ON=5173 DAIKOKU_INIT_DATA_FROM=../dev/config/daikoku_state_oidc.ndjson DAIKOKU_MODE=dev DAIKOKU_HEALTH_ACCESS_KEY=secret sbt "~run"

Finally start frontend

cd $DAIKOKU_PROJECT_ROOT/daikoku/javascript
npm run dev

You can start tests, for instance with UI:

cd $DAIKOKU_PROJECT_ROOT/daikoku/javascript
npx playwright test --workers 1 --config ./tests/playwright.oidc.config.js --ui --project chromium

Running doc​

cd $DAIKOKU_PROJECT_ROOT/manual
npm start

Demo data​

If you did setup you Daikoku instance with pre-defined data, you'll have to use one of the following users:

Contribution Tips​

Before opening a pull request:

  • Run all available tests and linters.

  • Clearly describe:

    • What problem or feature your change addresses.
    • The potential impact or breaking changes.
    • How to manually test your change.

Happy hacking 💥 Welcome to the Daikoku developer community! Join us in Discord Join the chat on Discord