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).

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

Below is the overview of all necessary components:

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.

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. Set up CI Process for Corporate Artifacts (see recipe Set up CI Build for Corporate Artifacts)
   This recipe describes how to build artifacts on the CI server only needed once per environment.
4. Set up CI Process for Project Artifacts (see recipe Set up CI Build for Project Artifacts)
   This recipe describes how to build artifacts, needed separately for each project, on the CI server.
5. Set up a developer environment (see Cookbook - Gradle Developer Workflow | Recipe: Set up a Development Environment).
   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.

Glossary

References

• Public Release Notes - Gradle Tools - Version 2.11

• Gradle User Guide

• Gradle Build Language Reference (DSL)

• Gadle Java Documentation

• Cookbook - Gradle Build Tools
• Deployment Cookbooks depending on the used version
  • Cookbook - Gradle Deployment Tools (7.4 CI - ICM 7.7)
  • Cookbook - Deployment Tools ICM 7.8
  • Cookbook - Deployment Tools ICM 7.9
  • Cookbook - Deployment Tools ICM 7.10

• Standardizing And Administering Your Enterprise Build Environment

• Jenkins Home Page

Migration

General

This section gives an overview of 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 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 Set up CI Build For Project Artifacts.

Gradle Tools 2.11 Updates

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

Recipe: Configure Artifact Repository Server

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?

Solution

Supported Servers

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

• Sonatype Nexus
• JFrog Artifactory
• Apache Archiva

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!

Prerequisites

• JDK 1.8 is installed
• JAVA_HOME is specified.

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:

   ID	Usage	Comment
   jcenter	For 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.
   central	For Maven artifacts available from Maven Central. (Proxy for https://repo1.maven.org/maven2/)
   ishrepo	For binary artifacts provided by Intershop. (Proxy for https://repository.intershop.de/) Please have a look at your contract page in the Intershop KB area for more information.
   distributions	Repository for Gradle distributions.
   releases	For corporate/ project releases.
   snapshots	For all artifacts from snapshot builds. This is the only repository that should allow overwriting of existing artifacts with the same name and version.
   components	This repository combines releases, jcenter, central, ishreleases (if present), and ishrepo into one group.	This is a repository group. Please check the detailed configuration below.

   Note

   As of March 31, 2021, JCenter no longer provides new artifacts and goes into read-only state. Therefore Gradle deprecated the jCenter repository configuration and will remove this in the next major version. For this reason, Intershop moves to Maven Central for new Maven artifacts.

   What is needed for the future? Make sure to add the proxy repository configuration for Maven Central (https://repo1.maven.org/maven2/) to your Artifact Repository Server in parallel with the JCenter configuration.

   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.

   ID	Usage	Comment
   jcenter	For Maven artifacts available from Bintray JCenter (Proxy for https://jcenter.bintray.com)	These are artifact proxies to repositories in the internet that cache all artifacts that have already been retrieved.
   central	For Maven artifacts available from Maven Central (Proxy for https://repo1.maven.org/maven2/)
   distributions	Repository for Gradle distributions	This is a Maven repository.
   ivy-local-releases	For corporate/ project releases of Ivy artifacts	Replaces releases configuration in this special kind of configuration.
   mvn-local-releases	For corporate/ project releases of Maven artifacts
   ivy-intershop	For Ivy binary artifacts provided by Intershop. This is a proxy repository for https://repository.intershop.de/ivy-releases	Replaces ishrepo configuration in this special kind of configuration.
   mvn-intershop	For Maven binary artifacts provided by Intershop. This is a proxy repository for https://repository.intershop.de/mvn-releases
   ivy-releases	This repository combines local Ivy releases (ivy-local-releases), Intershop Ivy releases (ivy-intershop) into one group.	These are group or virtual repositories. It replaces components configuration in this special kind of configuration.
   mvn-releases	This repository unites local Maven releases (mvn-local-releases), Intershop Maven (mvn-intershop) releases and JCenter in one group.
   ivy-local-snapshots	For 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-snapshots	For 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 permissions to publish new artifacts.
      In Maven the process of pushing artifacts to the repository is called deploy and release, while in Gradle it is called publish.

Discussion

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:

Proxy Repositories

If you need additional remote repositories, all these repositories should be configured in one group. This makes it easier to configure this kind of repository 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.

Set up the Intershop Proxy Repository

The Intershop Proxy Repository in your repository provides artifacts according to your contract with Intershop. So you need to log in 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).

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

Hosted Repositories

Create and configure the following repositories as hosted:

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:

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

Components Configuration

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.

Summary

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

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

The resulting repository overview should look like this:

Recipe: Configure CI Server

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?

Solution

This is an example list of CI servers:

• Atlassian Bamboo
• Jenkins / Hudson
• Jetbrains TeamCity

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.

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.

Steps

Choose a CI server and perform the following steps:

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.

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.

Discussion

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.

Plugin Recommendations

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

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

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.

      Name	REPO_USER_NAME	REPO_USER_PASSWD
      Password	e.g., admin	e.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. 1. Go to Manage Jenkins | Configure Systems.
   2. Select Global Passwords | Add.

   3. Add password.

      Name	SCM_USERNAME	SCM_PASSWORD
      Password	e.g., username	e.g., password

Recipe: Create Sources From Intershop Templates

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?

Solution

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.

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.

Discussion

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.

Optional Adjustments of build.gradle

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.

plugins {
    id 'com.intershop.gradle.cisetup' version '2.1.0'
}

IntershopCISetup {
	directories {
		setupDirectory = '/home/developer/intershop-ci/sources'
		devOpsDir = "${setupDirectory}/devops"
	
		projectsDir = "${setupDirectory}/projects"
	}
}

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"
	}
}

Repositories

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

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.

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. 

Project settings

The section intershopProject defines only the name of the project. 

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:

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).

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.

Additional Code Changes for Old Intershop Versioning Plugin

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
+ }

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"

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

http://nexus:8081/nexus/content/repositories/releases/gradle-dist/ish/2.0.0-SNAPSHOT/ish-2.0.0-20200618.073037-1.zip

git tag RELEASE_2.0.1

git commit

http://nexus:8081/nexus/content/repositories/releases/gradle-dist/ish/2.0.1/ish-2.0.1.zip

Recipe: Set up Project Based on the Responsive Starter Store

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?

Solution

Prerequisites

See the following recipes:

• Recipe: Configure CI Server
• Recipe: Create Sources From Intershop Templates

Steps

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.

Download the Latest Version of the Responsive Starter Store

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

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

Responsive Starter Store version 32.2.4 for Intershop Commerce Management 7.10

• 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/32.2.4/zips/a_responsive-zip-src-32.2.4.zip

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.

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.
   Do not skip this step! You really need to delete these folders, otherwise you will run into exceptions.

  Assembly Type	Storefront Cartridges	Demo/Init Cartridges	Assembly
  B2C	app_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
  B2X	B2C 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'
          }
      }
  
  

Set up 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.

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.

Set up the Intershop Microservices

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

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

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 of CI Infrastructure', 7.2.5 Process for Building the Oracle JDBC Drivers Component **/
    + runtime 'com.oracle.jdbc:ojdbc7:12.1.0.2.0.0'
}

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.

Subversion

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

theme.css
theme.css.map

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

theme.css
theme.css.map

Git

Extend .gitignore of the root project:

# 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

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.

Discussion

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.

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.

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.

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.

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.

Recipe: Set up CI Build for Corporate Artifacts

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?

References

• The Gradle Wrapper
• Standardizing And Administering Your Enterprise Build Environment
• Concept - Gradle Build Tools

Solution

Prerequisites

See the following recipes:

• Recipe - Create Sources From Intershop Templates
• Recipe - Configure CI Server

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.

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.

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.

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:

   Parameter	Environment Variable
   repoUserName	REPO_USER_NAME
   repoUserPasswd	REPO_USER_PASSWD
   releaseURL	RELEASEURL

Discussion

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).

Example Using Jenkins

This example assumes that:

• You use the default output directories structure.

Build Item for Corporate Distribution

Create a new build item Corporate Distribution:

cd corporate-distribution
./gradlew publish -s

cd corporate-distribution
gradlew publish -s

...
: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:

Build Item for Oracle JDBC Driver Component Set

Create a new build item Oracle JDBC Driver component set:

cd 3rd_oracle
./gradlew publish -s

cd 3rd_oracle
gradlew publish -s

...

+ 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:

Jenkins Overview with All Build Items

Recipe: Set up CI Build for Project Artifacts

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? 

Solution

Prerequisites

See the following recipes:

• Recipe: Configure CI Server
• Recipe: Create Sources From Intershop Templates
• Recipe: Set up CI Build for Corporate Artifacts

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.

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.

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.

Discussion

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.

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.

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.

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.

Example Using Jenkins

This example assumes that:

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

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.

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.

Build Item for Snapshot

Create a new build item Project Snapshot:

export JAVA_HOME=/usr/java/jdk1.8.0
 
cd corporateshop
 
./gradlew clean dbinit check publish \
--refresh-dependencies \
-PbuildEnvironmentProperties="${ENVIRONMENT_PROPS}" \
-PtestEnvironmentProperties="${ENVIRONMENT_PROPS}" -s

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

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.

Build Item for Release Build

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

Create a new build item Release corporateshop_release:

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

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.

...
+ 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:

Recipe: Configure a Secured Repository

Problem

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

Solution

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.

      Name	Description	Repository	Repository Target
      Distributions	Target Privilege Distributions	Distributions (Repo)	All (Maven 2)
      Components	Target Privilege Components	Components (Group)	All (Maven 2)
      Releases	Target Privilege Releases	Releases (Repo)	All (Maven 2)
      Intershop	Target Privilege Intershop Releases	Intershop (Repo)	All (Maven 2)
      Snapshots	Target Privilege Snapshots	Snapshots (Repo)	All (Maven 2)
      Central	Target Privilege Central	Central (Repo)	All (Maven 2)
      JCenter	Target Privilege JCenter	JCenter (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 ID	Name	Role/Privilege Management
      maven2-distributions-read	Role: Distributions (read)	Distributions - (read) Distributions - (view)
      maven2-components-read	Role: Components (read)	Components - (read) Components - (view)
      maven2-snapshots-read	Role: Snapshots (read)	Snapshots - (read) Snapshots - (view)
      maven2-central-read	Role: Central (read)	Central - (read) Central - (view)
      maven2-jcenter-read	Role: JCenter (read)	JCenter - (read) JCenter - (view)
      maven2-projectbuilds-full	Role: Projectbuilds (full)	Releases - (create) Releases - (delete) Releases - (read) Releases - (update) Releases - (view) Snapshots - (create) Snapshots - (delete) Snapshots - (read) Snapshots - (update) Snapshots - (view)
      maven2-ishrepo-full	Role: 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 ID	Name	Role/Privilege Management
      nexus-project-developer	Project Developer	Nexus 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 ID	Name	Role/Privilege Management
      nexus-project-deployment	Project 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 ID	Name	Role/Privilege Management
      nexus-intershop-deployment	Intershop Deployment User	Nexus 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.

         Property	Value
         User ID (Login)	corp_deployment
         Email	<admin account of this user>
         Status	Active
         Password	<password for all processes>
         Role Management	Intershop 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.

         Property	Value
         User ID (Login)	prj_deployment
         Email	<admin account of this user>
         Status	Active
         Password	<password for all processes>
         Role Management	Project 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.

       Property	Value
       User ID (Login)	<developer account login>
       Email	<email of the user>
       Status	Active
       Password	<password>
       Role Management	Project Developer

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

gradlew clean publish -PrepoUserName=corp_deployment -PrepoUserPasswd=<passwd>

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>

// 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.

systemProp.repoUserName = <developer account login>
systemProp.repoUserPasswd = <developer account password>

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.

Recipe: Create a Proxy Repository Chain

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 set up a proxy repository chain.

How can an administrator set up a second repository?

Solution

Prerequisites

See the following recipes:

• Recipe: Configure Artifact Repository Server
• Recipe: Create Sources From Intershop Templates
• Recipe: Set up CI Build for Corporate Artifacts

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.

   Name	ID	Repository Type	Remote Storage Location	Format	Remarks
   Intershop Repository on A	ishrepoproxy	Proxy	http[s]://<hostname of A>/nexus/content/repositories/releases	Maven2	Depending on the security configuration it is necessary to configure the authentication for the connection.
   Releases Repository on A	releasesproxy	Proxy	http[s]://< hostname of A>/nexus/content/repositories/ishrepo	Maven2

   "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:

   Name	ID	Repository Type	Format	Repository IDs
   Components	components	group	Maven2	Releases, 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: Set up CI Build for Corporate Artifacts.

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 set up an own CI environment. In this case you have to create more template sources and a setup of a CI server is necessary.