Explore Knowledge Base

Developer’s Onboarding Guide

31. 01. 2025

Developer Workstation Requirement

1. Developer Workstation Requirements
2. Setting Up the Development Environment
3. Docker setup
4. Maven setup
5. Configuring and start ‘SDK-5’ project
6. Prepare code for transferring to the Client
7. Working with SSL-certificates
8. Suggestion on applying source code patches and new features usage in the development purposes

1. Developer Workstation Requirements

Operating System

Ubuntu Linux operating system is our officially supported OS. This guide contains only recommendations for this OS.

If you want to use another OS, you are on your own. Use this guide as a reference.

OS Family

Notes

Linux

Ubuntu LTS (22.04) is recommended.

OS X

If you would want to use Docker, please note that there is no native kernel support for Docker in OS X at the moment. Containers will run in a hardware-emulated environment.

Windows

Windows 10 with Linux Subsystem is recommended.
If you would want to use Docker, please note that there is no native kernel support for Docker in Windows 10 at the moment. Containers will run in a hardware-emulated environment.

Required Software

  • Any preferable mail client

  • Any preferable chat or messenger

2. Setting Up the Development Environment

JDK Installation:

For Linux:

For Mac:

  1. Download OpenJDK for Mac OSX from http://jdk.java.net/ (for example Java 17)

  2. Unarchive the OpenJDK tar, and place the resulting folder (i.e. jdk-17.jdk) into your /Library/Java/JavaVirtualMachines/ folder since this is the standard and expected location of JDK installs. You can also install it anywhere you want in reality.

More details about the installation can be found at https://java.tutorials24x7.com/blog/how-to-install-openjdk-15-on-mac

To correct build and start a project with Java 17, for IntelliJ IDEA, you need to install the last version IntelliJ Lombok plugin – 0.33 !

GIT Installation and Configuration

Checklist:

  1. Install Git and Git flow packages

  2. Configure Git environment

  3. Generate your SSH keys

  4. Install your SSH public key into your GitLab account

For Linux:
Ubuntu Linux usually comes with Git pre-installed. Otherwise, use this command:

sudo apt install git git-flow

For Mac:

There are several ways to install Git on a Mac. In fact, if you’ve installed XCode (or it’s Command Line Tools), Git may already be installed. To find out, open a terminal and enter git --version.

Otherwise, the easiest way to install Git on a Mac is via the stand-alone installer:

  1. Download the latest Git for Mac installer.

  2. Follow the prompts to install Git.

Configure Git environment:

git config --global user.name "<your name>"
git config --global user.email <your e-mail>

To work with our GitLab, you will require to have your own key pair. It is used for authentication when using SSH transport.

If you already have one, you can use it. Otherwise, generate your key pair using:

ssh-keygen -t rsa -b 2048 -C "email@example.com"

Configure your GitLab account:

  1. Navigate to https://git.<your profile Name>/profile/keys

  2. Put contents of ~/.ssh/id_rsa.pub file into the “Key” field

DBeaver

 DBeaver is a database management tool.

For Linux:

Add DBeaver repository to your Debian / Ubuntu by running the commands below:

wget -O - https://dbeaver.io/debs/dbeaver.gpg.key | sudo apt-key add -echo "deb https://dbeaver.io/debs/dbeaver-ce /" | sudo tee /etc/apt/sources.list.d/dbeaver.list

After adding the repo, update the apt list and install DBeaver CE:

sudo apt update
sudo apt -y install dbeaver-ce

For Mac:

The installer distribution is the recommended way to install DBeaver on MacOS X. It contains all required dependencies. Besides this, the installer automatically upgrades DBeaver to the new version, if a previous version is already installed.

Installer for Mac available on – https://dbeaver.io/download/

Postman

You can install Postman on Linux via the Snap,  using the command

snap install postman

Accept invitation in email

Docker & Docker Compose

Full information on installing Docker and Docker Compose for different platforms is available on the official page https://docs.docker.com/engine/install/

3. Docker setup

For Linux:

docker login

docker login <Name of your subaccount>

and use credentials

Add to idea docker integration data: (for docker run tasks)

Developer’s Onboarding Guide

For Mac:

docker login <Name of your subaccount>

and use credentials:

developer / (password from admin)

Put the next string into /etc/hosts:

172.17.0.1 local.sdk.finance host.docker.internal

4. Maven setup

4.1. Install the maven

https://linuxize.com/post/how-to-install-apache-maven-on-ubuntu-20-04/

4.2 Create settings.xml

Find ~.m2 directory and put settings.xml here. (replace {login} and {password} with ldap credentials)

<?xml version="1.0" encoding="UTF-8"?><settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.1.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><servers> <server> <username>{login}</username> <password>{password}</password> <id>sdk</id> </server> <server> <username>{login}</username> <password>{password}</password> <id>sdk-spring</id> </server> <server> <username>{login}</username> <password>{password}</password> <id>sdk.artifactory</id> </server> <server> <username>{login}</username> <password>{password}</password> <id>snapshots</id> </server> <server> <username>{login}</username> <password>{password}</password> <id>sdk.spring.release</id> </server> <server> <username>{login}</username> <password>{password}</password> <id>sdk.spring.snapshots</id> </server></servers></settings>

4.3 IntelliJ IDEA plugin for maven

To resolve Transitive Dependencies collisions
Maven Helper – IntelliJ IDEs Plugin | Marketplace

5. Configuring and start ‘SDK-5’ project

5.1 Create a folder for projects

Create a folder for projects if it does not exist

In Terminal (Ctrl + Alt + T) run

mkdir ~/projects

5.2 Obtain project from the repository

5.2.1 Create a folder for the project if it does not exist

In Terminal (Ctrl + Alt + T) run

mkdir ~/projects/core

5.2.2 Open project in IDE

‘Core’ project repository

https://git.<your repository>

Clone → Clone with SSH → Copy URL

Launch IntelliJ IDEA → Get from Version Control

Developer’s Onboarding Guide

Choose ‘Version control’ Git, paste the copped URL into ‘URL’ and input into ‘Directory’ the project folder path
e.g.

URL:<link to your Git repository>
Directory: /home/username/projects/core

Clone

5.3 Build Run/Debug Configurations

  1. Create Spring Boot

Developer’s Onboarding Guide

2. Use for Main class sdk.finance.SdkFiveApplication

5.4 Run project

5.4.1 Start project databases

For start project databases:

  1. In Terminal run command  docker-compose up -d from project directory

  2. In IntelliJ IDEA:

  • Open the docker-compose.yml file.

  • Click in the gutter.

This creates a Docker Compose run configuration, which starts databases in containers as the db services.

5.4.2 Compile the source code of the project

To compile the source code of the project run

mvn clean compile

5.4.3 Run project

You can use the previously created Run/Debug configuration to run the application.

Click the button Run to create a project configuration.

Developer’s Onboarding Guide

Or open in IntelliJ IDEA Main class: SdkFiveApplication and click the button Run opposite the class definition

Developer’s Onboarding Guide

5.4.4 Switch to JDK17

  1. Download and install JDK17 on your local machine
    In IntelliJ IDEA: FileProject Structure…

Developer’s Onboarding Guide

Set JDK version

Developer’s Onboarding Guide

2. Set up project Run Configurations in IntelliJ IDEA

add to VM options:

--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.time=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED

by default spring.profiles.active=dev

To run an application:

Developer’s Onboarding Guide

To run Tests:
in VM Options:

--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.time=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED -Dspring.profiles.active=test
Developer’s Onboarding Guide

6. Prepare code for transferring to the Client

6.1 Maven repository .m2 is empty

6.2 Put custom libraries into a local Maven repository

6.2.1 Download lib file

lcl-core-2.0.0-RELEASE.jar

sdk5-openapi-2.0.1.jar

6.2.2 Run the command to put the lib into the repository

Execute the command to put the file lcl-core-2.0.0-RELEASE.jar into the local Maven repository (by default is ~/.m2/repository)

