Introduction

Intershop 7 (since IS 7.4 CI) is delivered with tools that can be used to build, assemble, upgrade, downgrade, deploy and undeploy software components.

The present document is intended as a quick start guide for consultants and developers for a quick project setup. The procedures described are based on Intershop 7.9 in combination with Intershop Gradle Tools 2.11.

For more detailed information to a complete CI Infrastructure, please refer to Cookbook - Setup CI Infrastructure.

For more detailed information about deploying Intershop 7 instances, please refer to Cookbook - Deployment Tools ICM 7.9.

Glossary

References

• Cookbook - Deployment Tools ICM 7.9 - The cookbook describes how to use the component-oriented deployment for the Intershop Commerce Management 7.9 based on Gradle 2.11.
• Concept - Gradle Deployment Tools - This concept describes how to use the component-oriented deployment based on Gradle. This includes the deployment of Intershop 7 and all custom solutions that are created with the Gradle-based build and assembly process.
• Concept - Continuous Delivery Tools (valid to 7.10) - Intershop 7 (since IS 7.4 CI) is delivered with tools, that can be used to build, assemble, upgrade, downgrade, deploy and undeploy software components. These tools are designed to implement very flexible continuous delivery processes. This document targets developers and administrators, who want to get an overview about the entire tool chain. It introduces the high level concept of these particular phases of the overall continuous software delivery process.
• Cookbook - Setup CI Infrastructure - This cookbook describes in full detail how to create the required CI infrastructure. This document 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.
• Overview - System Requirements - This document lists all System Requirements for Intershop Commerce Suite version 7.9
• Reference - CI Dependencies of Intershop Commerce Management - This document describes the connection between Intershop Commerce Management (ICM) releases and their according Intershop Gradle Tools releases.
• Video Tutorial - Simple Deployment of a Production System - This video tutorial shows a general approach to deploy a production server locally.
  
• Video Tutorial - Prepare Your Artifact Repository Server (valid to 7.10) - This video tutorial shows how to prepare a local Nexus Artifact Repository server.
  
• Video Tutorial - Simple Setup of a Development-System (valid to 7.10) - This video tutorial shows how set up a development system.
  

Preconditions

• Accessible database scheme
• Installed Oracle database client
• Installed 64-bit Oracle JDK 1.8 or higher and an environment variable JAVA_HOME pointing to this JDK installation.
• Installed Java Cryptography Extension (JCE) Unlimited Strength in the JDK
• ojdbc7.jar file
• ucp.jar file
• ons.jar file
• Valid Intershop contract (Contract ID) and license.xml
• A Deployment User for deployment and application start (must be the same)
  
  

Version Control

The present document does not mention any version control system. Nevertheless you should be aware of the advantages of version control systems.

The Cookbook - Setup CI Infrastructure outlines how to use Apache Subversion to achieve this.

Automation with CI Server

A CI server is perhaps not absolutely necessary to perform the tasks for your setup. However, build automation, automated deployment and self-testing builds are essential for a continuous integration strategy.

The more detailed Cookbook - Setup CI Infrastructure illustrates how to use Jenkins to achieve this.

User and Access Rights

This Quick Guide does not describe any user management neither for the artifact repository server nor for the version control system nor for a CI server.

Install Nexus

