Skip to main content

Developing Izanami

Here are some tips to help you get started with Izanami contribution.

Cloning remote repository​

git clone git@github.com:MAIF/izanami.git
cd izanami

Using mise​

Tools​

The easiest way to setup your dev environment is to use mise.

You'll also need a docker environment (docker / podman / colima).

Setup up environment​

Once you installed mise, run below command to setup you dev environment:

mise install # Install needed dependencies (sbt, java, node, ...)
mise run install # Install front & back dependencies, pull docker images

Running the app​

To run Izanami, run below command

mise run dev

This will run frontend, backend and a bunch of docker containers (postgres, fake mail provider, fake oidc server, ...).

This command display log nicely using process-compose, a nice TUI that allows seeing logs / state for each application component (back, front & containers).

Running only containers​

To run only containers, use

mise run dev:containers

Running only backend​

To run only containers, use

mise run dev:back

``

Running only frontend​

To run only containers, use

mise run dev:front

Running tests​

Backend​

To run backend tests, use

mise run test:back

⚠️ Backend tests restart Izanami backend with misc configurations, therefore Izanami backend must not be started to run these tests.

Frontend​

To run frontend tests, use

mise run test:front

⚠️ Frontend tests start backend with a test specific configuration, therefore Izanami backend must not be started to run these tests.

Both​

Command

mise run tests

Runs frontend tests then backend tests.

Documentation​

To start documentation locally, run

mise run doc

Packaging​

To package Izanami :

mise run package

To start packaged jar (you'll need docker container running, you can use mise run dev:containers).

mise run package:run

To build docker image (after packaging frontend and backends)

mise run docker:build

To test docker image (you'll need docker container running, you can use mise run dev:containers).

mise run docker:run

To build "test" docker image (docker image with embeded postgres)

docker:build-demo

Clean up​

Docker containers may keep running even after command are terminated, to stop all container associated with Izanami run

mise run clean

Without mise​

Here is what you'll need to run Izanami without mise

  • SBT > 1.9.7
  • JDK >= 21
  • Node > 20
  • Docker / Colima / Podman whatever allows you to run docker-compose

Install dependencies​

For backend

sbt compile

For frontend

cd izanami-frontend
npm install --force
npx playwright install chromium

To pull images

docker-compose pull

Running project​

First let's start some containers, docker-compose.yml contains everything that may be needed by Izanami (mock SMTP server, WASMO, simple OIDC provider, postgres database, ...). You may delete some of these elements to reduce consumed resources, however you need to keep the Postgres database.

# In root directory
docker-compose up

Now let's start the backend

# Opening 5005 port allows to plug in Izanami for debug
sbt -jvm-debug 5005
# You may add -Dapp.sessions.TTL=604800 to have longer login sessions
~run -Dconfig.resource=dev.conf

And finally let's start frontend application

cd izanami-frontend
npm run dev

After eveyrhing is started, browse to http://localhost:3000 (login form may take some time to respon since compilation is started on first backend request).

Running tests​

Backend tests​

To run backend tests, you will need to start Izanami and associated containers independently.

To do so, just start the backend and the docker containers with the above commands.

Once backend and containers are started, just run

sbt "testOnly *AllTests"

Backend test without starting container​

Alternatively, you can run one test suite directly (without Izanami and containers running). The suite will start everything for you, however this is way slower than above method and still highly experimental.

If you're using Colima instead of docker, this method may require the following env variables to be set :

DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock;
RYUK_CONTAINER_PRIVILEGED=true;
TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE=/var/run/docker.sock

Frontend tests​

As for backend tests, you'll docker containers started to run frontend tests.

Izanami backend must be started using a specific configuration (this is needed for test that set up OIDC).

sbt "run -Dconfig.resource=base-test.conf -Dlogger.file=./test/resources/logback.xml"

You'll also need to start your frontend on localhost:3000 (using above commands).

Once everything is running, just run

cd izanami-frontend
npm test

To display playwright UI, use

npm test -- --ui

Serving documentation locally​

To run documentation, just install and start project in manual folder.

cd manual
npm install
npm start

Packaging​

To package frontend :

cd izanami-frontend
npm run build

To package backend (make sure to package frontend first) :

sbt "set test in assembly := {}" clean assembly

To start generated jar (you need running containers).

java -Dconfig.resource=dev.conf -jar ./target/izanami.jar

To build docker image (after packaging frontend and backends)

docker build -t izanami .

To test docker image

docker run --env IZANAMI_PG_URI=postgresql://postgres:postgres@host.docker.internal:5432/postgres -p 9000:9000 izanami

To build "test" docker image (docker image with embeded postgres)

docker build -t izanami-test-standalone -f ./demo-docker-image/Dockerfile-pg-embeded .