Related Documents
Document Properties
Kbid279D85
Last Modified16-Jun-2020
Added to KB12-Aug-2016
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • Gradle Tools
  • ICM 7.9
  • ICM 7.10
Related Product

Cookbook - Setup CI Infrastructure

1 Introduction

This cookbook describes in full detail how to create the required CI infrastructure. It provides detailed examples based on Jenkins as CI server and Subversion for version control. In addition, the cookbook also describes how to set up the required users and permissions.

This cookbook describes the setup and configuration of the base processes in a Continuous Integration Environment (CI).

Note

This cookbook requires Intershop Gradle tools version 2.11. Previous versions of this document show how to deal with:

This document replaces Cookbook - Setup CI Infrastructure (valid to Gradle Tools 2.7).

Since Intershop delivers Maven artifacts, it is necessary to reconfigure the existing infrastructure. For more detailed information please refer to the section Cookbook - Setup CI Infrastructure | Migration.

There are changes outside the Gradle tools that affect CI setup components. Therefore, a new version of the CI setup Gradle plugin was created. Please refer to the corresponding notes for this new version in the document.

The Intershop Gradle Tools and this document make no strong assumptions which artifact repository server, continuous integration server (CI server) or version control system (VCS) have to be used. This cookbook nonetheless provides examples for using Sonatype Nexus, Jenkins, and Subversion (SVN) or git.

Note

The recipes in this cookbook are made for a specific ICM version in combination with specific Intershop Gradle Tools.

Since the bootstrap of the Intershop Gradle Tools defines your project's directory structure and different versions of the Intershop Gradle Tools differ regarding their plugins, you have to ensure to use a valid combination of ICM and Intershop Gradle Tools.

For detailed version dependency information refer to Reference - CI Dependencies of Intershop Commerce Management.

For more detailed information on which plugins are available/deprecated for which Intershop Gradle Tools version refer to:

This is an overview of all necessary components:

overview-ci-setup-v2

Note

For build, demonstration and integration systems it is necessary to have a database. On such machines it is also necessary to have an installed Oracle client and a JDK.
Please refer to the System Requirements Sheet of your Intershop version for the recommended versions of the Oracle Database, Oracle Client and JDK installations.

The order of the recipes describes the way to set up a CI environment with all the necessary components. Some recipes can be executed in parallel or may be executed multiple times.

CI Setup Workflow

  1. Prepare the necessary server for the process:
    1. Artifact repository server (see recipe Configure Artifact Repository Server)
      This recipe describes the setup of an artifact repository based on Sonatype Nexus. 
    2. CI Server (see recipe Configure CI Server)
      This description is based on Jenkins.
    3. Version Control System
      All examples and descriptions are based on Apache Subversion. Intershop does not require any special configurations on this server.
  2. Generate Sources/Configuration (see recipe Create Sources from Intershop Templates)
    For the build processes of Intershop special source artifacts are necessary. Intershop provides the possibility to generate these sources from templates.
  3. Setup CI Process for Corporate Artifacts (see recipe Setup CI Build for Corporate Artifacts)
    This recipe describes how to build artifacts on the CI server only needed once per environment.
  4. Setup CI Process for Project Artifacts (see recipe Setup CI Build for Project Artifacts)
    This recipe describes how to build artifacts on the CI server needed separately for each project.
  5. Setup a developer environment (see recipe Setup Developer Environment in cookbook Gradle Developer Workflow)
    This document describes the setup steps on a developer machine. This can be done by the developer himself/herself, but it is also possible to provide VMs for the project developers.

1.1 Glossary


Phrase
Meaning
Version Control System (VCS)

Also known as source control, source code management systems (SCM), or revision control systems (RCS). VCS is a mechanism for keeping multiple versions of your files, so that when you modify a file you can still access the previous revisions.

Artifact Repository

Place, where build and package software components are located. Provide a common interface to a dependency management system.

Code AnalysisProcess to analyze source code to calculate metrics, find bugs, etc.
Continuous Delivery PipelineSometimes called Deployment Pipeline, describes the stages, which code artifacts runs through source to production system.
System ComponentA software package of different code artifacts and files, that have to be deployed together.
System Component SetIs a container for system components, that needs to be build and branched together.
AssemblyAn assembly references one or more system components residing in the same or a configured artifact repository in order to deploy or deliver them together.
Build ProcessCompiles and packages files and code artifacts from a source project to deployable artifacts.
Publish ProcessThe process which transfers the deployable artifacts to a configured artifact repository.
Assembly ProcessThis process combines several system components to an assembly.
Deployment ProcessThis process extracts files and code artifacts from an artifact repository and applies the configuration.
Project Gradle DistributionThis is a customized Gradle distribution with the preconfigured artifact repositories and Gradle plugins.
Gradle PluginA Gradle plugin packages up reusable pieces of build logic, which can be used across many different projects and builds.
Project Gradle PluginThis is a Gradle plugin which contains special corporate respectively project settings.
Corporate PluginThe term is used as a synonym for Project Gradle Plugin.
Gradle Extension ObjectJava Bean compliant class holding configurations for Gradle plugins.
Gradle WrapperThe Gradle Wrapper is the preferred way of starting a Gradle build. The wrapper is a batch script on Windows, and a shell script for other operating systems. When you start a Gradle build via the wrapper, Gradle will be automatically downloaded and used to run the build. See for more information The Gradle Wrapper in the Gradle documentation (2.11, 2.7, 2.3, 2.0, 1.8)
Intershop ClusterA number of hosts of different types serving an Intershop 7.
Cluster NodeOne separately deployable part of an Intershop cluster. A host can run multiple nodes of one Intershop cluster.

1.2 References

2 Migration

2.1 General

This section is a short overview about what has changed compared to the previous document. With this new version of the Intershop Gradle Tools, Intershop did some changes in the setup of the infrastructure.

The bootstrap package was replaced with a publicly available template.

The corporate plugin configuration was removed and the corporate plugin was replaced with the public available plugin (repoconfig-gradle-plugin). Therefore it is necessary to reconfigure the existing infrastructure. Follow the steps described in recipe Configure Artifact Repository Server, to provide the needed repositories.

As Intershop 7.6 and later contains Maven artifacts, it is necessary to reconfigure the existing infrastructure. Follow the steps described in recipe Configure Artifact Repository Server, to provide the needed repositories.

There is a new CI setup version which comes with changes for a project setup. Generate these files and merge them into existing projects that should run on Intershop Commerce Management 7.6 or later. To get the generated files follow the recipe Create Sources From Intershop Templates. Follow the special migration steps.

Finally, the CI build plan configuration needs to be adapted as well. Please see recipe Setup CI Build For Project Artifacts.

2.2 Gradle Tools 2.11 Updates

Please mind migration steps documented in the Public Release Notes - Gradle Tools - Version 2.11. Intershop recommends to use the latest version of the provided Gradle tools.

3 Recipe: Configure Artifact Repository Server

3.1 Problem

The artifact repository server stores artifacts. Artifacts are uploaded by the build server and downloaded by development environments, the build server and demo/production deployments. The build engineer resp. developer should set up and configure this server at the beginning of a project. So, which artifact repository servers are available and which configuration is required to run the Intershop build, assembly and deployment tools?

3.2 Solution

3.2.1 Supported Servers

The following artifact repository servers are available and work with the Intershop continuous delivery tools:

Example

See the discussion for an example using Sonatype Nexus.

3.2.2 Automated Setup and Configuration with Sonatype Nexus on CentOS

There are scripts for an automatic setup and configuration on GitHub.

Please verify the preconditions on the machine!

Note

The file ishrepo_repository.json must be adapted with the correct account ID, user name and password.

3.2.3 Prerequisites

  • Installed JDK 1.8
    The JAVA_HOME must be specified. 

3.2.4 Configuration Steps