mvn install:install-file -Dfile=./lcl-core-2.0.0-RELEASE.jar -DgroupId=sdk.finance -DartifactId=lcl-core -Dversion=2.0.0-RELEASE -Dpackaging=jar

where -Dfile=<path-to-file>

Repeat the same action for lib sdk5-openapi-2.0.1.jar

all details look at maven specification Guide to installing 3rd party JARs – Maven

6.3 Compile the project

run the maven command to pull all required dependencies from the maven central repository and then compile the project

mvn clean compile

The whole process should take approximately 10 min. (look at the image) and the size of the .m2 folder should be approximately 208 Mb.

6.4 Set up and run application

6.4.1 Run docker containers

docker-compose -f docker-compose.yml up -d

6.4.2 Install JDK17

6.4.3 Run the project

VM options should be:

--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.time=ALL-UNNAMED --add-opens java.base/java.math=ALL-UNNAMED

6.5 Generate JavaDoc

run the maven command to generate JavaDoc

mvn -X clean javadoc:aggregate-jar

7. Working with SSL-certificates

There is a special configuration part in application.yaml that is responsible for traffic encryption:

server:
ssl:
enabled: true
key-store: classpath:keystore.p12
key-store-type: PKCS12
key-store-password: 1234
key-alias: mykey

Here is a brief explanation of each parameter:

  • enabled – enable or not the traffic encryption. In case of false, all other parameters can be omitted

  • key-store – location and the name of the key-store file that will be used for the traffic encryption.
    By default, it is included in the app and classpath: is used to define the location.
    Key-store location in the project path is /base/core/core-services/src/main/resources/keystore.p12
    To use different locations outside the app a full path with the file name should be provided. For example, /opt/sdk/security/keystore.p12.
    We recommend storing this file in a different directory from the application.

  • key-store-type – the type of the key-store. We recommend using PKCS12 as it’s easier to maintain them.
    If you want/need to use another type of storage, you can refer to the official Spring documentation.

  • key-store-password – The password for the key-store.

  • key-alias – The alias of the key inside the key store.

7.1. Create a key-store

To generate a .p12 file from a private key (.key) and a public certificate (.crt), you can use the OpenSSL command. Here is an example:

openssl pkcs12 -export -out keystore.p12 -inkey private.key -in certificate.crt -name "mykey"

Explanation:

  • -export — indicates the creation of a .p12 file.

  • -out output.p12 — the name of the output file that will be created.

  • -inkey private.key — the path to your private key.

  • -in certificate.crt — the path to your public certificate.

  • -name "mykey" — the alias name you want to assign to the certificate in the .p12 file.

When you run the command, OpenSSL will prompt you to set a password to protect the .p12 file.

If you also need to include a certificate chain (e.g., intermediate certificates), add the -certfile option:

openssl pkcs12 -export -out keystore.p12 -inkey private.key -in certificate.crt -certfile chain.crt -name "mykey"

7.2. List aliases in the key-store

To list the available aliases in a Java KeyStore (.jks or .p12 file), you can use the keytool command provided by the JDK. Here’s how you can do it:

keytool -list -keystore <keystore-file> -storepass <store-password>

Explanation:

  • -list — tells keytool to list all aliases in the specified keystore.

  • -keystore <keystore-file> — path to the keystore file (for example, keystore.jks or keystore.p12).

  • -storepass <store-password> — the password for accessing the keystore.

For example:

keytool -list -keystore keystore.p12 -storetype PKCS12 -storepass mypassword

8. Suggestion on applying source code patches and new features usage in the development purposes

  1. After receiving the source code, create new separate branches:

    1. initial_source_code – for applying patches from SDK.

    2. set of branches for development and production.

  2. After receiving the patch file 4.24.1-patch create a new branch from initial_source_code branch with a certain name (e.g., release_4.24.1)
    and then apply the patch to this new branch.

  3. Merge this branch release_4.24.1 into initial_source_code.

  4. Read release notes related to the patch.

  5. Choose an appropriate feature in the updated initial_source_code branch.

  6. Copy the code related to the selected feature and paste it into a development branch.