<- .:modules_scim | ^ .:start | Documentation ^ .:modules_comp | -> {{tag> IdMtool tool}} ====== Modules - Tool [tool] ====== Source documentation on [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/tool/README.md|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: - 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). - or can be installed globally and used by ``--node-home`` IdM tool argument. - 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 ``/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. If you want to use the tool for building the 9.7.14+ versions, the tool is not available in idm.war. But you can get the tool from the release of a newer version of CzechIdM (e.g. idm-app-10.2.0.war). Please use not only the idm-tool.jar, but also the whole **lib** folder included in the newer version of CzechIdM (WEB-INF/lib). Don't use the lib from some 9.7.x version, the tool wouldn't start, you would get the following error: Error: Could not find or load main class eu.bcvsolutions.idm.tool.ConsoleRunner When you try to release a module and you get the following exception, try to use the tool from version 10.4 and newer. Caused by: java.lang.NoClassDefFoundError: org/bouncycastle/jce/provider/BouncyCastleProvider at org.eclipse.jgit.lib.GpgSigner.(GpgSigner.java:58) at org.eclipse.jgit.api.CommitCommand.processOptions(CommitCommand.java:611) If you already are at a newer version, try adding the library `bcprov-jdk15on-1.61.jar` to the `lib` folder. ## 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: | Argument | Value | Description | Default | | --release | | Release product or module under ``--release-version`` argument. New development version will be set as ``--develop-version`` argument. | | | --publish | | Push prepared development, production and tags into origin repository. | | | --release-publish | | Release and publish shortcut as one command, taking the same arguments as ``--release`` command. | | | --build | | Build project or build product only (under current develop version in develop branch).
Maven 'install' command is used for product build, artifact will be installed into the local maven repository (=> usable as dependency for other module). Use ``-p`` argument to project build.| | | --get-version | | Get current product version (on the development branch or set '--development-branch' argument). | | | --set-version | | Set current product version (on the development branch - development branch can be changed only). | | | --revert-version | | Changed versions by release command can be reverted if needed (before commit, usable after change product version only). | | | -h,--help | | Print tool help. | | | -v,--version | | Print tool version. | | ### Additional arguments Additional / optional arguments can be combined with commands above: | Argument | Value | Description | Default | | --develop-branch | branchName | Branch with feature - working branch. | ``develop`` | | --develop-version | snapshot version | Usable with ``--release`` command. After release this version will be used in development branch. | Next minor snapshot semantic version will be used as default (=> current minor snapshot version + 1).
See ``--major``, ``--minor``, ``--patch``, ``--hotfix`` argument if different version is needed. | | --force | | Count of files changed by release command will not be checked. Limit of changed files is [30]. | | | --hotfix | | Next develop version will be hotfix, e.g. release 1.2.3 => develop 1.2.3.1-SNAPSHOT. | | | -m,--module | moduleId | Switch to module release / build. | | | --major | | Next develop version will be major, e.g. release 1.2.3 => develop 2.0.0-SNAPSHOT. | | | --master-branch | | Branch for releases - where feature has to be merged after release.
``none`` can be given - merge don't be executed (e.g. when some old hotfix branch is released).| ``master`` | | --maven-home | path | Maven home directory.
Maven directory should contain command ``/bin/mvn``.| ``MAVEN_HOME`` system property will be used as default. | | --minor | | Next develop version will be minor, e.g. release 1.2.3 => develop 1.3.0-SNAPSHOT. | | | -p,--project | | Switch to project build. | | --password | 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 , 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.).| | | --patch | | Next develop version will be patch, e.g. release 1.2.3 => develop 1.2.4-SNAPSHOT. | | | -r,--repository-location | path | Repository root folder - should contain all modules (/Realization/...). | Folder ``CzechIdMng`` in the same folder as ``idm-tool.jar`` will be used as default for product. Folder ```` in the same folder as ``idm-tool.jar`` will be used as default for module. | | --release-version | version | Usable with ``--release`` command. Release will be create under this version. | Stable semantic version will be used as default (=> current no snapshot version). | | --username | git username | Git username, if https repitory is used. When ssh repository is used, then passphrase for ssh key is needed only.| | ## Tool return codes | Value | Description | | 0 | everything successful | | 1 | unexpected exception | | 2 | wrong arguments given into command line | | 3 | command failed (build or release failed) | ## 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 , 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: ./logs/tool.log %d{dd-MM-yyyy HH:mm:ss.SSS} [%thread] %-5level %logger{36}.%M - %msg%n ./logs/tool_%d{dd-MM-yyyy}_%i.log 10MB 10 100MB ### 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 --password **Nexus credential has to be configured in maven** for deploy artefacts into our private ``maven-releases`` repository. Example of ``settings.xml``: nexus username password external.atlassian.jgitflow nexus * https://nexus.bcvsolutions.eu/repository/maven-all/ nexus-repo maven-snapshots https://nexus.bcvsolutions.eu/repository/maven-snapshots/ false true maven-release https://nexus.bcvsolutions.eu/repository/maven-releases/ true false archetype https://nexus.bcvsolutions.eu/repository/maven-public-releases/ true false nexus-repo ### 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 --password **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: | Argument | Value | Description | Default | | --- | :--- | :--- | :--- | | ``%%--%%node-home`` | path | Node home directory for build a project.
Global node instalation directory should contain executable node command.
For Windows /node/node.exe.
For Linux /node | Node and npm will be dowloaded and installed localy automaticaly into tool target folder (``/npm``) by default | | ``-c``, ``%%--%%clean`` | | Clean up dowloaded frontend libraries in node_modules. | | | ``-r``, ``%%--%%repository-location`` | path | Folder structure location. | ``../`` - when IdM tool is placed by example above. | | ``%%--%%resolve-dependencies`` | | Third party module dependencies will be resolved automatically (not resolved by default), when project is built. Dependencies will not be resolved and included in build, if feature is not enabled => all module dependencies has to be installed manually (prepared ~ copied in 'modules' folder). | | #### 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)