Related Documents
Document Properties
Kbid272L35
Last Modified03-Feb-2020
Added to KB17-Aug-2015
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • Gradle Tools
  • ICM 7.6
  • ICM 7.7

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

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.

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 (valid to Gradle Tools 2.7) 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 (valid to Gradle Tools 2.7).

For more detailed information about deploying Intershop 7 instances, please refer to Cookbook - Gradle Deployment Tools (7.4 CI - ICM 7.7).

The procedures described in the present guide are based on Intershop 7.6 in combination with Intershop Gradle Tools 2.7.

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 - Gradle Deployment Tools (7.4 CI - ICM 7.7) – The present cookbook describes how to use the component-oriented deployment based on Gradle (versions 1.0 to 2.11). This includes the deployment of Intershop 7 (Intershop 7.4 CI until Intershop Commerce Suite 7.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 (valid to Gradle Tools 2.7)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 RequirementsThis document lists all System Requirements Sheets for Intershop Commerce Suite version 7.6 or later.

    Also available is a guide that matches the Intershop Commerce Suite versions with the Intershop Gradle Tools versions.

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 Strenght in the JDK
  • ojdbc7.jar file
  • ucp.jar file
  • ons.jar file
  • Valid Intershop contract (Contract ID) and license.xml file for IS 7.6 or later
  • 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 (valid to Gradle Tools 2.7) 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 (valid to Gradle Tools 2.7) 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

  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
    Centralcentral

    http://<hostname:port>/nexus/content/repositories/central

    proxy for
    http://repo1.maven.org/maven2/
      Maven Central public repository
    Intershopishrepohttp://<Hostname:Port>/nexus/content/repositories/ishrepoproxy for
    https://repo.intershop.de/content/repositories/ <contract-id>
      contains all released Intershop artifacts
    Distributionsdistributions

    http://<hostname:port>/nexus/content/repositories/distributions

    hostedRelease

    Disable Redeploy

    for project Gradle distribution
    Gradlegradle

    http://<hostname:port>/nexus/content/repositories/gradle

    hostedRelease

    Disable Redeploy

    for project Gradle plugins
    Releasesreleases

    http://<hostname:port>/nexus/content/repositories/releases

    hostedRelease

    Disable Redeploy

    for corporate / project releases
    Snapshotssnapshots

    http://<hostname:port>/nexus/content/repositories/snapshots

    hostedSnapshotAllow Redeployfor all artifacts from snapshot builds
  6. Create a repository group.

    NameIDRepo TypeRepository Names
    ComponentscomponentsgroupIntershop, Releases, Gradle
    Maven allmavenallgroupJCenter, Central, Intershop

    The order of the repositories is important!

Note

Possible pitfall, when attempt 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 sureDiscovery 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).
    RepoCredentials
  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 CI Bootstrap

  1. As Deployment User: Download the latest CI Bootstrap via your browser into the Intershop proxy repository (ishrepo).

    Download URL
    http://<your-reposerver:port>/nexus/content/repositories/ishrepo/com/intershop/build/infrastructure/intershop-ci-setup-bootstrap/3.3.0/intershop-ci-setup-bootstrap-3.3.0.zip

    Doing so downloads the release to the previously defined proxy repository (ishrepo).

  2. Create a directory, e.g., ProjectHome.
  3. Unzip intershop-ci-setup-bootstrap-x.x.x.zip in a directory (<ProjectHome>).