Choose an artifact repository server and perform the following steps:

  1. Install a repository server according to the vendors documentation.
  2. A repository server can hold multiple repositories. Each repository is reachable via a URL of the form <repository base URI>/<repository ID>, e.g., http://nexus/repositories/releases.
    Create/configure the following repositories:

    IDUsageComment
    jcenterFor Maven artifacts available from Bintray JCenter. (Proxy for https://jcenter.bintray.com)These are artifact proxies to repositories in the internet, which cache all already retrieved artifacts. Please check the detailed configuration below.
    centralFor Maven artifacts available from Maven Central. (Proxy for https://secure.central.sonatype.com/maven2 )
    ishrepoFor binary artifacts provided by Intershop. (Proxy for https://repository.intershop.de/)
    Please have a look on your contract page in the Intershop KB area for more information. 
    distributionsRepository for Gradle distributions
    releasesFor corporate/ project releases
    snapshotsFor all artifacts from snapshot builds. This is the only repository that should allow overwriting of existing artifacts with the same name and version.
    componentsThis repository units releases, jcenter, central (if present) , ishreleases (if present) and ishrepo in one group.These is a repository group. Please check the detailed configuration below.

    ishreleases

    ishreleases is the predecessor to the proxy-based ishrepo and was used to host Intershop releases that were not delivered via Intershop's public repository. You do not need to create this repository when working only with Intershop releases that are delivered via public repository (e.g., Intershop Commerce Suite 7.9).


    For some repository server software it is recommended to store Maven and Ivy artifacts in different repositories. This is a suggestion for this special kind of configuration.

    IDUsageComment
    jcenterFor Maven artifacts available from Bintray JCenter. (Proxy for https://jcenter.bintray.com)This repository provides all artifacts also from Maven Central. Therefore a separate configuration for Maven Central is not necessary.
    distributionsRepository for Gradle distributionsThis is a Maven repository.
    ivy-local-releasesFor corporate/ project releases of Ivy artifacts.It replaces releases configuration in this special kind of configuration. 
    mvn-local-releasesFor corporate/ project releases of Maven artifacts.
    ivy-intershopFor Ivy binary artifacts provided by Intershop. This is a proxy repository for https://repository.intershop.de/ivy-releasesIt replaces ishrepo configuration in this special kind of configuration.
    mvn-intershopFor Maven binary artifacts provided by Intershop. This is a proxy repository for https://repository.intershop.de/mvn-releases 
    ivy-releasesThis repository units local Ivy releases (ivy-local-releases), Intershop Ivy releases (ivy-intershop) in one group.These are group or virtual repositories. It replaces components configuration in this special kind of configuration.
    mvn-releasesThis repository units local Mvn releases (mvn-local-releases), Intershop Maven (mvn-intershop) releases and JCenter in one group.
    ivy-local-snapshotsFor all artifacts from snapshot builds of Ivy artifacts. Please check the configuration of your repository for the handling of snapshots. It replaces snapshots configuration in this special kind of configuration.
    mvn-local-snapshotsFor all artifacts from snapshot builds of Maven artifacts.
  3. Configure permissions:
    1. All users should have read access to all repositories of the project.
    2. At least one user must be granted with permissions to publish new artifacts.
      In Maven the process of pushing artifacts to the repository is called deploy and release, while in the Gradle world it is called publish.

3.3 Discussion

3.3.1 Example Using Sonatype Nexus

Download and install Sonatype Nexus:

This is the overview of available repositories in an installation before any changes:

The following repositories are necessary for all build and deployment processes:

3.3.1.1 Proxy Repositories

NameIDRepository TypeRemote Storage LocationFormatRemarks
JCenterjcenterProxyhttps://jcenter.bintray.com/Maven2This repository provides all artifacts also from Maven Central. Therefore a separate configuration for Maven Central is not necessary.
IntershopishrepoProxyhttps://repository.intershop.de/releasesMaven2See Setup the Intershop Proxy below for details on how to get your contract-id and authorization information.
Intershop Ivyivy-intershopProxyhttps://repository.intershop.de/ivy-releasesIvy
Intershop Mavenmvn-intershopProxyhttps://repository.intershop.de/mvn-releasesMaven2

If you need additional remote repositories, all these repositories should be configured in one group. This makes it easier to configure this kind of repositories in the Gradle configuration, because all different repositories are usable via one URL. These repositories provide third party artifacts from public Maven repositories. The repository server needs internet access.

3.3.1.2 Set Up the Intershop Proxy Repository

The Intershop Proxy Repository in your repository makes the artifacts according to your contract with Intershop available. So you need to log on to the Intershop Knowledge Base and retrieve your credential tokens from your contract details. You need to check the Authentication (optional) box and provide your credential tokens (user and password).

Note

Login failed for repository.intershop.de

Although Intershop's public repository server shows a login screen when viewed in a web browser, those credentials do not entitle you to log into the Artifactory UI. A login attempt yields the following error message:

Username or Password Are Incorrect.

This is entirely intentional by design. Your credentials are suitable only for resolving artifacts using a proxy repository.

Note

Possible pitfall, when attempting to access files via this proxy repository. If the following message appears:
404 - Automatic routing filter rejected remote request for path https://repository.intershop.de/releases/com.intershop.public.source/a_responsive/<version>/zips/a_responsive-zip-src-<version>.zip from M2Repository(id=ishrepo)

Apply the following workaround.

Note

In case of Nexus 3 usage you need to define layout policy PERMISSIVE to avoid repository download issues.


Switch to the tab Routing and make sure Discovery is unchecked.

Note

In case the error message 404 - Automatic routing filter rejected remote request persists, please verify the configuration of the Nexus -> Views/Repositories -> Routing and adapt or delete the existing rules.

3.3.1.3 Hosted Repositories

The following repositories must be created and configured as hosted repositories:

NameIDRepository TypeRepository PolicyDeployment PolicyUsage
DistributionsdistributionshostedReleaseDisable Redeployfor project Gradle distribution
ReleasesreleaseshostedReleaseDisable Redeployfor corporate / project releases
SnapshotssnapshotshostedSnapshotAllow Redeployfor all artifacts from snapshot builds

3.3.1.4 Groups

The following repository forms a repository group of different repositories. There are hosted repositories as well as the Intershop proxy repository in there. Create it according to the following table:

NameIDRepository TypeFormatRepository Names
ComponentscomponentsgroupMaven2Releases, Intershop, JCenter

Once you created the new repository group, switch to the configuration tab an move the needed repository from Available Repositories to Ordered Group Repositories.

Note

The order of the assigned repositories is very important.

  1. JCenter
  2. Intershop 
  3. Releases

Components Configuration


Note

Older releases of Intershop were imported to a repository Intershop Releases. If you need this for migration projects or for other use cases, it is necessary to add this repository also to the group Components. Please add this repository to the end of the list.

3.3.1.5 User, Roles and Permissions

In the example we use the default admin user with the default password.

To create a deploy user:

  1. Create the role Project Upload with the following roles and privileges:
    Nexus Deployment Role, All Repositories (create, read, update, view), Artifact Download, Artifact Upload
  2. Create the user deploy and assign the new role.

3.3.1.6 Summary

The format of all hosted and proxy repositories is always Maven 2.

Note

The ID is case sensitive, because it is part of the URL.

It is necessary to configure these repositories in your artifact repository installation. After the configuration the following URLs are available.

The actual path nexus/content/repositories/central depends on the actual installation of your repository server.
NameURL
JCenterhttp://<Hostname:Port>/nexus/content/repositories/jcenter
Intershophttp://<Hostname:Port>/nexus/content/repositories/ishrepo
Distributionshttp://<Hostname:Port>/nexus/content/repositories/distributions
Releaseshttp://<Hostname:Port>/nexus/content/repositories/releases
Componentshttp://<Hostname:Port>/nexus/content/groups/components
Snapshotshttp://<Hostname:Port>/nexus/content/repositories/snapshots

The following repository is only needed for customers with older versions (7.5 and older). It is not needed for new customers.

Intershop Releaseshttp://<Hostname:Port>/nexus/content/repositories/ishreleases

The resulting repository overview should look like this:

4 Recipe: Configure CI Server

4.1 Problem

For the automatic execution of all build processes and the automatic installation of a new build in an integration environment it is required to have a special CI server.

How can an administrator set up this kind of server?

4.2 Solution

This is an example list of CI servers:

The listed CI servers always support remote processes, so there are different options for the execution on the server (the CI-host) or on a remote-agent (a connected client-host).

These are the extremes of all options:

  • Undistributed: All processes are running on one single machine.
  • Distributed: Component set builds, assembly builds, integration and the demo servers will be started on different bare metal machines or VMs.

Example

See the discussion for an example using Jenkins.

4.2.1 Prerequisites

Hardware requirements for server processes

  • Each active build of a component set process needs approx 1GB RAM and one CPU.
  • An assembly build needs approx two CPUs and approx 3GB RAM.
  • A single INTERSHOP instance requires in minimum two CPUs and approx 4GB RAM.
  • The space on the hard disc depends on the size of the custom component set.

Software requirements for server processes

  • The hosts (server and remote-agent) are part of the CI Environment and need to perform build- and deployment-tasks. They must meet minimum software requirements.
  • Oracle JDK must be installed for Jenkins and all other processes (See also requirements of the used Intershop version)
    It is possible to use the install script from GitHub: https://github.com/IntershopCommunicationsAG/oracle-jdk18-setup-script
  • Furthermore it is necessary to have an Oracle client installed (See also requirements of the used Intershop version).

Database

  • For each assembly build, integration and demo server, a database schema is necessary. The sizes of the table spaces depend on the amount of the init data of the custom extension.

4.2.2 Steps

Choose a CI server and perform the following steps:

Note

The CI server must support the type of your VCS. There are also corresponding plugins for special use cases of interacting with artifact repositories.

  1. Install a CI server according to the vendors documentation.
  2. Configure permissions to the servers in the CI Infrastructure, that are:
    1. VCS read credentials – server needs read privilege
    2. Artifact repository credentials – the user with permission to publish new artifacts (see Recipe: Configure Artifact Repository Server > Configure permissions)

(optional)

  1. For long running processes and also for demo and integration test machines it is recommended to use external agents. It is also possible to use ssh scripts and commands for the access to external machines if the usage of agents is limited.
  2. For a faster analysis of some automatic build steps it is helpful to have a web front end for your VCS. Most CI servers provide support for those kind of interfaces.
  3. Special tasks like assembly builds, the setup of the integration server and the demo servers should run on different bare metal machines or VMs.

4.2.3 Folder for Additional Build Directories

Gradle uses a directory for caches and it is also possible to store additional configuration files in this directory. This directory can be set with the environment variable GRADLE_USER_HOME or with an additional parameter (See Gradle Command Line). The build and assembly process provided by Intershop uses this directory for a special publishing configuration on the CI server. Therefore it is necessary to provide a directory where the CI server process can read and write files. The owner of this directory should be the CI server user.

Make that path available as environment variable BASE_GRADLE_USER_HOME to your CI builds.

4.3 Discussion

4.3.1 Example Using Jenkins

Download and Install Jenkins:

You may follow the instructions from https://wiki.jenkins-ci.org/display/JENKINS/Use+Jenkins, resp. https://wiki.jenkins-ci.org/display/JENKINS/Installing+Jenkins.

4.3.1.1 Plugin Recommendations

After the server is started, you should change the admin password. Furthermore it is necessary to activate the following set of plugins:

PluginDescription
All Changes Plugin

Shows all changes which influenced the builds of a project.

  • Shows changes by dependent builds (via fingerprinting)
  • Shows changes by sub projects added via a BuildStep from the parameterized-trigger-plugin
Build Environment Plugin*This plugin shows information about the environment of a build and gives the option to compare the environments of two builds.
Config File Provider Plugin*

This plugin allows the user to copy various similar configuration files to all build nodes. It also adds the ability to edit those files through the Jenkins UI.

Dashboard View

The CI server should provide the possibility for different views of the build plans.

This plugin contributes a new view implementation that provides a dashboard / portal-like view for Jenkins.

Email-ext plugin

The CI server should be able to send e-mails, when an error has occurred in a build.

This plugin extends Jenkins built in email notification functionality by giving you more control. It provides customization of 3 areas.

  • Triggers - Select the conditions that should cause an email notification to be sent.
  • Content - Specify the content of each triggered email's subject and body.  
  • Recipients - Specify who should receive an email when it is triggered.
Environment Injector Plugin*

For configurations it is necessary to specify some environment variables. These settings must be isolated for a specific job.

This plugin makes it possible to have an isolated environment for your jobs.

Environment File Plugin

This plugin enables the user to set environment variables via a file. The file's format must be the standard Java property file.
Git Parameter PluginThis plugin allows you to choose between Git tags or sha1 of your SCM repository so Git Plugin installed is required.

* The plugins marked with a star are mandatory for the following documentation.

4.3.1.2 Configuration Hints

It is necessary to add / change the following configuration settings:

  1. JDK
    1. Login with an admin account.
    2. Select Manage Jenkins.
    3. Select Global Tool Configuration.
    4. Adapt the JDK configuration.
  2. Source Code Management
    1. Subversion: Select the preferred version of the workspace. This should be 1.8!
    2. Git: It is necessary to create the configuration for user name and email.
  3. E-mail Notification and Extended E-mail Notification
    1. Set SMTP server:
    2. Add default recipients
  4. Add global password configuration for deployment user (see Recipe: Configure Artifact Repository Server > User, Roles and Permissions)

    1. Go to Manage Jenkins | Configure Systems.
    2. Select Global Passwords | Add.
    3. Add password.

      NameREPO_USER_NAMEREPO_USER_PASSWD
      Passworde.g., admine.g., admin123
  5. If you use Subversion and you want use the SCM version plugin, it is necessary to specify an additional global password configuration:
    1. Go to Manage Jenkins | Configure Systems.
    2. Select Global Passwords | Add.
    3. Add password.

      NameSCM_USERNAMESCM_PASSWORD
      Passworde.g., usernamee.g., password

5 Recipe: Create Sources From Intershop Templates

5.1 Problem

For a project setup or development environment setup it is necessary to have scripts, configuration files and also some basic source artifacts. The sources for the following artifacts must be generated from provided templates.

How can a developer or administrator create the source artifacts from the provided Intershop template?

5.2 Solution

5.2.1 Prerequisites

Meet the minimum system requirements.

  • Windows or Linux machine with:
    • Installed Oracle JDK (use a version specified in the system requirements of your Intershop version)
    • Access to https://services.gradle.org/
    • Access to the VCS (this documentation uses Subversion or git as a version control system)

See Recipe: Configure Artifact Repository Server.

5.2.2 Steps

  1. Check your active Java version:

    >java -version
    java version "1.8.0_77"
    Java(TM) SE Runtime Environment (build 1.8.0_77-b03)
    Java HotSpot(TM) 64-Bit Server VM (build 25.77-b03, mixed mode)

    It is possible to download older version of the Oracle JDK from the Oracle website. There are scripts for an automatic setup on GitHub. If you want use this JDK installation also for the development with Intershop Commerce Management, it is necessary to add the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from the Oracle website as well.

  2. Download the latest version of the bootstrap package for the CI setup via your proxy.

    Fetch CI Bootstrap Package on Linux
     $ wget https://github.com/IntershopCommunicationsAG/intershop-cisetup-template/archive/master.zip
    Fetch CI Bootstrap Package on Windows
    (new-object System.Net.WebClient).DownloadFile('https://github.com/IntershopCommunicationsAG/intershop-cisetup-template/archive/master.zip', '<target dir>\master.zip')

    It is also possible to create an own clone of the Git repository, see https://github.com/IntershopCommunicationsAG/intershop-cisetup-template.git.

  3. Unzip the the contents or clone the Git repository to a directory of your choice, eg. intershop-cisetup-template.

    Example for unzipping (Linux)
    unzip master.zip -d <target directory>
    cd <target directory>/intershop-cisetup-template-master
    mv * .. 
    cd .. 
    rm -rf intershop-cisetup-template-master	

    or

    git clone https://github.com/IntershopCommunicationsAG/intershop-cisetup-template.git <target directory>
  4. Open the build.gradle file of the Intershop CI-setup template in an editor. This file configures the generation of artifacts.
    It contains lines marked with //TODO. Go through these lines and provide the necessary information.
    Also see the discussion for required and optional adjustments of the build.gradle.
  5. Run the following command inside the intershop-ci-setup directory to generate all source artifacts:

    Note

    It is important to specify the JAVA_HOME before you start the command.

    Run generation of all sources (Windows)
    gradlew intershopCISetupAll
    Run generation of all sources (Linux)
    ./gradlew intershopCISetupAll

    See the discussion for a directory tree of the generated sources. You may also generate (or regenerate) only some of the source artifacts by running dedicated Gradle tasks, see discussion.

  6. Prepare the build of the Cartridge with Oracle JDBC driver libraries. It is possible to download these artifacts from the Oracle download page or from Oracle Maven repository.
    1. To download from the Oracle Site add .jar files to the prepared Oracle JDBC Driver component set:
      1. Download the files ojdbc7.jar, ucp.jar and ons.jar from the Oracle web by selecting the required version (http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html) and agree to the license conditions.
      2. Copy files to <setupDirectory>/projects/oracleDriver/3rd_oracle/build//oracleLibs/jars.
    2. To download from Oracle Maven repository with the provided build script, register your OTN account for the usage of Oracle's Maven repository (https://www.oracle.com/webapps/maven/register/license.html).

      Info

      During the build of the component, the driver libraries are downloaded from Oracle's Maven repository. The files are cached in the build directory.

  7. Add all generated sources to your VCS.
    It is recommended to add them in a way that the different source artifacts can be branched independently. How to do this depends on the VCS.
    Also add the intershop-ci-setup directory to your VCS for later regeneration of sources.

See discussion for example commands if you use SVN as VCS.

5.3 Discussion

5.3.1 Required Adjustments of build.gradle

  1. Corporate name (corporateName): Specify a name that identifies your company/department. If you use the same CI environment for multiple projects, these can stay the same across projects.
  2. Project name (projectName): Specify names that identify your project.
  3. Output directory: Specify a directory to generate sources into in the property setupDirectory.
  4. Repository base URL: Specify the repository base URL of your artifact repository server in property repoBaseURL.

5.3.2 Optional Adjustments of build.gradle

5.3.2.1 Output Directories

By default all sources are generated into subdirectories of the setupDirectory. You may also configure independent output directories for different types of source artifacts. See the directories section of the build.gradle file and the following examples.

Example for adjusting output directories (Linux)
plugins {
    id 'com.intershop.gradle.cisetup' version '2.1.0'
}

IntershopCISetup {
	directories {
		setupDirectory = '/home/developer/intershop-ci/sources'
		devOpsDir = "${setupDirectory}/devops"
	
		projectsDir = "${setupDirectory}/projects"
	}
}
Example for adjusting output directories (Windows)
plugins {
    id 'com.intershop.gradle.cisetup' version '2.1.0'
}
IntershopCISetup {
	directories {
		setupDirectory = 'C:/Users/developer/intershop-ci/sources'
		devOpsDir = "${setupDirectory}/devops"
	
		projectsDir = "${setupDirectory}/projects"
	}
}

5.3.2.2 Repositories

The build.gradle file comes with default IDs for all important repositories. For changes see the repository section of the build.gradle file.

5.3.2.3 Corporate Distribution

The repository section allows to adjust the version of your corporate distribution in property distributionVersion.

It also allows to configure a different URL. So your corporate distribution can be downloaded by the Gradle wrapper in property distributionURL. This way you can place your corporate distribution on any web server you want.

5.3.2.4 Versions

The versions section configures which versions of the deployment launcher (special component of the Intershop Gradle tools) and third party components should be used. Please check always support sites of Intershop for updates. 

5.3.2.5 Project settings

The section intershopProject defines only the name of the project. 

5.3.3 Overview of Tasks and Output

Running gradlew tasks shows all available tasks:

:tasks
 
------------------------------------------------------------
All tasks runnable from root project
------------------------------------------------------------

Build Setup tasks
-----------------
...

Help tasks
----------
...

Intershop CI Source tasks
-------------------------
createCorporateDistribution - Creates a structure of a corporate distribution package project.
createDeploymentConfig - Creates a structure of a deployment configuration.
createOracleComponentSet - Creates a special component set for publishing Oracle JDBC drivers
createProject - Creates a structure of a project configuration.
intershopCISetupAll - Create all necessary source artefacts

The resulting sources (assuming default output directories) look like this:

Generated Sources
sources
|-- devops
|   |-- ci_server  		---------------------------------------- 	ci server configuration
|   |   `-- host_configs
|   |       `-- ciserverhost
|   |           `-- environment.properties
|   |-- deployments 	 
|   |   `-- corporateshop	------------------------------------	Project for deploying the corporateshop, including a preconfigured settings.gradle 
|   |       |-- gradle
|   |       |   `-- wrapper
|   |       |       |-- gradle-wrapper.jar
|   |       |       `-- gradle-wrapper.properties
|   |       |-- gradlew
|   |       |-- gradlew.bat
|   |       `-- settings.gradle	
|   `-- gradle
|       `-- corporate-distribution	----------------------------	corporate gradle distribution package project
|           |-- build.gradle
|           |-- gradle
|           |   `-- wrapper
|           |       |-- gradle-wrapper.jar
|           |       `-- gradle-wrapper.properties
|           |-- gradle.properties
|           |-- gradlew
|           |-- gradlew.bat
|           `-- src
|               `-- init.d
|                   `-- intershop-init.gradle
`-- projects
    |-- corporateshop	----------------------------------------	gradle multiproject, entry point of all component projects, related to the corporate shop	
    |   |-- gradle
    |   |   `-- wrapper
    |   |       |-- gradle-wrapper.jar
    |   |       `-- gradle-wrapper.properties
    |   |-- gradle_environment.bat
    |   `-- gradle_environment.sh
    `-- oracleDriver	----------------------------------------	special component set for publishing Oracle JDBC drivers			
        `-- 3rd_oracle
            |-- build
            |   `-- oracleLibs
            |       `-- jars
            |-- build.gradle
            |-- gradle
            |   `-- wrapper
            |       |-- gradle-wrapper.jar
            |       `-- gradle-wrapper.properties
            |-- gradlew
            |-- gradlew.bat
            |-- init.gradle
            |-- publish.bat
            |-- publish.sh
            `-- settings.gradle

The following table shows which task generates which source artifacts. Multiple projects may share the same CI environment. Some source artifacts are global to the CI environment (corporate artifacts), others are project specific (project artifacts).

LineGenerated byProject or corporate artifactUsed inDescription
03-15createDeploymentConfigproject 

Configuration template for running a deployment

  • Outside of the CI and development environment, e.g., for demo, integration tests and production ('deployments'-folder)
  • On the CI server during the build process ('ci_server'-folder)
16-28createCorporateDistributioncorporateSetup CI Build For Corporate ArtifactsSee Concept - Gradle Build Tools
30-36createProjectproject

Setup CI Build For Project Artifacts

Cookbook - Gradle Developer Workflow

See:

37-52createOracleComponentSetcorporateSetup CI Build For Corporate ArtifactsFor legal reasons Intershop cannot deliver the Oracle JDBC drivers.
This component set contains scripts to package Oracle JDBC drivers as component.
Once published to the corporate repository, the Oracle JDBC drivers can be handled like any other component.

5.3.4 Additional Code Changes on Corporate Distribution

The build script of the corporate distribution is preconfigured with a special Intershop Release plugin, see https://github.com/IntershopCommunicationsAG/gradle-release-plugins. This project provides different publishing plugins. The templates contain an inactive Artifactory publishing configuration and an active simple publish configuration.

If you want use the Artifactory publishing configuration, activate this plugin and deactivate the other plugin.

5.3.5 Additional Code Changes for Old Intershop Versioning Plugin

If you use Intershops new Version Recommender Gradle Plugin (https://github.com/IntershopCommunicationsAG/version-recommender-gradle-plugin), it is not necessary to do any additional code changes.
Please check your build gradle file for apply plugin: 'com.intershop.gradle.versionrecommender'. If this plugin is applied, the sources for the distribution can be used as they are.

The old Intershop versioning plugin must be applied to all projects. Therefore it is located in the init Grade file of the distribution.

Please adapt the file '<sources>/devops/gradle/corporate-distribution/src/init.d/intershop-init.gradle' as follows:

initscript {
+	// only used for secured repositories
+	String repoUser = System.properties['repoUser'] ?: System.getenv('REPO_USER')
+	String repoUserPasswd = System.properties['repoUserPasswd'] ?: System.getenv('REPO_USER_PASSWD')
+
repositories {
+       // add repository configuration for proxy configuration of Intershop public repository
+ 		ivy {
+			url '<URL of repository with Intershop artifacts (ID: ishrepo)>'
+			layout('pattern') {
+				ivy '[organisation]/[module]/[revision]/[type]s/ivy-[revision].xml'
+				artifact '[organisation]/[module]/[revision]/[ext]s/[artifact]-[type](-[classifier])-[revision].[ext]'
+			}
+			// only used for secured repositories
+			if(repoUser && repoUserPasswd) {
+				credentials {
+					username repoUser
+					password repoUserPasswd
+				}
+			}
+		}
	}
	dependencies {
+		classpath 'com.intershop.build.gradle:versioning:2.11.6'
 
 
	corporateName = '<name from configuration>'
}
+ // apply old versioning plugin to all sub projects
+ allprojects {
+    // Versioning plugin
+    project.plugins.apply com.intershop.build.gradle.plugins.VersioningPlugin
+ }

 

5.3.6 Examples If Using SVN As VCS

If you use SVN as your VCS you may use the following commands to add your intershop-ci-setup directory and the generated sources to it.

This example assumes that:

  • You work on Linux (Windows commands are similar).
  • The intershop-cisetup-template directory is located at /home/developer/intershop-ci/intershop-cisetup-template.
  • Your SVN root is http://ciserver/svn/intershop.
  • Your output directory (property setupDirectory in intershop-cisetup-template /build.gradle) is /home/developer/intershop-ci/sources and you use the default output directories structure.

Perform the following steps:

  1. Create the following file for a list of common SVN ignores (assumed location is /home/developer/ignore.txt):

    /home/developer/ignore.txt
    build
    .gradle
    bin
    target
  2. Add your intershop-cisetup-template directory by executing:

    SVN command
    cd /home/developer/intershop-ci
    
    # Create SVN structure
    svn mkdir --parents http://ciserver/svn/intershop/devops/intershop-cisetup-template -m "create path for template project" 
    svn mkdir --parents http://ciserver/svn/intershop/devops/intershop-cisetup-template/branches -m "create branches folder"
    svn mkdir --parents http://ciserver/svn/intershop/devops/intershop-cisetup-template/tags -m "create tags folder"
     
    # Import sources to SVN
    svn import intershop-cisetup-template http://ciserver/svn/intershop/devops/intershop-cisetup-template/trunk -m "add intershop-ci-setup configuration"
     
    # Make your local folder a working copy
    svn co --force http://ciserver/svn/intershop/devops/intershop-cisetup-template/trunk intershop-cisetup-template
    svn revert -R intershop-ci-setup
     
    # Add ignore properties (see ignore.txt) and executable bit for gradle
    svn propset svn:ignore -F /home/developer/ignore.txt intershop-ci-setup-template
    svn propset svn:executable on intershop-ci-setup-template/gradlew*
    svn commit intershop-cisetup-template -m "add svn ignore and executable bit"
  3. Add your corporate distribution by executing:

    SVN Commands
    cd /home/developer/intershop-ci/sources/devops/gradle
    
    # Create SVN structure
    svn mkdir --parents http://ciserver/svn/intershop/devops/gradle -m "create path for Gradle projects"
    svn mkdir --parents http://ciserver/svn/intershop/devops/gradle/corporate-distribution/branches -m "create svn structure"
    svn mkdir --parents http://ciserver/svn/intershop/devops/gradle/corporate-distribution/tags -m "create svn structure"
    
    # Import sources to SVN
    svn import corporate-distribution http://ciserver/svn/intershop/devops/gradle/corporate-distribution/trunk -m "add corporate distribution"
     
    # Make your local folder a working copy
    svn co --force http://ciserver/svn/intershop/devops/gradle/corporate-distribution/trunk corporate-distribution
    svn revert -R corporate-distribution
      
    # Add ignore properties (see ignore.txt) 
    svn propset svn:ignore -F /home/developer/ignore.txt corporate-distribution
    svn propset svn:executable on corporate-distribution/gradlew*
    svn commit corporate-distribution -m "add svn ignore and executable bit"
  4. Add the project artifacts by executing (assuming project name is 'corp_project'):

    SVN Commands
    cd /home/developer/intershop-ci/sources/corporateshop
    
    # Create SVN structure
    svn mkdir --parents http://ciserver/svn/intershop/projects/corporateshop -m "create path for project"
    svn mkdir --parents http://ciserver/svn/intershop/projects/corporateshop/branches -m "create svn structure"
    svn mkdir --parents http://ciserver/svn/intershop/projects/corporateshop/tags -m "create svn structure"
    
    # Import sources to SVN
    svn import corporateshop http://ciserver/svn/intershop/projects/corporateshop/trunk -m "add project"
    
    # Make your local folder a working copy
    svn co --force http://ciserver/svn/intershop/projects/corporateshop/trunk corporateshop
    svn revert -R corporateshop
    
    # Add ignore properties (see ignore.txt) 
    svn propset svn:ignore -F /home/developer/ignore.txt corporateshop
    svn propset svn:executable on corporateshop/gradlew*
    svn commit corporateshop -m "add svn ignore and executable bit"
    
  5. Add the Oracle JDBC Drivers Component Set by executing:

    SVN Commands
    cd /home/developer/intershop-ci/sources/projects/oracleDriver
    
    # Create SVN structure
    svn mkdir --parents http://ciserver/svn/intershop/projects/3rd_oracle -m "create path for project oracle driver"
    svn mkdir --parents http://ciserver/svn/intershop/projects/3rd_oracle/branches -m "create svn structure"
    svn mkdir --parents http://ciserver/svn/intershop/projects/3rd_oracle/tags -m "create svn structure"
    
    # Import sources to SVN
    svn import 3rd_oracle http://ciserver/svn/intershop/projects/p_oracle/trunk -m "add Oracle JDBC driver project"
    
    # Make your local folder a working copy
    svn co --force http://ciserver/svn/intershop/projects/3rd_oracle/trunk .
    svn revert -R .
    
    # Add ignore properties (see ignore.txt)
    svn propset svn:ignore -F /home/developer/ignore.txt .
    svn propset svn:executable on gradlew*
    svn commit . -m "add svn ignore and executable bit"
  6. Add demo deployment scripts (assuming project Name is corporateshop) by executing:

    SVN Commands
    cd /home/developer/intershop-ci/sources/devops/deployments
    
    # Create SVN structure
    svn mkdir --parents http://ciserver/svn/intershop/devops/deployments -m "create path for deployment projects"
    svn mkdir --parents http://ciserver/svn/intershop/devops/deployments/corporateshop/branches -m "create svn structure"
    svn mkdir --parents http://ciserver/svn/intershop/devops/deployments/corporateshop/tags -m "create svn structure"
     
    # Import sources to SVN
    svn import corp_project http://ciserver/svn/intershop/devops/deployments/corporateshop/trunk -m "add deployment configuration"
     
    # Make your local folder a working copy
    svn co --force http://ciserver/svn/intershop/devops/deployments/corporateshop/trunk corporateshop
    svn revert -R corporateshop
    
    # Add ignore properties (see ignore.txt)
    svn propset svn:ignore -F /home/developer/ignore.txt corporateshop
    svn propset svn:executable on corporateshop/gradlew*
    svn commit corporateshop-m "add svn ignore and executable bit"
  7. Add CI server host configuration by executing:

    SVN Commands
    cd /home/developer/intershop-ci/sources/devops/ci_server
    
    # Create SVN structure
    svn mkdir --parents http://ciserver/svn/intershop/devops/ci_server/host_configs -m "create path for ci_server host_configs files and directories" 
    svn mkdir --parents http://ciserver/svn/intershop/devops/ci_server/host_configs/branches -m "create svn structure"
    svn mkdir --parents http://ciserver/svn/intershop/devops/ci_server/host_configs/tags -m "create svn structure"
    
    # Import sources to SVN
    svn import host_configs http://ciserver/svn/intershop/devops/ci_server/host_configs/trunk -m "add host specific configuration for ci assembly process"
    
    # Make your local folder a working copy
    svn co --force http://ciserver/svn/intershop/devops/ci_server/host_configs/trunk host_configs
    svn revert -R host_configs
    
    # Add ignore properties (see ignore.txt)
    svn propset svn:ignore -F /home/developer/ignore.txt host_configs
    svn commit host_configs -m "add svn ignore"

5.3.7 Examples if Using Git as VCS

If you use Git as your VCS you may use the following commands to add your intershop-ci-setup directory and the generated sources to it.

This example assumes that:

  • You work on Linux (Windows commands are similar).
  • The intershop-cisetup-template directory is located at /home/developer/intershop-ci/intershop-cisetup-template.
  • Your Git server is located on git@gitserver:user.
  • Your output directory (property setupDirectory in intershop-cisetup-template /build.gradle) is /home/developer/intershop-ci/sources and you use the default output directories structure.

The following Git-Repositories are necessary:

  • corporate-distribution
  • 3rd_oracle
  • deployment-corporateshop
  • ci_server-host_configs
  • project name, e.g., 'corporateshop'

Perform the following steps:

  1. Create the following file for a list of common ignores (assumed location is /home/developer/.gitignore):

    /home/developer/.gitignore
    # IntelliJ project files
    .idea
    *.iml
    out
    gen
    *.bak
    *.log
    
    # Eclipse project files
    **/bin/
    **/.settings/
    **/.classpath
    **/.project
    
    # editor backup files
    **~
    
    # Gradle Files
    **/build/
    **/.gradle
    
    # Intershop build directories
    **/target/
    # Ignore Gradle GUI config
    gradle-app.setting
    
    # Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
    !gradle-wrapper.jar
  2. Add your intershop-cisetup-template directory by executing:

    Git command
    cd /home/developer/intershop-ci/intershop-cisetup-template
    cp /home/developer/.gitignore .
     
    git init
    
    git remote add origin git@gitserver:user/intershop-cisetup-template.git
    # or
    git remote set-url origin git@gitserver:user/intershop-cisetup-template.git
     
    git add .
    git update-index --chmod=+x gradlew
    git update-index --chmod=+x *.sh
    
    git commit
    git push -u origin master
  3. Add your corporate distribution by executing:

    Git Commands
    cd /home/developer/intershop-ci/sources/devops/gradle/corporate-distribution
    cp /home/developer/.gitignore .
     
    git init
    git remote add origin git@gitserver:user/corporate-distribution.git
    git add .
    git commit
    git push -u origin master
  4. Add the project artifacts by executing (assuming project name is corporateshop):

    Git Commands
    cd /home/developer/intershop-ci/sources/projects/corporateshop
    cp /home/developer/.gitignore .
     
    git init
    git remote add origin git@gitserver:user/corporateshop.git
    git add .
    git update-index --chmod=+x gradlew
    git update-index --chmod=+x *.sh
    git commit
    git push -u origin master
  5. Add the Oracle JDBC Drivers Component Set by executing:

    Git Commands
    cd /home/developer/intershop-ci/sources/projects/oracleDriver/3rd_oracle
    cp /home/developer/.gitignore .
    
    git init
    git remote add origin git@gitserver:user/3rd_oracle.git
    git add .
    git update-index --chmod=+x gradlew
    git update-index --chmod=+x *.sh
    git commit
    git push -u origin master
  6. Add demo deployment scripts (assuming projectName is corporateshop) by executing:

    Git Commands
    cd /home/developer/intershop-ci/sources/devops/deployments/corporateshop
    cp /home/developer/.gitignore .
     
    git init
    git remote add origin git@gitserver:user/deployment-corporateshop.git
    git add .
    git update-index --chmod=+x gradlew
    git update-index --chmod=+x *.sh
    git commit
    git push -u origin master
  7. Add CI server host configuration by executing:

    Git Commands
    cd /home/developer/intershop-ci/sources/devops/ci_server/host_configs
    cp /home/developer/.gitignore .
    git init
    git remote add origin git@gitserver:user/ci_server-host_configs.git
    git add .
    git update-index --chmod=+x gradlew
    git update-index --chmod=+x *.sh
    git commit
    git push -u origin master

6 Recipe: Set Up Project Based on the Responsive Starter Store

6.1 Problem

Starting with Intershop Commerce Management Suite 7.6 (B2C, B2X) the delivered assemblies no longer include cartridges that define the storefront applications and do not provide the storefront functionality, meaning the view layer with the content model. Instead, Intershop provides the Responsive Starter Store. This includes the storefront parts as a source project that can be used as a blue print to set up customer projects.

After creating the project source structure from the Intershop templates it is necessary to fill the project with the specific artifacts, especially those that make up the storefront. The Responsive Starter Store is a good starting point, that provides the functionality, code artifacts and demo content of a standard responsive storefront.

How can a build engineer or developer set up a project based on the Responsive Starter Store?

6.2 Solution

6.2.1 Prerequisites

Note

License

Please make sure to comply with Glyphicons Free license terms (CC BY 3.0) or get pro license.

See the following recipes:

6.2.2 Steps

Note

The following listings contain diff-style where "<DIFF>" leads the listing title.

This describes changes on files where "-String=original line of code;" represents the original line of code that should be replaced with "+String=replaced line of code'".

  1. Download the latest version of the Responsive Starter Store (Version 3.+).
    If you want use the latest version of Gradle Tools with Responsive Starter Store Version 1.+ or 2.+, please use the migration steps from Public Release Notes - Gradle Tools - Version 2.11.
  2. Copy the contents of the Responsive Starter Store multi-project into your project folder, e.g., corporateshop.
  3. Set up the initialization cartridges.
  4. Commit changes to your VCS.

See the following sections for details.

6.2.3 Download the Latest Version of the Responsive Starter Store

Note

Newer versions of the responsive starter store

Find the Responsive Starter Store version and download links for a corresponding Intershop Commerce Management version in the Reference - CI Dependencies of Intershop Commerce Management.

Responsive Starter Store version 3.1.4 for Intershop Commerce Management 7.8:

  • Download the Responsive Starter Store multi project (a_responsive).

    Responsive Starter Store - Component Set
    http://<your-reposerver:port>/nexus/content/repositories/ishrepo/com.intershop.public.source/a_responsive/3.1.4/zips/a_responsive-zip-src-3.1.4.zip

    or from Intershop public repository

    https://repository.intershop.de/releases/com.intershop.public.source/a_responsive/3.1.4/zips/a_responsive-zip-src-3.1.4.zip

Responsive Starter Store version 4.0.0 for Intershop Commerce Management 7.9

  • Download the Responsive Starter Store multi project (a_responsive).

    Responsive Starter Store - Component Set
    http://<your-reposerver:port>/nexus/content/repositories/ishrepo/com.intershop.public.source/a_responsive/4.0.0/zips/a_responsive-zip-src-4.0.0.zip

    or from Intershop public repository

    https://repository.intershop.de/releases/com.intershop.public.source/a_responsive/4.0.0/zips/a_responsive-zip-src-4.0.0.zip

6.2.4 Copy the Contents of the Responsive Starter Store Source Package into the Projects Folder

Content Overview of the Responsive Starter Store multi project:

a_responsive
|-- app_sf_responsive
|-- app_sf_responsive_b2b
|-- app_sf_responsive_b2b_test
|-- app_sf_responsive_b2c
|-- app_sf_responsive_cm
|-- app_sf_responsive_costcenter
|-- app_sf_responsive_smb
|-- app_sf_responsive_test
|-- as_responsive
|-- as_responsive_b2b
|-- demo_responsive
|-- demo_responsive_b2b
|-- demo_responsive_catalog
|-- demo_responsive_content
|-- demo_responsive_ocst
|-- demo_responsive_search
|-- dev_storefront
|-- gradle
|-- inspired-b2c
|-- inspired-b2x
|-- microservices
|-- .ivyIcm-b2c.version
|-- .ivyIcm-b2x.version
|-- build.gradle
|-- gradle.properties
|-- gradlew
|-- gradlew.bat
`-- settings.gradle
responsive starter store
base storefront cartridge
additional B2B functionality cartridge
automatic tests for B2B functionality
base storefront cartridge
base storefront cartridge
additional B2B functionality cartridge
base storefront cartridge
automatic tests for base functionality
base storefront cartridge
additional B2B functionality cartridge
demo content cartridge
additional B2B demo content cartridge
demo content cartridge
demo content cartridge
demo content cartridge
demo content cartridge
development cartridge
 
B2C demo assembly
B2X demo assembly
micro-services scheduling and recurring orders 
version file for ICM b2c (Available with ICM 7.9)
version file for ICM b2x (Available with ICM 7.9)

Place the content into the working copy of your project folder (that was generated via CI bootstrap before). Rest assured that there are no conflicting files in your projects folder that otherwise need to be overwritten.

Long path names on Windows

On Windows certain tools have trouble dealing with path names longer than 255 characters. When in doubt, please use 7-Zip 15.12 or newer to uncompress the source packages.

6.2.5 Adapt the Build Configuration of the Responsive Starter Store Source Package

After copying the contents of the a_responsive Gradle multi-project set into your project folder some files need to be changed to fit your projects configuration.

  • Replace a_responsive with your projects name in the following files

    <DIFF> settings.gradle
    // define root project name
    -rootProject.name = 'a_responsive'
    +rootProject.name = 'corporateshop'
  • Replace the com.intershop.responsive group with your projects group in the following file:

    <DIFF> build.gradle
    description 'Components Responsive Starter Store Applications'
    -group = 'com.intershop.responsive'
    +group = 'com.company.corporateshop'
    
    subprojects {
    -   group = 'com.intershop.responsive'
    +   group = 'com.company.corporateshop'
  • Adapt the release configuration of the project. 

    <DIFF> build.gradle
    // ci configuration
    -	/**
    -	 * Intershop release configuration
    -	 * requires
    -	 *  - Sonatype Nexus Pro with a configured staging configuration
    -	 *  - Atlassian Jira
    -	 *  and additional environment variables.
    -	 * Furthermore an applied SCMVersion plugin is mandatory.
    -	 * See https://github.com/IntershopCommunicationsAG/gradle-release-plugins.
    -	 **/
    -	apply plugin: 'com.intershop.gradle.nexuspublish-configuration'
    -   apply plugin: 'com.intershop.gradle.artifactorypublish-configuration'
    /**
     * Simple Release configuration
     * requires only a Maven compatible repository and
     * additional environment variables.
     * See also https://github.com/IntershopCommunicationsAG/gradle-release-plugins. 
     **/
    -	// apply plugin: 'com.intershop.gradle.simplepublish-configuration'
    +	apply plugin: 'com.intershop.gradle.simplepublish-configuration'
    -	/**
    -	 * This plugin will create a source package of the build.
    -	 * It is possible to use this e.g. for the creation of an ESCROW package.
    -	 * _This plugin is optional._
    -	 * See https://github.com/IntershopCommunicationsAG/gradle-release-plugins
    -	 **/
    -	apply plugin: 'com.intershop.gradle.escrow-plugin'
    -	escrow {
    -    	sourceGroup = 'com.intershop.public.source'
    -	    exclude '*/target'
    -	    exclude '**/gradle/wrapper/gradle-wrapper.properties'
    -	}
     
    description 'Components Responsive Starter Store Applications'
    group = 'com.intershop.responsive'
    assert System.properties['java.version'].startsWith('1.8')
    
    
    - artifactory {
    -     publish {
    -         // for ivy publications
    -         repository {
    -             maven = false
    -         }
    -         // list of publication names
    -         defaults {
    -             publications('ivy', 'ivyEscrow')
    -         }
    -     }
    - }
     
  •  Replace the version number with a version number fitting to your projects.
    1. Intershop Commerce Management 7.8
      Change the Intershop Commerce Management version in the following file:

      <DIFF> gradle.properties
      # dependency versions
      -version.com.intershop.assembly.commerce_management_b2x = 7.X.0.0
      +version.com.intershop.assembly.commerce_management_b2x = 7.X.X.X
      -version.com.intershop.assembly.commerce_management_b2c = 7.X.X.X

      If you need only Intershop Commerce Management B2C use b2c instead of b2x:

      <DIFF> gradle.properties
      # dependency versions
      -version.com.intershop.assembly.commerce_management_b2x = 7.X.0.0
      -version.com.intershop.assembly.commerce_management_b2c = 7.X.X.X
      +version.com.intershop.assembly.commerce_management_b2c = 7.X.X.X
    2. Intershop Commerce Management 7.9
      With this version we introduced a better plugin for the version handling. See https://github.com/IntershopCommunicationsAG/versionrecommender-gradle-plugin
      Therefore the files .ivyIcm-b2c.version or .ivyIcm-b2x.version must be changed. Replace the version in these files with your own.
  • Remove not needed sub projects.
    (warning) Do not skip this step! You really need to delete these folders, otherwise you will run into exceptions.

    Assembly TypeStorefront CartridgesDemo/Init CartridgesAssembly
    B2Capp_sf_responsive
    app_sf_responsive_cm
    app_sf_responsive_b2c
    app_sf_responsive_smb
    as_responsive
    demo_responsive
    demo_responsive_catalog
    demo_responsive_content
    demo_responsive_search
    demo_responsive_ocst
    inspired-b2c
    B2XB2C Storefront Cartridges + app_sf_responsive_b2b
    app_sf_responsive_costcenter
    as_responsive_b2b
    B2C Demo/Init Cartridges +
    demo_responsive_b2b
    inspired-b2x

    The table gives an overview of the needed cartridges for the different assembly types.

  • Rename the folder of the assembly sub project 'inspired-b2x' or 'inspired_b2c' to your preferred name, e.g., assembly_corporateshop. This name is used for the deployment of the project.

  • Adapt build configuration for the used assembly

    If a B2C assembly will be created:

    <DIFF> build.gradle
    assert System.properties['java.version'].startsWith('1.8')
     
    -	def assemblyProjects = [ project(':inspired-b2c'), project(':inspired-b2x') ]
    +	def assemblyProjects = [ project(':assembly_corporateshop') ]

    If a B2X assembly will be created:

    <DIFF> build.gradle
    assert System.properties['java.version'].startsWith('1.8')
     
    -	def assemblyProjects = [ project(':inspired-b2c'), project(':inspired-b2x') ]
    +	def assemblyProjects = [ project(':assembly_corporateshop') ]

    This configuration does only exists in version 3.x (ICM 7.8).

    build.gradle
        buildDir = new File(projectDir, 'target')
    -    if(name == 'inspired-b2x') {
    -        versioning {
    -            useVersionsFrom 'com.intershop.assembly:commerce_management_b2x'
    -        }
    -     }
    -    if(name == 'inspired-b2c') {
    +	 if(name == 'assembly_corporateshop') {
            versioning {
                useVersionsFrom 'com.intershop.assembly:commerce_management_b2x'
            }
        }
    
    

6.2.6 Setup the Initialization Cartridges

The Responsive Starter Store provides a set of demo cartridges that can be kept as starting point for the projects initialization cartridges or they can be removed completely.

CartridgeDescription
demo_responsiveDemo organization structure for inSPIRED with inTRONICS, inTRONICS Business and Myers
demo_responsive_catalogCatalogs with categories and products for the inSPIRED organization
demo_responsive_contentCMS demo content (including campaigns and promotions) for the inSPIRED organization
demo_responsive_searchSearch demo configuration
demo_responsive_ocstAdditional demo content of the OCST (Omni-channel Services Toolset, a.k.a. Contact Center)
demo_responsive_b2bB2B specific content for the inTRONICS Business channel

In case they are used as init cartridges it is probably useful to rename the cartridges from "demo_..." to "init_..." or some other project naming scheme.
The renaming needs to be done for the cartridges folder name of the cartridge. The display name and description of the cartridge can be renamed in the build.gradle.

6.2.7 Setup the Intershop Microservices

The Responsive Starter Store provides a sub-project microservice, which contains the microservices scheduling and recurring order.

Database for microservices

It's mandatory for production system to replace the Derby Database. Therefore the build.gradle of the microservice sub-project has to be adapted

For Oracle it is necessary to configure the correct database driver. If you have this driver in an other group, please adapt the configuration.

build.gradle
dependencies {

    /** driver for derby */
    - runtime 'org.apache.derby:derby:10.12.1.1'
    /** driver for oracle */
    /** this configuration uses the prepared oracle drivers **/
    /** see 'Cookbook - Setup CI Infrastructure', 7.2.5 Process for Building the Oracle JDBC Drivers Component **/
    + runtime 'com.oracle.jdbc:ojdbc7:12.1.0.2.0.0'
}

6.2.8 Extend the 'ignore' Configuration

During the build of same cartridges CSS files will be generated with a Less compiler. These files must be generated to staticfiles/cartridge/static/default/css. Therefore it is necessary to extend the ignore configuration for these cartridges.

Cartridge with less compiler configuration
app_sf_responsive
app_sf_responsive_b2b
app_sf_responsive_smb

6.2.8.1 Subversion

It is possible to add svn:global-ignores for the project directory:

svn:global-ignores
theme.css
theme.css.map

or add svn:ignore to <cartridge name>/staticfiles/cartridge/static/default/css:

svn:ignore
theme.css
theme.css.map

6.2.8.2 Git

Extend .gitignore of the root project:

.gitignore
# IntelliJ project files
.idea
*.iml
out
gen
*.bak
*.log

# Eclipse project files
**/bin/
**/.settings/
**/.classpath
**/.project

# editor backup files
**~

# Gradle Files
**/build/
**/.gradle

# Intershop build directories
**/target/
# Ignore Gradle GUI config
gradle-app.setting
 
# generated css
app_sf_responsive*/staticfiles/cartridge/static/default/css/themes.css
app_sf_responsive*/staticfiles/cartridge/static/default/css/themes.css.map
app_sf_responsive*/staticfiles/cartridge/static/default/css/


# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
!gradle-wrapper.jar

6.2.9 Commit the Changes to the VCS

After the changes it is necessary to commit the changes to the used VCS and transfer the files to the remote server.

6.3 Discussion

6.3.1 Different Options of Customizing the Responsive Starter Store

As mentioned earlier, the demo cartridges of the Responsive Starter Store can be used as blue print for the projects initialization cartridges. For that they should be renamed and fitted to your projects needs.

Regarding the storefront cartridges of the Responsive Starter Store (app_sf_responsive, app_sf_responsive_cm, ...) there are several options on how you can use and customize them in your projects. Those options are described below.

In any case it might be necessary to not only adapt the app_sf_responsive cartridges but also the application type definitions of as_responsive. If additional project cartridges are added they need to be added to the application type definition too.

6.3.1.1 Use Responsive Starter Store Cartridges As Is

This is the above described approach of copying the relevant storefront cartridges of the Responsive Starter Store to your projects.

Any customization can be done within additional project cartridges, with the possibilities overloading and overwriting provides. This is pretty much the same as before, except for the fact that also the Responsive Starter Store storefront cartridges are part of the project cartridges set.

This fact, that the Responsive Starter Store storefront cartridges are part of your projects sources, leads to the second customization option. It is now possible to make any customization directly in the cartridges that were provided by Intershop since they are now project cartridges. You have pretty much the same control over these sources as an Intershop developer has when developing the Responsive Starter Store. Any parts can be changed or removed or added within the cartridges of the Responsive Starter Store. This gives you for example full control over the provided CMS content model, making it possible to simply add new call parameters where needed or removing not wanted components without the need of using the overwrites mechanism.

Using the Responsive Starter Store storefront cartridges as they are is probably the simplest approach. And in case the customization is done within additional project cartridges this is probably the easiest approach for later migrations to new Responsive Starter Store versions too.

In any case newer versions of the Responsive Starter Store cartridges are not getting updated automatically but will be provided as sources too and it is up to the project to decide if and how they will update their currently used Responsive Starter Store cartridges. Less customization in those cartridges will probably make the update/migration easier.

6.3.1.2 Copy and Rename the Responsive Starter Store Cartridges

The Responsive Starter Store is intended to be a blue print for a storefront project. The provided cartridges can be used the way they are regarding their naming and their content or they can be customized in any way wanted.

In case you want to create several independent application types that are initially based on the Responsive Starter Store or if you want to create your own storefront cartridge set based on the Responsive Starter Store but with your own naming conventions, you have to copy and rename the app_sf_responsive cartridges to transform them them into your own cartridges.

For this you basically have to search for all references to app_sf_responsive and alike in the Responsive Starter Store cartridges and replace all with your own cartridge naming. This goes for references in the content model files (*.pagelet2), in pipelines, in ISML templates and configuration files.

Also the CMS import files located in sites folder of demo_responsive_content need to be adapted to the new naming.

After this everything should work as before but with the new naming.

6.3.1.3 Use Own Storefront Cartridges

In case you want to use or create your own storefront cartridge set that is totally different from the Responsive Starter Store you can also remove the app_sf_responsive cartridges completely from your project. In that case you might only use the configuration files of the Responsive Starter Store but not the cartridges to set up your project.

You would build your storefront only on the basic storefront functionality that is provided by the Commerce Management assembly you are using. Basically this gives you only the storefront functionality of the sld_ch_sf_base cartridge. The whole storefront view layer would need to be provided by your own cartridges.

6.3.2 Release Process Configuration and Versioning

Internally, Intershop uses an release process with staging for releases, so that unused milestone builds can be easily dropped. For reporting purposes all issues will be extended with the solved version during the build process. Furthermore the version of internal Intershop projects is calculated from used source repository (see https://github.com/IntershopCommunicationsAG/scmversion-gradle-plugin.) This plugin is required by the release plugin com.intershop.gradle.nexuspublish-configuration. It is also possible to use a version in a property file. In this case the configuration for the com.intershop.gradle.scmversion plugin can be removed.

During the build of same cartridges CSS files will be generated with a less compiler. It is necessary, that these files must be generated to staticfiles/cartridge/static/default/css. Therefore it is necessary to extend the ignore configuration for these directories.

7 Recipe: Setup CI Build for Corporate Artifacts

7.1 Problem

Multiple projects may share the same CI environment. Some artifacts are required once for the CI environment and independently of projects (corporate artifacts).

Which steps are necessary to provide these artifacts for all other processes?

7.1.1 References

7.2 Solution

7.2.1 Prerequisites

See the following recipes:

7.2.2 Steps

  1. Provide host-specific configuration for deployments during assembly build.
  2. Set up the following automated processes on your CI Server:
    1. Process for building the corporate distribution
    2. Process for building the Oracle JDBC Drivers Component Set
  3. Trigger the processes a first time in the order they were set up, so the gradle user home is prepared and artifacts are uploaded to your artifact repository server.

See the following sections for details.

Example

See the discussion for an example using Jenkins and SVN.

7.2.3 Provide Host-specific Configuration

Provide host-specific configuration for deployments during assembly build:

  1. Checkout the host configuration (<sources>/devops/ci_server/host_configs/<hostname>) from your VCS.
  2. Adjust the environment.properties file.
    Depending on the operating system it is necessary to specify the user settings in this file. Furthermore, it is necessary to define the database connection parameter and used ports and interfaces.
  3. Commit the changes to your VCS.
  4. Duplicate the folder <hostname> for each remote-CI agent and repeat the three steps above.

7.2.4 Process for Building Corporate Distribution

Set up an automated process for building the corporate distribution. Configure the process to:

  1. Check out the sources of the corporate distribution from your VCS (<sources>/devops/gradle/corporate-distribution) to the folder corporate-distribution.
  2. Execute the following commands:

    Publish corporate distribution (Linux)
    cd corporate-distribution
    ./gradlew publish 
    Publish corporate distribution (Windows)
    cd corporate-distribution
    gradlew publish 

    This command provides a local published repository. The version is calculated from the used version control system and the available tags. For more details about versioning see https://github.com/IntershopCommunicationsAG/scmversion-gradle-plugin.


    For all available parameters for publishing in a CI environment see Simple Publish Configuration Plugin in the readme of https://github.com/IntershopCommunicationsAG/gradle-release-plugins.

    CI Configuration Example for Windows
    gradlew publish -PrunOnCI=true -PsnapshotURL=<URL for snapshots> -PreleaseURL=<URL for distribution releases> -PrepoUserName=<user with deploy permissions> -PrepoUserPasswd=<user password>

    Make sure, that the sources are stored in a VCS!

This project uses the same configuration and parameters like the main shop project, see Recipe - Setup CI Build For Project Artifacts.

7.2.5 Process for Building the Oracle JDBC Drivers Component

Set up an automated process for building the Oracle JDBC drivers component. Configure the process to:

  1. Check out the sources of the component set from the VCS (<sources>/projects/oracleDriver/3rd_oracle) to the folder 3rd_oracle.

    Note

    It is possible to download the necessary files from the Oracle Maven repository. Therefore the OTN credentials are necessary:

    • OTN account name: OTN_USER
    • OTN accout password: OTN_PASSWORD

    Before you can use the credentials to download artifacts from this Oracle Maven repository, it is required to activate your account for this repository.

    1. Open https://www.oracle.com/webapps/maven/register/license.html.
    2. Accept the license agreement.
  2. Execute the following commands:

    Publish release of p_oracle (Linux)
    cd 3rd_oracle
    export OTN_USER=<OTN user name>
    export OTN_PASSWD=<OTN user password>
    ./gradlew publish -PrepoUserName=<deployment user> -PrepoUserPasswd=<deployment user password> -PreleaseURL=<URL for release publishing>
    Publish release of p_oracle (Windows)
    cd 3rd_oracle
    set OTN_USER=<OTN user name>
    set OTN_PASSWD=<OTN user password>
    gradlew publish -PrepoUserName=<deployment user> -PrepoUserPasswd=<deployment user password> -PreleaseURL=<URL for release publishing>

    It is also possible to specify environment variables for the parameter:

    ParameterEnvironment Variable
    repoUserNameREPO_USER_NAME
    repoUserPasswdREPO_USER_PASSWD
    releaseURLRELEASEURL

7.3 Discussion

7.3.1 Rebuilding Corporate Artifacts

Before rebuilding the corporate distribution always increase the version number (located in <sources>/devops/gradle/corporate-distribution/gradle.properties). After rebuilding, change the version number in the wrapper configuration (gradle-wrapper.properties) of all your projects.

Before rebuilding the Oracle JDBC Drivers component set always increase the version or build number (located in <sources>/projects/oracleDriver/p_oracle/gradle.properties).

7.3.2 Example Using Jenkins

This example assumes that:

  • You use the default output directories structure.

7.3.2.1 Build Item for Corporate Distribution

Create a new build item Corporate Distribution:

ParameterValueDescription
Item namecorporate-distributionThe item name is also used for the directory path. Do not use spaces in this configuration.
Build typeBuild a free-style software project 
Advanced Project Options  
- Display NameCorporate DistributionThis is used for the item name on the web frontend
DescriptionCreates a corporate distribution for the main project 
 
Subversion
General  
This project is parameterized[selected] 
Add ParameterList Subversion tags (and more) 
-  Repository URLhttp://ciserver/svn/intershop/devops/gradle/corporate-distribution/tagsTags URL of the project project.
- CredentialsUsername / Password 
- Tags filterRELEASE_\d+\.\d+\.\d+-?(\S+)?It is necessary to specify an other filter, if the prefix of the Gradle SCM Versioning plugin configuration is different.
-  Default value[empty] 
- Maximum tags to display3This is only an example.
- Sort newest first[selected] 
Source Code ManagementSubversion 
- Repository URLhttp://ciserver/svn/intershop/devops/gradle/corporate-distribution/tags/$TAGNAMEURL of the corporate distribution project
- CredentialsUsername / PasswordSelect Add and configure this parameter in the dialog.
- Local module directorycorporate-distributionThis is the target path in the workspace directory for the the Subversion checkout.

- Check-out Strategy

Use 'svn upate' as much as possibleIt is also possible to checkout always a new copy.
 
Git
General  
This project is parameterized[selected] 
Add Parameter'Git Parameter' 
- NameTAGNAME 
- DescriptionGit tag nameoptional
- Parameter TypeTag 
- Advanced (Button)[selected] 
- Branch[empty]Used only if listing revisions.
- Branch filter[empty]Optional; if release from a special branch will be build
- Tag filterRELEASE_* 
-  Sort modeNONE 
- Default Value[empty] 
- Selected valueTOP 
- Quick filter[not selected] 
Source Code ManagementGit 
- Repository URLhttps://<Git Server with path>/corporate-distribution.gitURL of the corporate distribution project
- Branches to build*/master 
- CredentialsUsername / PasswordSelect Add and configure this parameter in the dialog.
- Advanced (Button)[selected] 
- Branches to build${TAGNAME} 
- Additional behaviors'Check out to a sub-directory' 
Local subdirectory for repocorporate-distribution 
 
Build Triggers[no selection] 
Build Environment  
Inject passwords to the build as environment variables[selected] 
- - Properties ContentRUNONCI=true
RELEASEURL= http://server:8081/nexus/content/repositories/distributions
 
- Global passwords[selected]Global configured password will be used.
BuildExecute Shell / Execute Windows batch commandOn a Linux server use Execute Shell. On Windows, it is necessary to select Execute Windows batch command.
- Command (Linux)
Publish corporate distribution
cd corporate-distribution
./gradlew publish -s
Before the build runs the old build should be deleted. Therefore, the target clean is also called.
REPO_USER_NAME and REPO_USER_PASSWD are specified as global password. See setup CI Server example.
- Command (Windows)
Publish corporate distribution
cd corporate-distribution
gradlew publish -s
Jenkins build log
...
:downloadGradle UP-TO-DATE
:customGradleDistribution
:generateDescriptorFileForIvyPublication
:publishIvyPublicationToIvy Distribution RepositoryRepository
Upload http://server:8081/nexus/content/repositories/distributions/gradle-dist/corporate_gradle_2.11/2.0.0/corporate_gradle_2.11-2.0.0-bin.zip
Upload http://server:8081/nexus/content/repositories/distributions/gradle-dist/corporate_gradle_2.11/2.0.0/ivy.xml
:publish

BUILD SUCCESSFUL


Total time: 6.927 secs


This build could be faster, please consider using the Gradle Daemon: https://docs.gradle.org/2.11/userguide/gradle_daemon.html
Finished: SUCCESS

Corporate distribution in the artifact repository if using Nexus:

7.3.2.2 Build Item for Oracle JDBC Driver Component Set

Create a new build item Oracle JDBC Driver component set:

ParameterValueDescription
Item name3rd_oracleThe item name is also used for the directory path. Do not use spaces in this configuration.
Advanced Project Options  
- Display NameOracle JDBC Driver componentThis is used for the item name on the web frontend
Build typeBuild a free-style software project 
DescriptionCreate Oracle JDBC Driver component set 
 
Subversion
Source Code ManagementSubversion 
- Repository URLhttp://ciserver/svn/intershop/projects/oracleDriver/trunk/p_oracleURL of the Oracle driver project
- CredentialsUsername / PasswordSelect Add and configure this parameter in the dialog.
- Local module directory3rd_oracleThis is the target path in the workspace directory for the the Subversion checkout.
Git
Source Code ManagementGit 
- Repository URLhttps://<Git Server with path>/3rd_oracle.gitURL of the Oracle driver project
- CredentialsUsername / PasswordSelect Add and configure this parameter in the dialog.
- Additional behaviors'Check out to a sub-directory' 
Local subdirectory for repo3rd_oracle 
 
Build TriggersPoll SCM 
- ScheduleH/15 * * * *The build is triggered manually only. Before the build can be restarted, the module must be deleted from the artifact repository.
Build Environment  
- Inject passwords to the build as environment variables[selected]Password will be defined for the environment
- - Properties ContentRELEASEURL=http://server:8081/nexus/content/repositories/releases
- Global passwords[selected]Global configured password will be used
- Job passwords[selected]Optional. Only necessary if the jar files must be downloaded.
 OTN_USER / <Username>
 OTN_PASSWD / <Userpassword>
BuildExecute Shell / Execute Windows batch commandOn a Linux server use Execute Shell. On Windows it is necessary to select Execute Windows batch command.
- Command (Linux)
Publish release of p_oracle
cd 3rd_oracle
./gradlew publish -s

Before the build runs the old build should be deleted. Therefore the target clean is also called.
Username and password of the repository deploy user must be specified with the project properties repoUser and repoUserPasswd. It is also possible to run this command manually.

REPO_USER_NAME and REPO_USER_PASSWD were specified as global passwords.

If artifacts must be downloaded from the Oracle Maven repository (see Process for Building the Oracle JDBC Drivers Component) it is necessary to declare OTN_USER and OTN_PASSWD as job passwords.

The build script is generated with a default release URL from the build configuration (see Recipe - Create Sources From Intershop Templates). It is possible to define a release repository with an environment variable RELEASEREPO or a Java environment variable 'releaseRepo'.

- Command (Windows)
Publish release of p_oracle
cd 3rd_oracle
gradlew publish -s
Log output
...

+ cd 3rd_oracle
+ sh ./gradlew publish -s
Defaults for 'test.corporatename' are used!
The local artifacts are stored in /var/lib/jenkins/.gradle/.localRepo!

:ojdbc7Download
Invalid cookie header: "Set-Cookie: IntradocAuth=Basic; expires=Tue, 08 Aug 2017 16:15:48 GMT; path=/". Invalid 'expires' attribute: Tue, 08 Aug 2017 16:15:48 GMT

Download https://www.oracle.com/content/secure/maven/content/com/oracle/jdbc/ojdbc7/12.1.0.2/ojdbc7-12.1.0.2.jar

:onsDownload
Invalid cookie header: "Set-Cookie: IntradocAuth=Basic; expires=Tue, 08 Aug 2017 16:15:53 GMT; path=/". Invalid 'expires' attribute: Tue, 08 Aug 2017 16:15:53 GMT
Download https://www.oracle.com/content/secure/maven/content/com/oracle/jdbc/ons/12.1.0.2/ons-12.1.0.2.jar

:ucpDownload
Invalid cookie header: "Set-Cookie: IntradocAuth=Basic; expires=Tue, 08 Aug 2017 16:15:56 GMT; path=/". Invalid 'expires' attribute: Tue, 08 Aug 2017 16:15:56 GMT
Download https://www.oracle.com/content/secure/maven/content/com/oracle/jdbc/ucp/12.1.0.2/ucp-12.1.0.2.jar
:generateDescriptorFileForIvyPublication

:publishIvyPublicationToIvyLocalRepository
:publishIvyPublicationToIvyRepository
Upload http://server:8081/nexus/content/repositories/releases/com.intershop/3rd_oracle/12.1.0.2.0.0/jars/ojdbc7-jar-12.1.0.2.0.0.jar
Upload http://server:8081/nexus/content/repositories/releases/com.intershop/3rd_oracle/12.1.0.2.0.0/jars/ons-jar-12.1.0.2.0.0.jar
Upload http://server:8081/nexus/content/repositories/releases/com.intershop/3rd_oracle/12.1.0.2.0.0/jars/ucp-jar-12.1.0.2.0.0.jar
Upload http://server:8081/nexus/content/repositories/releases/com.intershop/3rd_oracle/12.1.0.2.0.0/ivys/ivy-12.1.0.2.0.0.xml
:generatePomFileForMavenOJDBCPublication

:publishMavenOJDBCPublicationToMavenLocalRepositoryCould not find metadata com.oracle.jdbc:ojdbc7/maven-metadata.xml in remote (file:/var/lib/jenkins/.gradle/.localRepo/)

:generatePomFileForMavenONSPublication
:publishMavenONSPublicationToMavenLocalRepositoryCould not find metadata com.oracle.jdbc:ons/maven-metadata.xml in remote (file:/var/lib/jenkins/.gradle/.localRepo/)

:generatePomFileForMavenUCPPublication
:publishMavenUCPPublicationToMavenLocalRepositoryCould not find metadata com.oracle.jdbc:ucp/maven-metadata.xml in remote (file:/var/lib/jenkins/.gradle/.localRepo/)

:publish

BUILD SUCCESSFUL

Total time: 18.328 secs

This build could be faster, please consider using the Gradle Daemon: https://docs.gradle.org/2.11/userguide/gradle_daemon.html
Finished: SUCCESS

 

Oracle JDBC Driver component set in the artifact repository if using Nexus:

7.3.2.3 Jenkins Overview with All Build Items

8 Recipe: Setup CI Build for Project Artifacts

8.1 Problem

After changes on the code base it is a good practice to run an integration build with all automatic tests to provide fast feedback for the developer team. Furthermore, it is necessary to check the impact of the changes on the initialization of the database.

How can an administrator or developer set up a continuous integration process for all project artifacts? 

8.2 Solution

8.2.1 Prerequisites

See the following recipes:

8.2.2 Steps

  1. Set up the following automated processes on your CI Server:
    1. Process for building a snapshot of the project
    2. Process for building a release of the project
  2. Trigger the processes a first time in the order they were set up, so the artifacts are uploaded to your artifact repository server.

Example

See the discussion for an example using Jenkins.

8.2.3 Process for Building the project

Set up an automated process for a snapshot build of the specific Gradle multi project. Configure the process to:

  1. Check out the sources of the component set from the VCS (<sources>/projects/<project name>) to the folder <project name>.
  2. Check out the host configuration (<sources>/devops/ci_server/host_configs/) into the folder host_configs.
  3. Execute the following commands for a snapshot release:

    Publish snapshot of component set (Linux)
    export JAVA_HOME=<directory of JDK 1.8>
    export ENVIRONMENT_PROPS=<workspace directory>/host_configs/<name of executing host>/environment.properties
     
    cd <project name>
    ./gradlew clean dbinit check publish -PrunOnCI=true -PsnapshotURL=http://<url to nexus>/snapshots \
    -PbuildEnvironmentProperties=${ENVIRONMENT_PROPS} -PtestEnvironmentProperties=${ENVIRONMENT_PROPS} --refresh-dependencies -s
    Publish snapshot of component set (Windows)
    set JAVA_HOME=<directory of JDK 1.8>
    set ENVIRONMENT_PROPS=<workspace directory>\host_configs\<name of executing host>\environment.properties
    
    cd <project name>
    gradlew clean dbinit check publish -PrunOnCI=true -PsnapshotURL=http://<url to nexus>/snapshots ^
     -PbuildEnvironmentProperties="%ENVIRONMENT_PROPS%" -PtestEnvironmentProperties="%ENVIRONMENT_PROPS%" --refresh-dependencies -s

    This process should be triggered automatically upon detecting changes in the VCS. This build uses also snapshot repositories for the build. The parameter enableSnapshots is used by the Gradle plugin repoconfig-gradle-plugin (see https://github.com/IntershopCommunicationsAG/repoconfig-gradle-plugin).

If the Gradle SCM Versioning plugin is used, a build of a tag will always create a release. Without this plugin and a static specified version number it is possible to set the project property SNAPSHOT_RELEASE to true so that a snapshot version will be created.

8.2.4 Process for Building a Release of the Project

Set up an automated process for a release build of component set and assembly. Configure the process to:

  1. Check out the sources of the component set from the VCS (<sources>/projects/<project name>) to the folder <project name>.
    If the Gradle SCM Versioning plugin is used, it is necessary to checkout a tag of the VCS.
  2. Check out the host configuration (<sources>/devops/ci_server/host_configs/) into the folder host_configs.
  3. Execute the following commands:

    Publish release of component set and assembly (Linux)
    export JAVA_HOME=<directory of JDK 1.8>
    export ENVIRONMENT_PROPS=<workspace directory>/host_configs/<name of executing host>/environment.properties
     
    cd <project name>
    ./gradlew clean dbinit check publish -PreleaseWithDump=true -PrunOnCI=true -PreleaseURL=http://<url to nexus>/releases \
    -PbuildEnvironmentProperties=${ENVIRONMENT_PROPS} -PtestEnvironmentProperties=${ENVIRONMENT_PROPS} --refresh-dependencies -s
    Publish release of component set and assembly (Windows)
    set JAVA_HOME=<directory of JDK 1.8>
    set ENVIRONMENT_PROPS=<workspace directory>\host_configs\<name of executing host>\environment.properties
    
    cd <project name>
    gradlew clean dbinit check publish -PreleaseWithDump=true -PrunOnCI=true -PreleaseURL=http://<url to nexus>/releases ^
    -PbuildEnvironmentProperties="%ENVIRONMENT_PROPS%" -PtestEnvironmentProperties="%ENVIRONMENT_PROPS%" --refresh-dependencies -s

    If you run the build configuration with the Gradle SCM Versioning plugin, the process should be triggered manually or the build job must be configured only for tags.

8.3 Discussion

8.3.1 Versioning

Intershop provides a public Gradle plugin com.intershop.gradle.scmversion for the version configuration. This plugin calculates the version from the VCS and supports Subversion and Git. For more information see https://github.com/IntershopCommunicationsAG/scmversion-gradle-plugin.

It is also possible to specify a static version in the gradle.properties. For this use case it is necessary to add the project property snapshotRelease or the environment property SNAPSHOT_RELEASE to the command-line for the build of a snapshot.

8.3.2 Snapshot Build

For a fast developer feedback we suggest to use snapshot builds.

  • The build of the multi project ensures, that there are no compile errors and all JUnit tests were finished successfully after a code change.
  • Furthermore it is required, that the database initialization (dbinit) or database migration (DBmigrate) runs without any errors. The build of the assembly sub project runs with a database initialization. Therefore, it takes more time than the build of other sub projects. The run time depends on the size of the database objects.

The result of these build steps represents a temporary status. It is not possible to deploy this on a server for further testing (see section Release Build below).

The feedback time after changes depends on the performance of the build machine, the database, and the amount of data (products, catalogs, customer) for the database initialization.

For the snapshot process it is possible to publish the artifacts to a local file based repository like a developer, but this makes it impossible to distribute processes over different machines.

It is also possible to use only the release process and instead of this to run the release process more often. In this case more artifacts will be published to the artifact repository and a clean up process is necessary.

8.3.3 Release Build 

The release build runs manually on request. If the SCM version plugin is used, it can also run after the creation of a release tag automatically. All project artifacts of this release use the same version. This kind of build can be used for the installation on the integration machine or for long running manual tests.

It is possible to run a temporary installation based on the snapshot build, but it is not possible to reproduce this build result. The result of a release build is reproducible. For the storage of this build information, the init.script contains a task writeBuildInformation. This information can be used for hand over to the next processes or for build documentation. It is also possible to extend this script.

8.3.4 Usage of Simple Publish Configuration Plugin

For more information see https://github.com/IntershopCommunicationsAG/gradle-release-plugins.

Publish parameters can be provided as project properties or as environment variables.

8.3.5 Example Using Jenkins

This example assumes that:

  • You use the default output directories structure.
  • The name of the project is corporateshop.

8.3.6 Add environment.properties to Jekins Configuration

  1. Select Manage Jenkins | Manage files
  2. Select Add a new Config
  3. Select Custom file and click the Submit button.
ParameterValue
Nameenvironment.properties
Commentenvironment setting for deploying a test server during the build on 'machine'
Content

# content is used from VCS 'ci_server-host_configs' (server/environment.properties)

# ID of the platform to deploy on (must match the actual OS/distribution for the tests to be successful)
# Choose from: linux.rhel.x86_64, linux.sles.x86_64, win.x86_64
platformId = linux.sles.x86_64

# ID of the deployed server instance
instanceId = 1

# Set environment for your deployment: production, test, development
environment = development

...

webAdapterSharedMemoryKey = 0x2001

There is no possibility to use this file from the VCS with the Config File Provider Plugin. Furthermore it is not so easy to checkout files from the Git provider in two different sub directories.

8.3.7 Build Item for Snapshot

Create a new build item Project Snapshot:

ParameterValueDescription
Item namecorporateshopThe item name is also used for the directory path. Do not use spaces in this configuration.
Build typeBuild a free-style software project 
Advanced Project Options  
- Display Namecorporateshop - Snapshot BuildsThis is used for the item name on the web front end.
DescriptionCreate a snapshot build of the project "corporateshop" 
 
Subversion
Source Code ManagementSubversion 
- Repository URLhttp://ciserver/svn/intershop/projects/corporateshop/trunkURL of the project
- CredentialsUsername / PasswordSelect Add and configure this parameter in the dialog.
- Local module directorycorporateshopThis is the target path in the workspace directory for the the Subversion checkout.
 
Git
Source Code ManagementGit 
- Repository URLhttps://gitserver/<path>/corporateshop.git 
- CredentialsUsername / Password 
- Additional BehavioursCheck out to a sub-directory 
Local subdirectory for repocorporateshop 
 
Build TriggersPoll SCM 
- ScheduleH/5 * * * *The job will check the VCS for changes every 5 minutes.
Build Environment  
- Inject environment variables to the build process[selected] 
- - Properties ContentRUNONCI=true
SNAPSHOTURL=http://server:8081/nexus/content/repositories/snapshots
 
- Inject passwords to the build as environment variables[selected] 
-- Global passwords[selected]Global configured password will be used.
Build  
- Provide Configuration files
ParameterValue
Fileenvironment.properties
Target[empty]
VariableENVIRONMENT_PROPS
Replace Tokens[not selected]
 
- Command (Linux)
Execute Shell  
Publish snapshot of component set
export JAVA_HOME=/usr/java/jdk1.8.0
 
cd corporateshop
 
./gradlew clean dbinit check publish \
--refresh-dependencies \
-PbuildEnvironmentProperties="${ENVIRONMENT_PROPS}" \
-PtestEnvironmentProperties="${ENVIRONMENT_PROPS}" -s

Change to the project folder.
Run the publish target of the build with the environment configuration.

REPO_USER_NAME and REPO_USER_PASSWD are specified as global password.

- Command (Windows)
Execute Windows batch 
Publish snapshot of component set
set JAVA_HOME=c:/<path to JDK 1.8.0>
 
cd corporateshop
gradlew clean dbinit check publish ^
--refresh-dependencies ^
-PbuildEnvironmentProperties="${ENVIRONMENT_PROPS}" ^
-PtestEnvironmentProperties="${ENVIRONMENT_PROPS}" -s
Log output
Defaults for 'test.corporatename' are used!
The local artifacts are stored in /var/lib/jenkins/.gradle/.localRepo!
Parallel execution with configuration on demand is an incubating feature.

All tasks will be executed on a CI build environment.

It is not possible to identify the correct version. The default value 3.0.0 will be u


...
 
:assembly_corporateshop:remoteTest
:assembly_corporateshop:check
:assembly_corporateshop:build
:assembly_corporateshop:generateSampleSettingsGradle
:assembly_corporateshop:packSamples
:assembly_corporateshop:publishBuildAssemblyPublicationToIntershopIvyCIRepository SKIPPED
:assembly_corporateshop:publishBuildAssemblyPublicationToIvyLocalRepository SKIPPED
:assembly_corporateshop:publishBuildAssemblyPublicationToTestRepository SKIPPED
:assembly_corporateshop:publishIvyPublicationToBuildRepository SKIPPED
:assembly_corporateshop:publishIvyPublicationToIntershopIvyCIRepository
Upload http://server:8081/nexus/content/repositories/snapshots/com.company.corporateshop/assembly_corporateshop/3.0.0-SNAPSHOT/gradles/deploy-deploy-gradle-3.0.0-SNAPSHOT.gradle
Upload http://server:8081/nexus/content/repositories/snapshots/com.company.corporateshop/assembly_corporateshop/3.0.0-SNAPSHOT/gradles/deploy-settings-deploy-settings-gradle-3.0.0-SNAPSHOT.gradle
Upload http://server:8081/nexus/content/repositories/snapshots/com.company.corporateshop/assembly_corporateshop/3.0.0-SNAPSHOT/ivys/ivy-3.0.0-SNAPSHOT.xml

:assembly_corporateshop:publishIvyPublicationToIvyLocalRepository
:assembly_corporateshop:publishIvyPublicationToTestRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToBuildRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToIntershopIvyCIRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToIvyLocalRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToTestRepository
:assembly_corporateshop:publish

BUILD SUCCESSFUL

Total time: 1 hrs 4 mins 29.677 secs

This build could be faster, please consider using the Gradle Daemon: https://docs.gradle.org/2.11/userguide/gradle_daemon.html
Finished: SUCCESS

Jenkins overview page:

For a better overview of the existing projects in Jenkins separate tabs Project Builds and Corporate Builds were created. The duration of the assembly build depends on the performance of the build machine and the database.

8.3.8 Build Item for Release Build

This is an example for a parameterized build. It expects always a created tag in the VCS. 

Note

The used Git Parameter Plugin needs a cloned repository in the work space. Therefore it is necessary to configure first the project without parameters and without a build step. After the first run, the work space is created and a clone of the specified repository is available.

Create a new build item Release corporateshop_release:

ParameterValueDescription
Item namecorporateshop_releaseThe item name is also used for the directory path. Do not use spaces in this configuration.
Build typeBuild a free-style software project 
Advanced Project Options  
- Display Namecorporateshop - Release BuildsThis is used for the item name on the web front end.
DescriptionCreate the release of all artifacts of the "corporateshop" project. 
 
Subversion
General  
This project is parameterized[selected] 
Add ParameterList Subversion tags (and more) 

- Name

TAGNAME 
-  Repository URLhttp://ciserver/svn/intershop/projects/corporateshop/tagsTags URL of the project project.
- CredentialsUsername / Password 
- Tags filterRELEASE_\d+\.\d+\.\d+-?(\S+)?It is necessary to specify an other filter, if the prefix of the Gradle SCM Versioning plugin configuration is different.
-  Default value[empty] 
- Maximum tags to display3This is only an example.
- Sort newest first[selected] 
Source Code ManagementSubversion 
- Repository URLhttp://ciserver/svn/intershop/projects/corporateshop/tags/$TAGNAMEURL of the project project.
- CredentialsUsername / PasswordSelect Add and configure this parameter in the dialog.
- Local module directorycorporateshopThis is the target path in the workspace directory for the the Subversion checkout.
 
Git
General  
This project is parameterized[selected] 
Add Parameter'Git Parameter' 
- NameTAGNAME 
- DescriptionGit tag nameoptional
- Parameter TypeTag 
- Advanced (Button)[selected] 
- Branch[empty]Used only if listing revisions.
- Branch filter[empty]Optional, used if a release from a special branch will be build.
- Tag filterRELEASE_* 
-  Sort modeNONE 
- Default Value[empty] 
- Selected valueTOP 
- Quick filter[not selected] 
Source Code ManagementGit 
- Repository URLhttps://gitserver/<path>/corporateshop.gitURL of the project assembly
- CredentialsUsername / PasswordSelect user and password.
- Advanced (Button)[selected] 
- Branches to build${TAGNAME} 
- Additional BehavioursCheck out to a sub-directory 
Local subdirectory for repocorporateshop 
 
Build Triggers[not selected] 
Build Environment  
-  Inject environment variables to the build process[selected] 
- - Properties ContentRUNONCI=true
RELEASEURL= http://server:8081/nexus/content/repositories/releases
 
- Inject passwords to the build as environment variables[selected] 
-- Global passwords[selected]Global configured password will be used.
Build  
- Provide Configuration files
ParameterValue
Fileenvironment.properties
Target[empty]
VariableENVIRONMENT_PROPS
Replace Tokens[not selected]
 
- Command (Linux)
Execute Shell  
Publish release build of component set
export JAVA_HOME=/usr/java/jdk1.8.0
 
cd corporateshop
 
./gradlew clean dbinit check publish \
-PreleaseWithDump=true --refresh-dependencies \
-PbuildEnvironmentProperties="${ENVIRONMENT_PROPS}" \
-PtestEnvironmentProperties="${ENVIRONMENT_PROPS}" -s

Change to the project folder.
Run the publish target of the build with the environment configuration.

REPO_USER_NAME and REPO_USER_PASSWD are specified as global password.

- Command (Windows)
Execute Windows batch 
Publish release build of component set
set JAVA_HOME=c:/<path to JDK 1.8.0>
 
cd corporateshop
gradlew clean dbinit check publish ^
-PreleaseWithDump=true --refresh-dependencies ^
-PbuildEnvironmentProperties="${ENVIRONMENT_PROPS}" ^
-PtestEnvironmentProperties="${ENVIRONMENT_PROPS}" -s

For the creation of a build select Build with Parameters. In the following dialog it is possible to specify the tag name.

 

Log output
...
+ sh ./gradlew clean dbinit check publish --refresh-dependencies -PreleaseWithDump=true -PbuildEnvironmentProperties=/var/lib/jenkins/workspace/corporateshop_release@tmp/config340512709915159000tmp -PtestEnvironmentProperties=/var/lib/jenkins/workspace/corporateshop_release@tmp/config340512709915159000tmp -s
Defaults for 'test.corporatename' are used!
The local artifacts are stored in /var/lib/jenkins/.gradle/.localRepo!
Parallel execution with configuration on demand is an incubating feature.
All tasks will be executed on a CI build environment.
Buildinfo task will be executed on a CI build environment for corporateshop.
Buildinfo task will be executed on a CI build environment for app_sf_responsive.
The included ResourceListPlugin is deprecated! Please apply the new plugin com.intershop.gradle.cartridge-resourcelist (https://github.com/IntershopCommunicationsAG/resourcelist-gradle-plugin)
Buildinfo task will be executed on a CI build environment for app_sf_responsive_b2b
...
:demo_responsive_search:build
:dev_storefront:isml
:dev_storefront:assemble
:dev_storefront:check UP-TO-DATE
:dev_storefront:build
:publish UP-TO-DATE
:app_sf_responsive_b2b:publishIvyPublicationToIntershopIvyCIRepository
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/app_sf_responsive_b2b/3.1.0/zips/app_sf_responsive_b2b-share-3.1.0.zip
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/app_sf_responsive_b2b/3.1.0/jars/app_sf_responsive_b2b-jar-3.1.0.jar
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/app_sf_responsive_b2b/3.1.0/zips/app_sf_responsive_b2b-cartridge-3.1.0.zip
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/app_sf_responsive_b2b/3.1.0/ivys/ivy-3.1.0.xml
:app_sf_responsive_b2b:publishIvyPublicationToIvyLocalRepository
:app_sf_responsive_b2b:publish
...
:assembly_corporateshop:deployServer
Execute 'deploy'
Initialization script '/var/lib/jenkins/workspace/corporateshop_release/corporateshop/build/build-repo/build-repository.gradle': line 20
Defaults for test.corporatename are used for inject repositories!
Defaults for 'test.corporatename' are used!
The local artifacts are stored in /var/lib/jenkins/.gradle/.localRepo!
SID-based database configuration is deprecated, prefer to use service name instead
No usage of well-known ports detected. HTTPd binary will be run by jenkins.
:3rd_ant:deployDirectories UP-TO-DATE
:3rd_apache:deployDirectories
:3rd_oracle:deployDirectories
...
:assembly_corporateshop:build
:assembly_corporateshop:generateSampleSettingsGradle
:assembly_corporateshop:packSamples
:assembly_corporateshop:publishBuildAssemblyPublicationToIntershopIvyCIRepository SKIPPED
:assembly_corporateshop:publishBuildAssemblyPublicationToIvyLocalRepository SKIPPED
:assembly_corporateshop:publishBuildAssemblyPublicationToTestRepository SKIPPED
:assembly_corporateshop:packBranding
:assembly_corporateshop:packEncryptionConfig
:assembly_corporateshop:publishIvyPublicationToBuildRepository SKIPPED
:assembly_corporateshop:publishIvyPublicationToIntershopIvyCIRepository

Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/assembly_corporateshop/3.1.0/dmps/database-dump-dump-3.1.0.dmp
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/assembly_corporateshop/3.1.0/zips/encryption-config-encryption-config-3.1.0.zip
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/assembly_corporateshop/3.1.0/zips/branding-share-3.1.0.zip
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/assembly_corporateshop/3.1.0/gradles/deploy-deploy-gradle-3.1.0.gradle
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/assembly_corporateshop/3.1.0/gradles/deploy-settings-deploy-settings-gradle-3.1.0.gradle
Upload http://server:8081/nexus/content/repositories/releases/com.company.corporateshop/assembly_corporateshop/3.1.0/ivys/ivy-3.1.0.xml

:assembly_corporateshop:publishIvyPublicationToIvyLocalRepository
:assembly_corporateshop:publishIvyPublicationToTestRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToBuildRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToIntershopIvyCIRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToIvyLocalRepository SKIPPED
:assembly_corporateshop:publishTestAssemblyPublicationToTestRepository
:assembly_corporateshop:publish

BUILD SUCCESSFUL

Total time: 1 hrs 6 mins 54.656 secs

This build could be faster, please consider using the Gradle Daemon: https://docs.gradle.org/2.11/userguide/gradle_daemon.html

Finished: SUCCESS

Release artifacts are stored in the repository:

That is the final Jenkins overview page:

9 Recipe: Configuration of a Secured Repository

9.1 Problem

If the repository is accessible over the public internet, it is necessary to configure the security of the repository.

This recipe describes a security configuration for Sonatype Nexus.

9.2 Solution

9.2.1 Repository Configuration

Once you have configured the basic repository, the following configuration for the repository is required.

  1. Change the password of the standard admin account.
    1. Switch to the Profile tab of the user menu.
    2. Click Change Password and provide your own password.
  2. Add Repository Target Privileges for repositories.
    1. Select Privileges.
    2. Select Add | Repository Target Privilege.

       
    3. Add the target privileges.

      NameDescriptionRepositoryRepository Target
      DistributionsTarget Privilege DistributionsDistributions (Repo)All (Maven 2)
      ComponentsTarget Privilege ComponentsComponents (Group)All (Maven 2)
      ReleasesTarget Privilege ReleasesReleases (Repo)All (Maven 2)
      IntershopTarget Privilege Intershop ReleasesIntershop (Repo)All (Maven 2)
      SnapshotsTarget Privilege SnapshotsSnapshots (Repo)All (Maven 2)
      CentralTarget Privilege CentralCentral (Repo)All (Maven 2)

      JCenter

      Target Privilege JCenterJCenter (Repo)All (Maven 2)

  3. Create roles for accessing the repositories.
    1. Select Roles.
    2. Select Add | Nexus Role.

      If you use LDAP or an other user database like Atlassian Crowd, it is possible to create External Role Mapping instead.
    3. Add the role configuration and finish this configuration with Save.

      Role IDNameRole/Privilege Management
      maven2-distributions-readRole: Distributions (read)Distributions - (read)
      Distributions - (view)
      maven2-components-readRole: Components (read)Components - (read)
      Components - (view)
      maven2-snapshots-readRole: Snapshots (read)Snapshots - (read)
      Snapshots - (view)
      maven2-central-readRole: Central (read)Central - (read)
      Central - (view)
      maven2-jcenter-readRole: JCenter (read)JCenter - (read)
      JCenter - (view)
      maven2-projectbuilds-fullRole: Projectbuilds (full)Releases - (create)
      Releases - (delete)
      Releases - (read)
      Releases - (update)
      Releases - (view)
      Snapshots - (create)
      Snapshots - (delete)
      Snapshots - (read)
      Snapshots - (update)
      Snapshots - (view)
      maven2-ishrepo-fullRole: Intershop (read)Intershop - (read)
      Intershop - (view)


  4. Add a role for the project developer.
    1. Select Roles.
    2. Select Add | Nexus Role.
    3. Add the role configuration for a project developer and finish this configuration with Save

      Role IDNameRole/Privilege Management
      nexus-project-developerProject DeveloperNexus Developer Role
      Role: Distributions (read)
      Role: Components (read)
      Role: Maven all (read)
      Role: Snapshots (read)
      Role: Central (read)

      Instead of separate roles for the repositories, it also possible to use Repo: All Maven2 Repositories (View) and Repo: All Maven2 Repositories (Read)

  5. Add a role for the project deployment user.
    1. Select Roles.
    2. Select Add | Nexus Role.
    3. Add the role configuration for a project deployment user and finish this configuration with Save.

      Role IDNameRole/Privilege Management
      nexus-project-deploymentProject Deployment User

      Nexus Deployment Role
      Role: Projectbuilds (full)
      Role: Components (read)
      Role: Maven all (read)
      Project Developer

      The role Project Developer is used to ensure that Project Deployment Users have the same repositories available as developers.

  6. Add a role for a special deployment user.
    For special artifacts, such as Intershop releases or Gradle artifacts (distribution, plugins), it is possible to create a special deployment user.

    1. Select Roles.
    2. Select Add | Nexus Role.
    3. Add the role configuration for a special deployment user and finish this configuration with Save.

      Role IDNameRole/Privilege Management
      nexus-intershop-deploymentIntershop Deployment UserNexus Deployment Role
      Role: Gradle (full)
      Role: Intershop Releases (full) 
  7. Remove read privileges for all repositories from the anonymous user.
    1. Select Users.
    2. Select the user anonymous.
    3. Select Repo: All Repositories (Read).
    4. Select Remove.
    5. Save the configuration.
  8. Add read privileges for the distributions repository to the anonymous user.
    1. Select Users.
    2. Select the user anonymous.
    3. Select Add | Role: Distributions (read) from the list of roles.
       
  9. Add deployment users.
    1. Configure a deployment user for corporate artifacts (Corporate Distribution, Corporate Configuration Plugin, Intershop releases).
      1. Select Users.
      2. Select Add | Nexus User.
      3. Specify the configuration and finish the configuration with Save.

        PropertyValue
        User ID (Login)corp_deployment
        Email<admin account of this user>
        StatusActive
        Password<password for all processes>
        Role ManagementIntershop Deployment User
    2. Configure a deployment user for project artifacts.
      1. Select Users.
      2. Select Add | Nexus User.
      3. Specify the configuration and finish the configuration with Save.

        PropertyValue
        User ID (Login)prj_deployment
        Email<admin account of this user>
        StatusActive
        Password<password for all processes>
        Role ManagementProject Deployment User
  10. Create and configure developer accounts.
    1. Select Users.
    2. Select Add | Nexus User.
    3. Specify the configuration and finish the configuration with Save.

      PropertyValue
      User ID (Login)<developer account login>
      Email<email of the user>
      StatusActive
      Password<password>
      Role ManagementProject Developer

9.2.2 Build and Deployment Configuration

It is necessary to extend the local gradle.properties or the environment settings with the necessary credentials.

Build and Deployment on CI Server

Process 
  • Import Intershop Delivery
  • Setup CI Build For Corporate Artifacts
    • Corporate Distribution

For this task it is necessary to use the deployment user for corporate artifacts. User name and password is part of the command line.

Example
gradlew clean publish -PrepoUserName=corp_deployment -PrepoUserPasswd=<passwd>
  • Oracle JDBC Drivers Component Set

The result of the build will be published to the releases repository. Therefore, it is necessary to use the project deployment user.

Example
cd p_oracle
set OTN_USER=<OTN user name>
set OTN_PASSWD=<OTN user password>
gradlew publish -PrepoUserName=prj_deployment -PrepoUserPasswd=<password> -PreleaseURL=<URL for release publishing>
  • Component Set Build
  • Assembly Build

The result of the build will be published to the releases or snapshots repository. Therefore, it is necessary to use the project deployment user. But this process needs also read access to other repositories.

Example
// this configuration is necessary for the read access as well for publishing
export REPO_USER_NAME=prj_deployment
export REPO_USER_PASSWD=<deploy user password>

// Project properties will be used for the write access 
export JAVA_HOME=<directory of JDK 1.8>
set ENVIRONMENT_PROPS=<workspace directory>\host_configs\<name of executing host>\environment.properties
 
cd <project name>
gradlew clean check publish startWebserver startNodemanager remoteTest -PreleaseWithDump=true -PrunOnCI=true ^
-PreleaseURL=http://<url to nexus>/releases -PbuildEnvironmentProperties="%ENVIRONMENT_PROPS%" ^
-PtestEnvironmentProperties="%ENVIRONMENT_PROPS%" --refresh-dependencies -s 

Build and Deployment on Development Machine

The developer can also specify the user name and password on the command line or as an environment variable. But this is not really user friendly.

It is possible to add the login credentials in the gradle.properties of the Gradle user home.

<GRADLE_USER_HOME>/gradle.properties
systemProp.repoUserName = <developer account login>
systemProp.repoUserPasswd = <developer account password>

9.3 Discussion

User names and passwords are sent to the repository server for authentication. For security reasons, the transport should be secured. Therefore, it is necessary to configure HTTPS for the server communication. It is recommended to use a certificate created by a certification authority. For private certificates, it is necessary to import them in the key-store of the used JDK. This must be done on all machines that have access to the repository -- developer, build, test and production machines also. 

User names and passwords of users must be stored as plain text on the developer machine as well as on the build machine. This login and password can be used also for logging in to the repository server directly. So it is also possible to change the password this way.

Sonatype also provides a professional version of Nexus with costs. This version can use special tokens for the build and deployment access to the repository. It is not possible to log in to the server with these credentials.

10 Recipe: Create a Proxy Repository Chain

10.1 Problem

If the connection between the repository server on the development side and the production environment is bad or there is an additional development or test team, it is necessary to setup a proxy repository chain.

How can an administrator set up a second repository?

10.2 Solution

10.2.1 Prerequisites

See the following recipes:

10.2.2 Configuration Steps

Follow the installation steps in Recipe - Configure Artifact Repository Server except the configuration of the proxy repository to Intershop (ishrepo).

  1. Create a proxy repository to the repositories ishrepo and releases.

    NameIDRepository TypeRemote Storage LocationFormatRemarks
    Intershop Repository on AishrepoproxyProxyhttp[s]://<hostname of A>/nexus/content/repositories/releasesMaven2Depending on the security configuration it is necessary to configure the authentication for the connection. 
    Releases Repository on AreleasesproxyProxyhttp[s]://< hostname of A>/nexus/content/repositories/ishrepoMaven2

    "A" is the placeholder for the name of the location of the first repository server.

  2. The following repository forms a repository group of different repositories. There are hosted repositories as well as the proxy repositories there. Create it according to the following table:

    NameIDRepository TypeFormatRepository IDs
    ComponentscomponentsgroupMaven2Releases, Intershop Repository on A , Releases Repository on A , JCenter, Central

    Once you created the new repository group, switch to the configuration tab an move the needed repository from Available Repositories to Ordered Group Repositories.

    Note

    The order of the assigned repositories is very important.

    1. JCenter
    2. Intershop Repository on A
    3. Releases Repository on A
    4. Releases
    5. Central


  3. Create sources for the corporate distribution
    1. Follow the steps in Recipe: Create Sources From Intershop Templates to step four.
      The project configuration on the build.gradle file is not necessary.
    2. Run the following command:

      ./gradlew createCorporateDistribution createDeploymentConfig
    3. Store the sources of deployments/ corporateshop and gradle/ corporate-distribution in a version control system.

      For more detailed information see Recipe - Create Sources From Intershop Templates.

  4. Build and publish the corporate distribution.
    1. Checkout the sources from step 3.
    2. Open a command line and check your environment. It is necessary to have Java in your path or the JAVA_HOME is configured for your environment.
    3. Execute the command:

      gradlew clean publish -DREPO_USER_NAME=<deploy user login> -DREPO_USER_PASSWD=<deploy user password>

      For more information see Recipe: Setup CI Build for Corporate Artifacts.

10.3 Discussion

The corporate distribution is used in the deployment configuration. It is a standard Gradle distribution with included repository configurations. Therefore it is necessary to have an own corporate distribution for the environment of the new proxy repository.

If you want to extend the delivery from the location "A", it is necessary to setup an own CI environment. In this case you have to create more template sources and a setup of a CI server is necessary.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets