Related Documents
Document Properties
KbidH28462
Last Modified03-Feb-2020
Added to KB21-Sep-2017
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • Gradle Tools
  • ICM 7.9

Guide - Quick Project Setup (valid to Gradle Tools 2.11)

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

Note

The activities described in this document are intended to give a rough overview of the setup steps. The document helps to get a first impression about the functionalities of the Intershop platform and the "look and feel" when developing applications.

Be aware that this quick guide does neither describe the quickest solution for many developers, nor do the approaches mentioned here meet the requirements of a full-scale project setup.

To set up a development environment, please follow the Cookbook - Setup CI Infrastructure guide instead, which focuses on creating a reusable infrastructure for multiple developers.

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.

1.1 Glossary

TermDescription
NexusSonatype Nexus - an artifact repository server
GradleA build automation tool that builds upon the concepts of Apache Ant and Apache Maven

1.2 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 - 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 - This video tutorial shows how to prepare a local Nexus Artifact Repository server.
  • Video Tutorial - Simple Setup of a Development-System - This video tutorial shows how set up a development system.

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

3 Version Control

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

Intershop strongly recommends to store not only your source code but also all continuous integration infrastructure under version control.

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

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

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

Be aware that an appropriate user management is essential for collaboration and security.


Note

Make sure to apply restricted user credentials particularly when you intend to make one of the above mentioned systems or the repository server itself available via the internet.

Please refer to the documentation of the according system to get more information on how to do that.

6 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)
Intershop provides a script that helps to install and configure Nexus. See Intershop's GitHub repository for details.

7 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 NameRepo IDURLRepoRepo PolicyDeployment PolicyUsage
    JCenterjcenterhttp://<hostname:port>/nexus/content/repositories/jcenterproxy for
    https://jcenter.bintray.com/


    Bintrays public repository
    Centralcentralhttp://<hostname:port>/nexus/content/repositories/centralproxy for
    http://repo1.maven.org/maven2/


    Maven Central public repository
    Intershopishrepohttp://<Hostname:Port>/nexus/content/repositories/ishrepoproxy for
    https://repository.intershop.de/releases/


    Contains all released Intershop artifacts
    Distributionsdistributionshttp://<hostname:port>/nexus/content/repositories/distributionshostedReleaseDisable RedeployFor project Gradle distribution
    Releasesreleaseshttp://<hostname:port>/nexus/content/repositories/releaseshostedReleaseDisable RedeployFor corporate / project releases
    Snapshotssnapshotsttp://<hostname:port>/nexus/content/repositories/snapshotshostedSnapshotAllow RedeployFor 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.

    NameIDRepo TypeRepository Names
    ComponentscomponentsgroupIntershop, Releases, JCenter

Note

The order of the assigned repositories is very important.

  1. JCenter
  2. Intershop 
  3. Releases

Note

Possible pitfall, when attempting to access files via this proxy repository.

If the following message appears:
404 - Automatic routing filter rejected remote request for path /com/intershop/build/infrastructure/intershop-ci-setup-bootstrap/<version> /intershop-ci-setup-bootstrap-<version> .zip from M2Repository(id=ishrepo)

Apply the following workaround.

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


Make sure that the Intershop proxy repository (ishrepo) is configured with valid authentication credentials (username; password).

Get the credentials for your ishrepo on the Intershop Customer Support site.

  1. Go to Intershop Customer Support.
  2. Log In (1) with your customer support credentials.
  3. Switch to Your Contract (2).
  4. Select Repository (3).
    ishrepo_credentials

  5. Get (4) the required repository credentials.

8 Provide License

Note

You cannot start Intershop 7 without providing a valid license file.

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

Linux/opt/intershop/license
WindowsC:\intershop\license

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

9 Get the Intershop Template

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

    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.

10 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>'

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

12 Create the Corporate Artifacts

Before proceeding any further, Intershop strongly recommends to store all artifacts into a Version Control System.

Even the bootstrap may be subject to change. This means that you need to back up the artifacts created by the bootstrap in order to be able to exactly re-create the initial CI environment of your project.

This section only provides shortened working steps. For more detailed information please refer to the recipe Setup CI Build for Corporate Artifacts in the Cookbook - Setup CI Infrastructure.

  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>

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

This section only provides shortened working steps. For more detailed information please refer to the recipe Set Up Project Based on the Responsive Starter Store in the Cookbook - Setup CI Infrastructure.

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


Note

Newer versions of the responsive starter store

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

  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 TypeStorefront CartridgesDemo/Init CartridgesAssembly
    B2Capp_sf_responsive
    app_sf_responsive_cm
    app_sf_responsive_b2c
    app_sf_responsive_smb
    as_responsive
    demo_responsive
    demo_responsive_catalog
    demo_responsive_content
    demo_responsive_search
    demo_responsive_ocst
    inspired-b2c
    B2XB2C Storefront Cartridges + app_sf_responsive_b2b
    app_sf_responsive_costcenter
    as_responsive_b2b
    B2C Demo/Init Cartridges +
    demo_responsive_b2b
    inspired-b2x

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

  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.

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

Note

Once source code is added via a component or component set to the assembly, the build processes have to be executed.

Refer to Cookbook - Gradle Build Tools for more detailed information on how to do this.

Disclaimer

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

Customer Support
Knowledge Base
Product Resources
Support Tickets