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.js 22.x & 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)
tip

If you use nvm, you can install Node 22 easily:

nvm install 22
nvm use 22
node -v   # should show v22.x
npm -v
tip

If you use coursier, you can install Scala and sbt easily:

cs install scala sbt
scala -version
sbt -version

2) Start PostgreSQL in Docker​

Run a local PostgreSQL instance dedicated to Daikoku:

docker run --name daikoku-pg \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=default \
  -p 5432:5432 \
  -d postgres:17
Default connection info
  • Host: localhost
  • Port: 5432
  • Database: default
  • 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 start

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

4) Prepare static files for backend (development mode)​

In Terminal B, copy the frontend index.html into the backend’s public folder so that the backend can serve the dev UI correctly:

cp $DAIKOKU_PROJECT_ROOT/daikoku/javascript/index.html \
   $DAIKOKU_PROJECT_ROOT/daikoku/public/index.html

This step ensures the backend and frontend stay in sync while developing.

5) Start the Backend in Hot Reload Mode​

In Terminal B, start the backend with sbt and enable continuous compilation:

cd $DAIKOKU_PROJECT_ROOT/daikoku
sbt

Inside the sbt console:

~run

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

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

Troubleshooting​

Port 5173 already in use​

Change the Vite port (--port 5174) or stop the conflicting process.

PostgreSQL connection issues​

Make sure the container is running:

docker ps | grep daikoku-pg

Test database access:

docker exec -it daikoku-pg psql -U daikoku -d daikoku -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
  1. Backend running in Terminal B with sbt ~run for live reload.
  2. Frontend running in Terminal A with npm start for HMR (hot module reload).
  3. Open http://localhost:5173 and iterate!

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!