Creating a development environment

This text is intended as a tutorial for CzechIdM developers with the goal to set up IDE, build CzechIdM in it and run the system. If you prefer quick glance at the code or need to start quickly, you can use Quick start with devstack.

1. Install Java and Maven

First install JDK and Maven:

Download Java 1.8 Oracle JDK (or OpenJDK), minor version at least 101 (it's necessary due to the certificate of Nexus repository, which uses Let's encrypt and its support was added in version 101). The guide was tested for jdk1.8.0_131.

Install Maven from your system packages, at least version 3.1 is required.

yum install maven
mvn -v

Note: If you installed Java separately from your system libraries, you should set the correct Java home for Maven in the file ".mavenrc", which you will create in your home directory. You put there the full path to your JDK:

export JAVA_HOME=/path/to/installed/jdk/

This way Maven will always use this JDK.

2. Download the source code

Download CzechIdM source code from GitHub:

git clone https://github.com/bcvsolutions/CzechIdMng.git

Check branch:

git branch

The development is always done on the branch "develop", so don't forget to switch to this branch:

git checkout -b develop origin/develop

To develop your own feature or fix a bug create new branch from develop

git checkout -b personal/YourName/feature_or_bugfix-name_of_your_branch

Create pull request to merge your branch to develop branch.

3. Install PostgreSQL

CzechIdM in "dev" profile uses PostgreSQL as the repository. You have to install it at least in basic configuration:

Install necessary packages:

yum install postgresql postgresql-server postgresql-init

Fedora 25 packages:

dnf install postgresql-server postgresql-contrib

First run of the service:

systemctl start postgresql.service

If the following error occurs: "Job for postgresql.service failed. See 'systemctl status postgresql.service' and 'journalctl -xn' for details." Try initializing the PostgreSQL first and start the database again:

postgresql-setup --initdb --unit postgresql

Set automatic start of the service when starting OS:

systemctl enable postgresql.service

Set the configuration file for the database to accept login and password (change METHOD from ident to md5)

vim /var/lib/pgsql/data/pg_hba.conf

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local        all                   all                                                peer
# IPv4 local connections:
host         all                  all                127.0.0.1/32             md5
# IPv6 local connections:
host         all                  all                ::1/128                     md5

Restart the service to load the changes:

systemctl restart postgresql.service

Create the database: (Make sure you have installed and allowed en_US locale in your OS)

su postgres -c psql postgres
CREATE USER idmadmin PASSWORD 'idmadmin';
CREATE DATABASE "bcv_idm_storage" WITH OWNER idmadmin ENCODING 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8' template template0;

4. Backend development environment

The tutorial is different for each IDE. Select one and continue with a certain tutorial below:

In the IDE start the Tomcat server with CzechIdM deployed.

In browser access http://localhost:8080/idm-backend/api/v1/status to check whether the backend is running. Following text should be displayed:

CzechIdM API is running
If you can see this message, API is running

5. Frontend development environment

BEWARE!!! This tutorial may be obsolete. Please use this instructions

In frontent project folder:

Node.js version 4.x.x or higher is required (npm version 3.6 or higher is required). Download and install Node.js by your OS.

Be sure to have these versions. When upgrading node by "n" is also "npm" changed usually to lower version than needed.

For linux (fedora):

dnf install nodejs

Check nodejs version:

node -v

Check npm version:

npm -v

For update nodejs from 0.x versions:

Install gulp as global

Gulp version 3.9.0 is required.

npm install gulp@3.9.0 -g

Check gulp version:

gulp -v

First go to directory czechidm-app. It is basic application module keep dependencies on other sub-module. This module will start whole application.

cd czechidm-app

