Modules - Tool [tool]

Source documentation on Github.

## Features

- Release product version - release product under final version, new development version will be set, tag will be prepared. - Release module version - release module under final version, new development version will be set, tag will be prepared. - Change product version - set version for all modules. - Get product version - for test reasons only. - Build product version - for test reasons only. - Build project - use released product and install additional released modules and libraries.

## Requirements

- Install ``maven`` - at least version ``3.1`` is required (Configure ``MAVEN_HOME`` environment property or use ``–maven-home`` IdM tool argument). If libraries for maven build are downloaded automatically, then maven repositories (e.g. https://repo1.maven.org/maven2/, https://nexus.bcvsolutions.eu/repository/maven-public-releases) has to be available. Libraries have to be prepared in local maven repository otherwise. - Node and npm:

1. are downloaded, extracted and put into a node folder created in your installation directory (``target``) automatically (we are using [frontend-maven-plugin](https://github.com/eirslett/frontend-maven-plugin#frontend-maven-plugin)). Node repositories (e.g. https://nodejs.org/dist) has to be available. Node/npm will be "installed" locally to your project, it will not be installed globally on the whole system (and it will not interfere with any Node/npm installations already present).
2. or can be installed globally and used by ``–node-home`` IdM tool argument.
3. third party node modules are downloaded automatically from public node repository.

- ``Java 1.8`` usage is required by conventions. Artefacts have to be built under ``Java 1.8`` version. Java 11 is supported @since version 10.0.0., but we decide to not use it - artefact will run on environment with ``Java 1.8`` version.

## How to get the tool

Executable tool is available in idm.war artefact on path ``<idm.war>/WEB-INF/idm-tool.jar``. If tool is copied into another place, then don't forget to copy whole ``lib`` folder together with tool. Tool itself reusing CzechIdM libraries and product modules.

Error: Could not find or load main class eu.bcvsolutions.idm.tool.ConsoleRunner

Caused by: java.lang.NoClassDefFoundError: org/bouncycastle/jce/provider/BouncyCastleProvider
	at org.eclipse.jgit.lib.GpgSigner.<clinit>(GpgSigner.java:58)
	at org.eclipse.jgit.api.CommitCommand.processOptions(CommitCommand.java:611)

## How to build the tool from source

Standalone ``idm-tool.jar`` can be build under ``dist`` profile from the product sources (this repository). In the tool module folder (checkout master or develop branch is needed):

mvn clean package -Pdist -DskipTests

Executable jar will contain all required libraries (all-in-one-jar).

Commands examples expects idm-tool.jar is placed in the same parent folder, where the product or module root folder is.

## Tool arguments

Available tool parameters:

java -jar idm-tool.jar -h

### Command arguments

Available tool commands:

### Additional arguments

Additional / optional arguments can be combined with commands above:

–password | git password / token / ssh passphrase | If ssh repository is used / cloned, then passphrase for ssh key is needed only.<br /> If https repository is used / cloned, then git username and password is needed.<br />If two-factor authntication is enabled for <username>, then token has to be given (see git documentation, how to generate authentication token for developers).<br />If ssh key is used, then put passphrase for ssh key (It loads the known hosts and private keys from their default locations (identity, id_rsa and id_dsa) in the user’s .ssh directory.).| |

## Tool return codes

## Tool external configuration

### Configuration file

External ``application.properties`` configuration can be used, placed in the same folder as executable idm-tool.jar with content:

## CzechIdM tool external properties
# password is supported only

## Git password / token / ssh passphrase
# If ssh repository is used / cloned, then passphrase for ssh key is needed only
# If https repository is used / cloned, then git username and password is needed.
# If two-factor authntication is enabled for <username>, then token has to be given (see git documentation, how to generate authentication token for developers).
# If ssh key is used, then put passphrase for ssh key (It loads the known hosts and private keys from their
# default locations (identity, id_rsa and id_dsa) in the user’s .ssh directory.).
idm.sec.tool.password=xxxxx

When password is set in property file, then no password is needed as tool argument (prevent to have password in bash history).

Password is required for ``release-publish`` or ``–publish`` command. If password is not given as argument nor property file, then console prompt for enter password will be shown.

### Logging

Tool log file ``spring.log`` is placed by default in system temp directory. We are using ``logback`` library for logging. External logback configuration can be given to change logs location, logger levels etc.

You may specify the location of the logback configuration file with a system property named ``logback.configurationFile``. The value of this property can be a URL, a resource on the class path or a path to a file external to the application. Example with ``logback.xml`` placed in the same folder as executable ``idm-tool.jar``:

java -Dlogback.configurationFile=./logback.xml -jar idm-tool.jar --build -p

Example ``logback.xml`` configuration file content:

<?xml version="1.0" encoding="UTF-8"?>
<!-- https://springframework.guru/using-logback-spring-boot/ -->
<!-- http://logback.qos.ch/manual/appenders.html -->
<!DOCTYPE configuration>
<configuration>
	<include resource="org/springframework/boot/logging/logback/base.xml"/>

	<appender name="TOOL-LOG-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">

	  <file>./logs/tool.log</file>

	  <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
	    <Pattern>
	      %d{dd-MM-yyyy HH:mm:ss.SSS} [%thread] %-5level %logger{36}.%M - %msg%n
	    </Pattern>
	  </encoder>

	  <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
	    <fileNamePattern>
	    	./logs/tool_%d{dd-MM-yyyy}_%i.log
	    </fileNamePattern>
	    <maxFileSize>10MB</maxFileSize>
	    <maxHistory>10</maxHistory>
	    <totalSizeCap>100MB</totalSizeCap>
	  </rollingPolicy>

	</appender>

    <logger name="eu.bcvsolutions.idm.tool" level="DEBUG">
    	<appender-ref ref="TOOL-LOG-FILE" />
    </logger>
    <logger name="org.eclipse.jgit" level="INFO">
    	<appender-ref ref="TOOL-LOG-FILE" />
    </logger>
</configuration>

### Release product

Usable for CzechIdM 10.x version and for LTS 9.7.x version.

java -jar idm-tool.jar --release --release-version 10.0.0 --develop-version 10.1.0-SNAPSHOT

Release product under ``–release-version`` argument. New development version will be set as ``–develop-version`` argument.

Local commits in master and develop branches are prepared only. Local tag with release version is prepared too. Publish release into origin repository (after personal verification, if everything looks great :)):

java -jar idm-tool.jar --publish --username <git username> --password <ssh public key passphrase or git password or developer token>

Nexus credential has to be configured in maven for deploy artefacts into our private ``maven-releases`` repository.

Example of ``settings.xml``:

<settings>
  <servers>
    <!-- Nexus servers -->
    <server>
      <id>nexus</id>
      <username>username</username>
      <password>password</password>
    </server>
  </servers>

  <pluginGroups>
     <pluginGroup>external.atlassian.jgitflow</pluginGroup>
  </pluginGroups>

  <mirrors>
    <mirror>
      <id>nexus</id>
      <mirrorOf>*</mirrorOf>
      <url>https://nexus.bcvsolutions.eu/repository/maven-all/</url>
    </mirror>
  </mirrors>

  <profiles>
    <profile>
      <id>nexus-repo</id>
      <repositories>
        <repository>
          <id>maven-snapshots</id>
          <url>https://nexus.bcvsolutions.eu/repository/maven-snapshots/</url>
          <releases><enabled>false</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
        <repository>
          <id>maven-release</id>
          <url>https://nexus.bcvsolutions.eu/repository/maven-releases/</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </repository>
        <repository>
          <id>archetype</id>
          <url>https://nexus.bcvsolutions.eu/repository/maven-public-releases/</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>
  <activeProfiles>
    <activeProfile>nexus-repo</activeProfile>
  </activeProfiles>
</settings>

### Get product version

Get current product version in develop branch.

java -jar idm-tool.jar --get-version

### Change product version

Change product version for all product modules (FE + BE). Versions are changes only in develop branch (without commit) ⇒ changed versions in modules can be re

java -jar idm-tool.jar --set-version --develop-version 10.1.0-SNAPSHOT

### Revert product version

Changed versions by previous command in develop branch can be reverted if needed (before commit, usable after change product version only). Module descriptors (pom.xml, package.json) are reverted only.

java -jar idm-tool.jar --revert-version

### Build product

Available @since version 10.1.0.

Build product only under current develop version in develop branch.

java -jar idm-tool.jar --build

Maven ``install`` command is used under ``-Prelease`` profile, artifact will be installed into the local maven repository (⇒ usable as dependency for other module).

Build can be used before release for test purpose. Target artefact will be the same a can be deployed to tomcat for test if needed.

### Release module

Available @since version 10.1.0.

All commands above are available for standalone module too. The only difference is added parameter with module identifier:

java -jar idm-tool.jar --module idm-rec --release-publish --release-version 2.0.0 --develop-version 2.1.0-SNAPSHOT --username <git username> --password <git password or developer token>

Module identifier has to fit the folder name, where module sources are (by default). Use argument ``–repository-location`` otherwise.

The command above expects ``idm-tool.jar`` is placed in the same folder, where the module root (repository) folder is and has the same name as module identifier. In example above is used recertification module identifier.

Module can contains one frontend module and one or more backend modules (e.g. parent + api + impl). Module structure has respect module archetype generator (``Realization`` folders, frontend module with ``czechidm-`` prefix etc.).

Standalone modules are most probably in private repository, so credentials are needed.

### Build project

Available @since version 10.1.0.

Usable for build project with CzechIdM dependency ``>= 10.1.0`` or ``>= 9.7.14``.

Note for module developer: CzechIdM product dependency is / should be defined for project by ``czechidm-version`` maven property by conventions.

Build features: - Uses released product in defined version and install [released] project modules with backend and frontend is included. - Checks installation of duplicate modules in different version (e.g. scim module in 1.2.3 and 2.0.0 version placed in ``modules`` folder is not valid ⇒ scim module cannot be installed twice). - Installed module frontend and backend versions have to fit (backend ``pom.xml`` and frontend ``package.json`` version has to be the same).

[IdM Tool](#how-to-get-the-tool) can be placed into folder structure:

./
 ├── tool                           ⟵ [required] Here is idm-tool.jar (+lib or one-fat-jar).
 ├── product                        ⟵ [required] Here is product .war artefact (e.g. idm-9.7.14.war, idm-10.1.0.war or extracted folder idm-10.1.0). Can be downloaded from our nexus.
 ├── modules                        ⟵ [optional] Here are project modules and connectors. Third party module libraries (dependencies) could be here too, but is resolved automatically - see bellow.
 ├── frontend                       ⟵ [optional] Here can be custom frontend files - czechidm-app frontend module, localization can be overriden, e.t.c
 |   ├── config                     ⟵ frontend configuration (by profile, stage - see https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/frontend/czechidm-app/config/README.md)
 |   ├── czechidm-modules           ⟵ additional frontend modules (or overriden core module files, e.g. localization)
 ├── dist                           ⟵ [optional] Folder will be created automatically by tool usage - it will contain output artefacts ready for deploy (e.g. idm.war).
 ├── target                         ⟵ [optional] Folder will be created automatically by tool usage - used by tool internally for build.

After executing command in ``tool`` folder:

java -jar idm-tool.jar -p --build

will be deployable ``idm.war`` artefact (contains installed modules) ready in ``dist`` folder.

Usable additional tool argument:

#### Third party module dependencies

@since 10.7.0 (draft added @since 10.4.0, fully supported @since 10.7.0)

Third party module dependencies are included in target build automatically, when ``–resolve-dependencies`` argument is given:

• Product modules (``core``, ``acc`` etc.) are not defined as maven dependencies. These libraries are installed from product placed in product folder. Product dependency should be defined as provided in module dependencies.
• Modules or libraries added into ``modules`` folder are registered as project dependencies for build. All libraries have to be available in local or nexus repository ⇒ see settings.xml above to resolve private artefacts),
• libraries are included:
• 3th party libraries from module are included,
  • library scope is ``compile``,
  • library has to be available in maven repository (local or nexus),
  • library version can be defined by parent too,
  • if more versions of the same library is found in ``modules`` folder, then the build fails.

## Future development

- add module dependency descriptor with compatible product version list (e.g. scim module 1.2.3 is compatible / tested with product 9.7.14, 10.0.0, 10.1.0)