1. Download Sonatype Nexus (http://www.sonatype.org/downloads/nexus-latest-bundle.zip)
2. Install Sonatype Nexus (https://support.sonatype.com/forums/22202613-Getting-Started)

Configure Nexus

Once Nexus is installed properly the repositories have to be configured:

1. Start Sonatype Nexus.

2. Access Nexus (<yournexusserver>:8081).

3. Log in as administrator (user: admin password: admin123).

4. Select Repositories.

5. Create and/or configure the following repositories:

   Repo Name	Repo ID	URL	Repo	Repo Policy	Deployment Policy	Usage
   JCenter	jcenter	http://<hostname:port>/nexus/content/repositories/jcenter	proxy for https://jcenter.bintray.com/			Bintrays public repository
   Central	central	http://<hostname:port>/nexus/content/repositories/central	proxy for http://repo1.maven.org/maven2/			Maven Central public repository
   Intershop	ishrepo	http://<Hostname:Port>/nexus/content/repositories/ishrepo	proxy for https://repository.intershop.de/releases/			Contains all released Intershop artifacts
   Distributions	distributions	http://<hostname:port>/nexus/content/repositories/distributions	hosted	Release	Disable Redeploy	For project Gradle distribution
   Releases	releases	http://<hostname:port>/nexus/content/repositories/releases	hosted	Release	Disable Redeploy	For corporate / project releases
   Snapshots	snapshots	ttp://<hostname:port>/nexus/content/repositories/snapshots	hosted	Snapshot	Allow Redeploy	For all artifacts from snapshot builds

   For some repository server software it is recommended to store Maven and Ivy artifacts in different repositories. More information about this special kind of configuration can be found in the Cookbook - Setup CI Infrastructure.

6. Create a repository group.

   Name	ID	Repo Type	Repository Names
   Components	components	group	Intershop, Releases, JCenter, Central

Provide License

Plan the distribution of the license file, e.g., create a folder:

The Deployment User should have read-access to this location.

Get the Intershop Template

1. Download the latest version of the bootstrap package for the CI setup via your browser.

   Download URL: https://github.com/IntershopCommunicationsAG/intershop-cisetup-template/archive/master.zip

   Note

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

2. Unzip the contents or clone the Git repository to a directory of your choice, e.g., ProjectHome.

Edit build.gradle file of the Intershop CI-Setup Template

1. As Deployment User: Open <ProjectHome>/intershop-cisetup-template-master/build.gradle.
2. Adapt at least the following properties:

   1. Output directory: Specify a target directory for the sources to be generated in the property setupDirectory.

          directories {
              /**
               * Base directory for all generated sources.
               **/
              //TODO: Provide an absolute path, e.g., '/home/developer/intershop-ci/source' on Linux resp.'C:/developer/intershop-ci' on Windows
      
              setupDirectory = '<ProjectHome>'

   2. Corporate names: Specify names that identify your company/department.

      repository {
              /**
               * Technical enterprise or corporate name.
               * This is used for group/organization of generated artifacts in
               * the artifact repository.
               */
              //TODO: Provide a reverse domain name, e.g. 'com.corporate'
      
              corporateName = '<com.YourCompany>'

   3. Repository base URL: Specify the repository base URL of your artifact repository server in the property repoBaseURL.

      repository {     
      ...
              /**
               * Base URL for all repositories on the repository server.
               */
              //TODO: Provide URL (e.g. http://nexus:8081/nexus/content)
      
              repoBaseURL = 'http://<NEXUS>:8081/nexus/content'

   4. Project names: Specify names that identify your project.

      intershopProject {
              /**
               * Technical name of the project. This is also used for the name of the multi project,
               * that contains all components (cartridges) and the assembly build.
               **/
              //TODO: Provide a name using only letters, numbers and underscores (no spaces or other special characters), e.g. 'corporateshop'
      
              projectName = '<ProjectName>'

Execute the Intershop CI Setup

1. Ensure you have installed a valid JDK and set Java_Home correctly.

   You may encounter a build failure like this:

   Execution failed for task ':app_sf_foobar:compileJava'.

   > Could not find tools.jar

   In that case you most likely ran the build process with a JRE only, but compiling Java requires a JDK. Be sure to execute Gradle with the proper Java by pointing the environment variable JAVA_HOME to the location of your desired JDK installation.

   You may refer to How to Set Java Home, if you do not know how to achieve this.

2. As Deployment User: From <ProjectHome>/intershop-cisetup-template-master/ open a command line.

3. Execute:

   Windows

   gradlew intershopCISetupAll

   Linux

   ./gradlew intershopCISetupAll

   This initially creates all directories and files needed for your setup.

Create the Corporate Artifacts

1. As Deployment User: Go to <ProjectHome>/devops/gradle/corporate-distribution.

2. Open a command line and execute:

   Windows

   gradlew publish

   Linux

   ./gradlew publish

3. Copy Oracle jdbc7.jar, ons.jar and ucp.jar to  <ProjectHome>/projects/oracleDriver/3rd_oracle/build/oracleLibs/jars .

4. Go to <ProjectHome>/projects/oracleDriver/3rd_oracle.

5. Open a command line and execute:

   Windows

   gradlew publish -PrepoUserName=<deployment user> -PrepoUserPasswd=<deployment user password> -PreleaseURL=<URL for release publishing>

   Linux

   ./gradlew publish -PrepoUserName=<deployment user> -PrepoUserPasswd=<deployment user password> -PreleaseURL=<URL for release publishing>

Set Up the Responsive Starter Store

The standard assemblies of the Intershop Commerce Management Suite do not provide any storefront functionalities and/or content. Nevertheless Intershop provides a full grown Responsive Starter Store including the whole view layer with a responsive content model and demo content. This section describes how to integrate the source cartridges into your environment. This way the Responsive Starter Store is the perfect starting point for your development.

1. As Deployment User: Download the latest version of the Responsive Starter Store component set a_responsive.

   http://<your-reposerver:port>/nexus/content/repositories/ishrepo/com.intershop.public.source/a_responsive/<version>/zips/a_responsive-zip-src-<version>.zip

2. Unzip and copy the contents of the folder a_responsive to your project directory <ProjectHome>/projects/<ProjektName> / .

3. Within the folder <ProjectHome>/projects/<ProjektName> /gradle/wrapper open the file gradle-wrapper.properties  and adapt your distributionURL.

4. Adapt the following files within your project directory:

   <DIFF> settings.gradle

   // define root project name
   
   -	rootProject.name = 'a_responsive'
   +	rootProject.name = '<ProjectName>'

5. 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 = '<Projects Group>'
   
   subprojects {
   -   group = 'com.intershop.responsive'
   +   group = '<Projects Group>'

6.  Replace the version number with a version number fitting to your projects.
   
   1. Therefore the files .ivyIcm-b2c.version or .ivyIcm-b2x.version must be changed. Replace the version in these files with your own.

7. Physically remove not needed sub projects.

   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.

8. (optional) 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.

9. Delete the other assembly sub project folder, which is no longer needed.

10. Adapt build configuration for the used assembly.

    If a B2C assembly will be created:

    <DIFF> build.gradle

    -	def assemblyProjects = [ project(':inspired-b2c'), project(':inspired-b2x') ]
    +	def assemblyProjects = [ project(':inspired-b2c') ]

    If a B2X assembly will be created:

    <DIFF> build.gradle

    -	def assemblyProjects = [ project(':inspired-b2c'), project(':inspired-b2x') ]
    +	def assemblyProjects = [ project(':inspired-b2x') ]

    If you've renamed your assembly sub project then use the name instead

    
    

    <DIFF> build.gradle

    -	def assemblyProjects = [ project(':inspired-b2c'), project(':inspired-b2x') ]
    +	def assemblyProjects = [ project(':<YourAssemblyName>') ]

11. As Deployment User: Open a command line from <ProjectHome>/projects/ <ProjektName> / .

12. Execute the following command, in order to create the Deployment Configuration:

    Windows

    gradlew

    Linux

    ./gradlew

    Note

    The first call of gradelw in the project will generate a sample file for the deployment configuration ('<PROJECT><assembly name>/target/samples/environment.properties.sample'). But this will only happen if:

    1. No file environment.properties does exist in the assembly project directory.
    2. No project property <project name>BuildEnvironmentProperties is specified or the file, specified for this property, does not exist.
    3. No project property buildEnvironmentProperties is specified or the file, specified for this property, does not exist.

    If no sample file is generated please check the location of the assembly project, the environment settings and the file gradle.properties in your GRADLE_USER_HOME for some of this configuration properties.

For more detailed information please refer to the recipe Set Up Project Based on the Responsive Starter Store in the Cookbook - Setup CI Infrastructure.

Deploy a Server

These steps deploy the server from the current assembly build process.

1. Navigate to <ProjectHome>/projects/ <ProjektName> / <YourAssembly>/target/samples and copy the file environment.properties.sample to <ProjectHome>/projects/ <ProjektName> / <YourAssembly>
2. Rename the file environment.properties.sample to environment.properties

3. Adapt the environment.properties according to your OS, and define the database connection parameters, used ports and interfaces.

   Note

   Using Linux OS make sure you configure separate multicast ports for each messaging channel.

   Some older Linux distributions have an issue with multicast configurations on the same port and different IPs.

4. As Deployment User: Open a command line from <ProjectHome>/projects/ <ProjektName> / and execute:

   Windows

   gradle_environment.bat

   Linux

   ./gradle_environment.sh

5. Build and deploy.

   Windows

   gradlew deployServer

   Linux

   sh ./gradlew deployServer

6. Navigate to your server directory <ProjectHome>/projects/<ProjektName>/build/server/local/tools/dbinit/bin

7. As administrator / with root privileges open a command line and execute:

   Windows

   dbsetup.bat

   Linux

   ./dbsetup.sh

   More information about the automated, script-based setup can be found at the following link:

   Guide - Setup Oracle XE as Intershop Development Database

8. As Deployment User: Open a command line from <ProjectHome>/projects/ <ProjektName> / and execute:

   Windows

   gradlew dbinit

   Linux

   ./gradlew dbinit

9. As administrator/with root privileges: Open a command line from <ProjectHome>/projects/ <ProjektName> / build/server/postInstall and execute the post-install script:

   ------------------------------------------------------------------------------------
   To finish the deployment please execute the following scripts as administrator /
   with root privileges:
   /folder/postInstall/installServices.sh
   ------------------------------------------------------------------------------------
   
   

   Use installServices.bat if using Windows OS.

10. Start the application server.