Run script modules-link defined in package.json. This script will create directory nodemodules in parent directory and create symlink on him in czechidm-app. This prevents the problem with multiple copies of React (https://facebook.github.io/react/warnings/refs-must-have-owner.html). The goal is to have only one nodemodules directory (for all ours modules) with React.

IMPORTANT! Module-link script does not work on Windows. If are you Windows user, then you have to create symlink on node_modules (in parent directory) manually (use command 'mklink /D').
npm run modules-link
npm run czechidm-modules-link

Install basic dependencies for application module (will be common for all submodules ).

npm install

Install the dependencies for core module

Now we need to install mandatory core module. Go to core directory. You can use symlink in czechidm-modules.

cd czechidm-modules/czechidm-core

Install NPM dependencies. Most of dependency are installed within czechidm-core module. It is important for prevent problem with multiple copies of React. In this module is React present only in peer dependency. Peer dependency warnings are OK.

npm install

Go to app module.

cd ../../

We can install other application modules. We will install optional example module czechidm-example.

All application modules are in czechidm-modules directory (in czechidm-app). Go to him and create symlink on example module.

cd czechidm-modules
ln -s ../../czechidm-example
IMPORTANT! If are you Windows user, then you have to create symlink with command 'mklink /D' e.g.
mklink /D d:\Projekty\BCV\CzechIdMng\Realization\frontend\czechidm-app\czechidm-modules\czechidm-acc d:\Projekty\BCV\CzechIdMng\Realization\frontend\czechidm-acc

Go to the example module. You can use symlink in czechidm-modules.

cd czechidm-example

Install NPM dependencies.

npm install

Go to app module.

cd ../../

If you are developing a custom module (for example named as "czechidm-ext") that is not part of our product, you need to do the following:

  • We have the product installed in the projects/CzechIdM/ folder.
  • The czechidm-app module is in the projects/CzechIdM/Realization/frontend/czechidm-app/.
  • For example, the externally developed module (frontend part) czechidm-ext is in the projects/ExternalModule/Realization/frontend/czechidm-ext/ folder.

First, we create the symlink to the "czechidm-ext" module:

cd projects/CzechIdM/Realization/frontend/czechidm-app/czechidm-modules
ln -s ../../../../../ExternalModule/Realization/frontend/czechidm-ext

Then we create a symlink from the external module to the product "nodemodules". This prevents the problem with multiple copies of React (https://facebook.github.io/react/warnings/refs-must-have-owner.html). The goal is to have only one nodemodules directory (for all modules) with React.

cd ../../../../../ExternalModule/Realization/frontend/czechidm-ext
ln -s ../../../../CzechIdM/Realization/frontend/node_modules

After when we have installed all required modules, we have to copy them together. Its means create symlinks from czechidm-modules to app node_modules.

cd ../czechidm-app
gulp makeModules
gulp test

You can use any text editor or JavaScript IDE. We recommend to use ATOM

6. Run backend and frontend together

Assume running backend from the previous steps.

In the project root folder:

Start frontend

cd CzechIdM/Realization/frontend/czechidm-app
gulp

A new browser window or tab will open with https://localhost:3000 automatically (this could take some time).

The frontend is fully started after you see in following line in log:

[BS] 1 file changed (app.js)

After the application is running, log in:

  • username: admin
  • password: admin
If the app shows error with permission, log out
To use CzechIdM in more windows or tabs for development purposes go to http://localhost:3001/ to BrowserSync administration and then go to SyncOptions and disable everything except CodeSync

Congratulations! Your CzechIdM development environment is ready to use.

Common development errors & tips

If Tomcat server fails to start, try following:

  • Increase the timeout for Tomcat server Start (see Install Tomcat)
  • Check that PostgreSQL server is running.
systemctl status postgresql.service
  • Check that PostgreSQL database exists and the user can connect: Use the credentials filled in idm-app/src/main/resources/application-dev.properties and try to connect to the PostgreSQL database written in the datasource URL. E.g. for this setup:
spring.datasource.url=jdbc:postgresql://localhost:5432/bcv_idm_storage
spring.datasource.username=idmadmin
spring.datasource.password=idmadmin

use the following command and type the password when asked for it.

psql -h 127.0.0.1 -U idmadmin bcv_idm_storage
  • Check that you can read from the tables of the database. As in the previous point, connect to the PostgreSQL database and try to select data from any of the IdM tables. If you have insufficient access rights, check the owner and grants for the schema "public". If the user idmadmin is not an owner, there must be GRANT on schema public to the user idmadmin or to "public".
  • Check the error message in the server output console.

Common error messages

Initialization of bean failed; nested exception is org.flywaydb.core.api.FlywayException: Validate failed: Migration checksum mismatch for migration 7.07.004 means that your database was already used for some other version of CzechIdM (you can check used Flyway versions in the tables idm_schema_version_xxx). This can happen if you switch to some older development branch. The easiest solution for the developer (you will lose all your prepared data in IdM!) is to drop the database (DROP DATABASE bcv_idm_storage) and create it again (see the part CREATE DATABASE of Install PostgreSQL). Or you can create a different database and set its name to the application-dev.properties temporarily.

Initialization of bean failed; nested exception is org.flywaydb.core.api.FlywayException: Found more than one migration with version 7.07.004 means literally that there is a duplicity in Flyway scripts versions. This has to be fixed by the authors of the scripts by renaming one of the script that use the same version. The log will tell you where to find the duplicity:

Offenders:
-> ... idm-core-impl-7.7.0-SNAPSHOT.jar!/eu/bcvsolutions/idm/core/sql/postgresql/V7_07_004__automatic-role.sql (SQL)
-> ... idm-core-impl-7.7.0-SNAPSHOT.jar!/eu/bcvsolutions/idm/core/sql/postgresql/V7_07_004__add-index-template-name.sql (SQL)

Just increase the version in the name of one of the scripts, clean & build the project again.