10 Edit the build.gradle File of Intershop CI Bootstrap

  1. As Deployment User: Open <ProjectHome>/intershop-ci-setup-bootstrap/build.gradle.
  2. Adapt at least the following properties:
    1. Corporate names: Specify names that identify your company/department.
    2. Output directory: Specify a target directory for the sources to be generated in the propertysetupDirectory.

      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>'
    3. Project names: Specify names that identify your project.

      intershopProject {
      ...
              /**
               *  Technical name of the component set.
               *  This is used in the directory structure of generated sources.
               **/
              //TODO: Provide a name using only letters, numbers and underscores (no spaces or other special characters), e.g. 'corporateshopassembly'
              assemblyName = '<myCustomAssembly>'
              /**
               *  Technical name of the assembly.
               *  This is used in the directory structure of generated sources.
               **/
              //TODO: Provide a name using only letters, numbers and underscores (no spaces or other special characters), e.g. 'corporateshopset'
              componentSetName = '<myCustomComponentset>'
      }
      ...
    4. Repository base URL: Specify the repository base URL of your artifact repository server in the propertyrepoBaseURL.

      repository {
              /**
               * Base URL for all repositories on the repository server.
               */
              //TODO: Provide URL (e.g. http://127.0.0.1:8081/nexus/content)
              repoBaseURL = 'http://<NEXUS>:8081/nexus/content'
    5. Intershop Proxy Repository: Provide the URL to theishrepo repository (your proxy repository) on the marked line in thebuildscript section.

      buildscript {
      	repositories {
      		maven {
      			//TODO: Provide URL to Intershop Releases Group Repository, e.g. http://nexus:8081/nexus/content/groups/mavenall
      			url 'http://<NEXUS>:8081/nexus/content/groups/mavenall'
    6. Version: Specify the desired versions in the versions section. Please make sure, wildcards are not allowed in the version strings.

11 Run the Bootstrap

  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-ci-setup-bootstrap/ open a command line.
  3. Execute:

    gradlew intershopCISetupAll

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

12 Create the Corporate Artifacts

Note

Store All Artifacts to Version Control

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.
  1. As Deployment User: Go to <ProjectHome>/devops/gradle/corporate-distribution.
  2. Open a command line and execute:

    gradlew clean publish -PRepoUserLogin=admin -PRepoUserPasswd=admin123
  3. Go to <ProjectHome>/devops/gradle/corporate-plugins.
  4. Open a command line and execute:

    gradlew clean publish -PRepoUserLogin=admin -PRepoUserPasswd=admin123
  5. Copy Oracle jdbc.jar, ons.jar and ucp.jar to <ProjectHome>/projects/oracleDriver/p_oracle/3rd_oracle/staticfiles/cartridge/lib.
  6. Go to <ProjectHome>/projects/oracleDriver/p_oracle.

  7. Open a command line and execute:

    gradlew clean publish -I init.gradle -PRepoUserLogin=admin -PRepoUserPasswd=admin123

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 grownResponsive 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 theResponsive 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 (valid to Gradle Tools 2.7).

Long path names on Windows

On Windows certain tools have trouble dealing with path names longer than 255 characters. When in doubt, please use 7-Zip 15.12 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/1.0.1/zips/a_responsive-zip-src-1.0.1.zip
  2. Unzip and copy the component set contents to your project directory <ProjectHome>/projects/intershop-project /<myCustomComponentset>.
  3. Download a Responsive Starter Store assembly inspired-b2x.
    http://<your-reposerver:port>/nexus/content/repositories/ishrepo/com.intershop.public.source/inspired-b2x/1.0.1/zips/inspired-b2x-zip-src-1.0.1.zip
    Alternatively, you can also go for the B2C only Responsive Starter Store:
    http://<your-reposerver:port>/nexus/content/repositories/ishrepo/com.intershop.public.source/inspired-b2c/1.0.1/zips/inspired-b2c-zip-src-1.0.1.zip
  4. Unzip and copy the the assembly contents to your project directory <ProjectHome>/projects/intershop-project/ <myCustomAssembly>.
  5. component set: in <ProjectHome>/projects/intershop-project/<myCustomComponentset> adapt the following files (Following listings are ):
    1. settings.gradle

      <DIFF> settings.gradle
      // define root project name
      -rootProject.name = 'a_responsive'
      +rootProject.name = '<myCustomComponentset>'
    2. .project

      <DIFF> .project
      <projectDescription>
      -   <name>a_responsive</name>
      +   <name>%%myCustomComponentset%%</name>
    3. build.gradle
      1. Replace the com.intershop.responsive group with your projects component set group.
      2. Delete the repositories definition in thebuildscript{}-block. The repositories are set via your corporate distribution.

        <DIFF> build.gradle
        ...
        description 'Components Responsive Starter Store Applications'
        -group = 'com.intershop.responsive'
        +group = '<projects group>'
        
        subprojects {
        -   group = 'com.intershop.responsive'
        +   group = '<projects group>'
        ...
        buildscript {
        -   repositories {
        -       maven {
        -           url 'http://nexus/nexus/content/repositories/gradle-releases/'
        -       }
        -   }
        ...
        }
    4. Replace the version number with a version number that fits to your projects component set and change the Commerce Management version.

      <DIFF> gradle.properties
      # project settings
      -version=1.0.1
      +version=1.0.0
      -filter.com.intershop.assembly.commerce_management_b2x = 7.6.0.0
      +filter.com.intershop.assembly.commerce_management_b2x = 7.6.1.1
  6. Adapt demo cartridges according to your needs.

  7. assembly:in <ProjectHome>/projects/intershop-project/ <myCustomAssembly> adapt the following files:
    1. settings.gradle

      <DIFF> settings.gradle
      -rootProject.name= 'inspired-b2x'
      +rootProject.name= '<myCustomAssembly>'
    2. build.gradle
      1. Replace the com.intershop.responsive group with your projects group and the version number that fits to your project.
      2. Delete the repositories definition in the buildscript{} -block. The repositories are set via your corporate distribution.

        <DIFF> build.gradle
        -group = 'com.intershop.responsive'
        +group = '<projects group>'
        -version = '1.0.1'
        +version = '1.0.0'
         
        buildscript {
        -   repositories {
        -       maven {
        -           url 'http://nexus/nexus/content/repositories/gradle-releases/'
        -       }
        -   }
        ...
        }
        ...
        assembly {
            cartridges {
         
        -       include(*(storefrontCartridges.collect {"com.intershop.responsive:$it"}), in:[development, test, production])
        +       include(*(storefrontCartridges.collect {"<projects group>:$it"}), in:[development, test, production])
         
        -       include (*(initCartridges.collect {"com.intershop.responsive:$it"}), in: init)
        +       include (*(initCartridges.collect {"<projects group>:$it"}), in: init)
            }
        }
    3. gradle.properties – Replace the com.intershop.responsive group with your projects group, the component set name a_responsive with your projects component set name in the version number and change the Commerce Management version.

      <DIFF> gradle.properties
      # componentsets with the same live cycle
      -filter.com.intershop.responsive.a_responsive = 1.0.1%suffix%
      +filter.<projects group>.<myCustomComponentset> = 1.0.0%suffix%
      -filter.com.intershop.assembly.commerce_management_b2x = 7.6.0.0
      +filter.com.intershop.assembly.commerce_management_b2x = 7.6.1.1

      %suffix% – will be substituted with "-local", "-SNAPSHOT" or ".<BuildNo>" depending on the environment where it is built.

    For more detailed information please refer to Recipe: Create a New Assembly Inheriting From an Existing Assembly in the Cookbook - Gradle Assembly Tools (valid to 7.8).

14 Deploy a Server

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

  1. As Deployment User: From <ProjectHome>/projects/intershop-project /developer_home/ open a command line and execute:

    Windows
    gradle_environment.bat
    Linux
    source ./gradle_environment.sh
  2. Adapt the environment.properties
    1. create environment.properties.sample

      Linux
      cdAssembly
      sh ./gradlew
      cp environment.properties.sample environment.properties
      Windows
      cdAssembly
      gradlew
      copy environment.properties.sample environment.properties
    2. Adapt the environment.properties according to your OS, and define the database connection parameters and 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.

  3. Build and Deploy

    Windows
    cdSet
    gradlew useSetAsFilter publish
    cdAssembly
    gradlew dbinit build publish
    Linux
    cdSet
    sh ./gradlew useSetAsFilter publish
    cdAssembly
    sh ./gradlew dbinit build publish
  4. As administrator/with root privileges, 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.
  5. Start the application server.

Once you added source code via a component or component set to the assembly, you have to execute the build processes.

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