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.

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

1) Prerequisites​

Make sure you have the following installed:

  • JDK 21+
  • Scala & sbt (latest recommended version)
  • Node LTS & npm (Vite requires a modern Node version)
  • Docker (to run PostgreSQL, and later Elasticsearch, Otoroshi and Minio)
  • a clone of the Daikoku code repository (git clone git@github.com:MAIF/daikoku.git)

2) Start dependencies in Docker​

Run a local PostgreSQL and an instance of otoroshi dedicated to Daikoku:

docker-compose -f $DAIKOKU_PROJECT_ROOT/daikoku/javascript/tests/docker-compose-very-local.yml up
Default connection info
  • Host: localhost
  • Port: 5432
  • Database: daikoku
  • User / Password: postgres / postgres

3) Start the Frontend (Vite Dev Server)​

In Terminal A, go to the javascript folder and start the Vite development server:

cd $DAIKOKU_PROJECT_ROOT/daikoku/javascript
npm install
npm run dev

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

4) Start the Backend in Hot Reload Mode​

In Terminal B, start the backend with sbt:

cd $DAIKOKU_PROJECT_ROOT/daikoku
sbt

Inside the sbt console:

With some demo data​

If you want to start Daikoku with pre-defined tenant, teams, ... Use below command.

~run -Dconfig.resource=local.conf -Ddaikoku.init.data.from=javascript/tests/config/daikoku/daikoku_state_very_local.ndjson

Without demo data​

If you want to start Daikoku without any pre-defined data use below command.

~run -Dconfig.resource=local.conf

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

5) 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.

6) Log in​

With some demo data​

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

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.

Troubleshooting​

Port 5173 already in use​

Change the Vite port (--port 5174) and the exposedPort (-Ddaikoku.exposedOn=5174) in sbt console or stop the conflicting process.

PostgreSQL connection issues​

Make sure the container is running:

docker ps | grep postgres_daikoku

Test database access:

docker exec -it postgres_daikoku psql -U postgres -d postgres -c '\dt'

sbt not reloading properly​

Ensure you’re running JDK 21+ and clear the build cache if needed:

sbt clean

Node dependency problems​

Clean and reinstall:

rm -rf node_modules package-lock.json
npm install

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