Introduction

This cookbook gives more in-depth knowledge to some selected deployment topics, including:

• Preparation and configuration of the deployment of your own assembly in a production environment
• Customizing and adding what gets deployed
• Application of content filters

It is in the nature of Gradle that the lines between configuration and extension, administration and development blur. That is why this cookbook addresses administrators and developers and concerns development and deployment time.

The cookbook is mostly self-contained. Knowledge of the Concept - Gradle Deployment Tools is not required to follow the recipes, but helpful for a deeper understanding and straying off the predefined course.

Glossary

References

• Concept - Continuous Delivery Tools (valid to 7.10)
• Concept - Gradle Deployment Tools

Recipe: Prepare the Deployment

Problem

Before executing a deployment the host and its environment must be prepared.

Solution

Prerequisites for executing a deployment are:

1. Meet the Software Requirements.
2. Install a Gradle distribution or a Gradle wrapper.
3. Make repositories that contain the assembly, all contained components and deployment plugins accessible to the host.
4. Configure the location of the Gradle user home directory.
5. Configure the deployment in a local deployment script settings.gradle (what to deploy in which version, host type, where to deploy, ports etc).

Discussion

Deployment for Developers

Developers can use a deployment that is triggered inside the assembly process and that requires only a simple properties file for configuration.

For more information, refer to the corresponding Gradle Developer Workflow cookbook:  

• Cookbook - Gradle Developer Workflow
• Cookbook - Gradle Developer Workflow (valid to Gradle Tools 2.7)

Gradle Distribution and Wrapper

You may use a standard Gradle distribution available from http://www.gradle.org, download it and extract it. 

You may also use a project Gradle distribution, as created through the corresponding Setup CI Infrastructure cookbook in your artifact repository. This has the advantage that the repositories are preconfigured automatically.

You may either download the Gradle distribution manually or use a Gradle wrapper - a small Java program that will download Gradle, extract it and run it automatically. It is recommended to store and retrieve the Gradle wrapper from a VCS.

See also the corresponding Gradle user guide on the Gradle Wrapper:

• Gradle Wrapper (2.11)
• Gradle Wrapper (2.7)
• Gradle Wrapper (2.3)
• Gradle Wrapper (2.1)
• Gradle Wrapper (1.8)

The corresponding Setup CI Infrastructure cookbook helps you to create a wrapper:

• Cookbook - Setup CI Infrastructure
• Cookbook - Setup CI Infrastructure (valid to Gradle Tools 2.7)
• Cookbook - Setup CI Infrastructure (valid to Gradle Tools 2.3)
• Cookbook - Setup CI Infrastructure (valid to GradleTools 2.1)
• Cookbook - Setup CI Infrastructure (valid to GradleTools 1.1)

Make Repositories Accessible

The deployment copies files to deploy from an artifact repository. The repository is filled by a build process/copying pre-built components from other repositories. Two main types of repositories are

• File system based repository, e.g., a local or mounted folder,
• An URL based repository like a file server or dedicated artifact repository (like e.g., Sonatype Nexus, Artifactory)

Making them accessible may thus mean to mount an NFS or a DVD or opening firewalls. To tell Gradle where the repositories can be found refer to the Recipe: Configure the Deployment.

Configure Location of Gradle User Home

Gradle stores caches and configurations in a folder called Gradle user home. When using a remote repository (i.e., URL, not file system based), this can become quite large. The default location at <OS user home>/.gradle may not be the best place in this case. Reconfigure the location by setting the environment variable GRADLE_USER_HOME.

Configure the Deployment

Gradle itself is a general purpose automation tool. The central file telling Gradle what to automate is the Gradle settings file, typically called settings.gradle.

For the deployment it contains:

• Logic telling Gradle to execute an Intershop deployment, by including the deployment-bootstrap plugin.
• Which assembly to deploy
• Where to deploy it
• How to configure host names, ports, permissions etc.
• Custom deployment logic
• Inclusion of other deployment scripts/configuration files

See Recipe: Configure the Deployment for details about the contents of this file.

Also see the Concept - Gradle Deployment Tools and the corresponding Gradle user guide on Multi-project Builds (2.11, 2.7, 2.3, 2.1, 1.8).

The settings file can be stored anywhere in the local file system, except any folder which is processed by the deployment. We recommend to put it into the parent folder of your deployment (if you deploy into a single directory). If the local deployment script is called settings.gradle and located in the current working directory or any parent directory Gradle will automatically find it. If you differ from naming or location, you have to pass in the Gradle command line option -c, --settings-file , upon every execution, see the corresponding Gradle user guide on command line usage (2.11, 2.7, 2.3, 2.1, 1.8).

We recommend to store the settings.gradle in a VCS or use a configuration management tool to generate/distribute it.

Executing Gradle

To execute the deployment run the Gradle command (gradlew for invocation through the wrapper or gradle for direct invocation) in the directory of the settings file and pass a Gradle task to execute. Available tasks can be displayed by:

Prerequisites of the Deployed Application

When deploying an Intershop 7 based solution additional system prerequisites must be met - like an installed Oracle client and a prepared database.

Recipe: Configure the Deployment

Problem

Before executing a deployment must be configured in the settings.gradle file.

Solution

To configure your deployment create a settings.gradle file, containing the following information:

• Repositories
• Which assembly to deploy in which version
• Which host type and environment to select
• Java directory
• Share and local directories
• Appserver instances
• Database account
• License file
• Appserver instance ID
• Platform ID
• Ports for Web Adapter
• Ports and network interface for application server (Nodemanager)
• User name and group

The general structure of a settings.gradle for deployment is:

buildscript {
    gradle.injectRepositories(repositories, configurations)
    dependencies {
        classpath 'com.intershop:deployment-bootstrap:<version>'
    }
}
 
apply plugin: com.intershop.deploy.bootstrap.DeploymentBootstrapPlugin
 
deploymentBootstrap {
    gradle.injectRepositories(repositoryHandler, configurationContainer)
 
    // assembly block
	assembly ('<assembly organization>:<assembly name>:<assembly version>') {
	    hostType {
    	    environment '<environment>'
    	    hostType '<host type>'
	    }
	}
 
    // config block
	config {
	    <config DSL block>
	}
}

Discussion

Repository Configuration

The deployment requires repositories to resolve the assembly, all components to deploy and the deployment plugins from. The settings.gradle template above assumes, that

• The repository configuration is provided as an extension property injectRepositories on the global  gradle object.
• This property is set to a closure that takes a RepositoryHandler and a ConfigurationContainer
• The closure adds repositories to the passed in RepositoryHandler and may optionally control details of the dependency resolution process on the ConfigurationContainer object

This closure is best provided in a Gradle init script. The Project Gradle Plugin created with Cookbook - Setup CI Infrastructure (valid to GradleTools 1.1) already provides this closure. Using a Project Gradle Distribution (directly or through a Gradle wrapper) will therefore automatically declare the repositories.

You may also declare them manually in a Gradle init script as shown in the following example:

gradle.ext.injectRepositories = { RepositoryHandler repositories, ConfigurationContainer configurations -> 
    repositories.with {
        // Declare repositories using Gradle's repository DSL
        maven {
            url "http://repo.mycompany.com/maven2"
        }

        ivy {
            url "http://repo.mycompany.com/repo"
            layout "pattern", {
                artifact "[module]/[revision]/[type]/[artifact].[ext]"
            }
        }
    }
}

See Gradle user guide on Dependency Management or Gradle DSL documentation on RepositoryHandler for details on how to declare repositories.

Assembly hostType DSL Block

The deployment must know which assembly to deploy. Also it must determine - very early in deployment - which components to create as projects (see Concept - Gradle Deployment Tools), based on host type and environment to deploy. See Concept - Continuous Delivery Tools (valid to 7.10) (in the sections Assembly Subsset Host Type and Assembly Subset Environment) and Concept - Gradle Assembly Tools for a general definition of what a host type and an environment is and which ones are available by default.

Config DSL Block

The config block configures the root level Gradle project during deployment, which represents the assembly. It contains most significant deployment configurations. It is segmented into sub-blocks.

The following tables gives an overview about sub-blocks of the config block and their properties. The last three columns show for which host-types they are required.

Configuration	Structure	Description	Example	appserver	share	webserver
Java directory	target.javaHome = File	Specify the JDK which should be used in scripts, e.g. to execute the server-startup. (DEFAULT) By default this Value is set to the Java which executes the Gradle-Process. JDK lookup mechanism: Gradle tries to find a JDK installation, if the Gradle-Process is executed via a JRE based in a JDK's directory. E.g.: Gradle-Process Java is /path/to/jdk/jre/bin/java The lookup sets the Java-Path for the deployment to /path/to/jdk If the parent directory is not identified as JDK directory, the Deployment fails. The mechanism doesn't work, if target.javaHome is configured. In this case target.javaHome must point to a valid JDK directory with jre directory inside.	target {        javaHome =  new File( '/path/to/jdk' )        // must reference to a jdk directore (see below) } /* [/ or C:\] |-- path      |-- to          |-- jdk              |-- bin              |   |-- .java (linux)              |   |-- .java.exe (windows)              |-- jre                      |-- bin                              |-- .java (linux)                              |-- .java.exe (windows) */
Share directory	target.shareDirectory = File	Specify the share directory to deploy to (IS_SHARE). IS_SHARE may not be the same directory as your settingsDir	target { shareDirectory = new File(settingsDir, 'share') }
Local directory	target.localDirectory = File	Specify the local directory (IS_HOME) IS_HOME may not be the same directory as your settingsDir	target { localDirectory = new File(settingsDir, 'local') }
Application server settings	appserver { hostname = 'Host' nodemanagerNetworkInterface = 'Address' nodemanagerJmxPort = Port }	Configuration relevant for all appservers of the installation. The nodemanagerNetworkInterface defaults to 127.0.0.1. The hostname defaults to localhost for single-machine installations.	appserver { hostname = 'myhost.domain.invalid' nodemanagerJmxPort = 10055 }
Appserver instances	appserver { instances { appserver[n] { tomcatShutdownPort = Port1 tomcatHttpPort = Port2 tomcatHttpsPort = Port3 appserverPort = Port4 serverGroups = ['GROUP1', 'GROUP2'] } } }	Specify the appserver instances. For each instance add a block for the application server. The ports must be unique and unused on the target system. Even, if not required, stay with the naming schema 'appserver0', 'appserver1', etc. Server groups are optional and default to ['WFS', ' BOS', ' JOB']. Appserver-specific configuration is stored in IS_HOME/config per default, but can be configured via appserver.configPath.	appserver { instances { appserver0 { tomcatShutdownPort = 10050 tomcatHttpPort = 10051 tomcatHttpsPort = 10052 appserverPort = 10053 } appserver1 { tomcatShutdownPort = 10060 tomcatHttpPort = 10061 tomcatHttpsPort = 10062 appserverPort = 10063 serverGroups = ['BOS'] } } }
Database account (Gradle Tools ≤ 1.1)	database { host = '<FILL IN>' port = <FILL IN> sid = '<FILL IN>' tnsAlias = '<FILL IN>' user = '<FILL IN>' password = '<FILL IN>' oracleClientDir = new File('<FILL IN>') }	Specificy the database settings.	database { host = 'localhost' port = 1521 sid = 'ISORCL1' tnsAlias = 'ISSERVER.world' user = 'dbuser' password = 'dbpassword' oracleClientDir = new File('C:/path/to/oracle/client/dir') }
Database account (Gradle Tools ≥ 2.0)	database { host = '<FILL IN>' port = <FILL IN> serviceName = '<FILL IN>' tnsAlias = '<FILL IN>' user = '<FILL IN>' password = '<FILL IN>' oracleClientDir = new File('<FILL IN>') }	Specificy the database settings. SID-based configuration is deprecated, prefer to use service name to designate the database instance.	database { host = 'localhost' port = 1521 serviceName = 'ISORCL1.world' tnsAlias = 'ISSERVER.world' user = 'dbuser' password = 'dbpassword' oracleClientDir = new File('C:/path/to/oracle/client/dir') }
License file	license.licenseFile = File	Specify the path to your license file. The file must be available at your target system.	license { licenseFile = new File('C:/path/to/license.xml') }
Instance ID	target.instanceId = '<FILL IN>'	Specify the ID of your instance. The ID must be unique on your target system.	target.instanceId = '9'
Platform ID	target.platform = '<FILL IN>'	Specify the ID of your platform. Supported values are: linux.rhel.x86_64 linux.sles.x86_64 win.x86_64	target { platform = 'linux.rhel.x86_64' }
Web Adapter settings	webadapter { hostname = '<FILL IN>' port = PORT1 securePort = PORT2  sharedMemoryKey = '<FILL IN>' configurationServices = ['SVC1', 'SVC2']     serverGroups = ['WFS', 'BOS', 'JOB'] }	Specify the settings for running the Web Adapter. configurationServices is a list of hosts (format: hostname:port), whose configuration servlets will be used by the Web Adapter. For single-machine deployments (Host type: all) this value is optional and defaults to 'localhost:$appserverPort' for each locally configured appserver instance. serverGroups (since Gradle Tools ≥ 2.0) configures all the server groups known to the Web Adapter. For single-machine deployments (Host type: all) this value defaults to the union of all appservers' server groups, for other host types it defaults to ['WFS', 'BOS', 'JOB'].	webadapter { hostname = 'localhost' port = 80 securePort = 443 sharedMemoryKey = '0x2001' configurationServices = ['localhost:10053'] }
Web Adapter settings (for share only)	webadapter { hostname = '<FILL IN>' port = PORT1 securePort = PORT2 serverGroups = ['WFS', 'BOS', 'JOB'] }	Specify the settings how to generate public URLs directed at a Web Adapter (or load balancer). serverGroups exists since Gradle Tools ≥ 2.0.	webadapter { hostname = 'customer.de' port = 80 securePort = 443     serverGroups = ['WFS', 'BOS', 'JOB', 'STG'] }
External SSL box configuration (Gradle Tools ≥ 2.0)	webadapter { useSSLBox = true|false sslBoxSecuredPort = PORT3 }	Specifies whether or not an external SSL box is being used, and which port the Web Adapter should listen to for secured connections .useSSLBox defaults to false.	webadapter { useSSLBox = true sslBoxSecuredPort = 8443 }
Multicast settings (until Gradle Tools 1.0)	multicast { appserverMulticastAddress = '<FILL IN>' appserverMulticastPort = PORT1 appserverMulticastInterface = '<FILL IN>' tcmMulticastAddress = '<FILL IN>' tcmMulticastPort = PORT2 tcmMulticastInterface = '<FILL IN>' cacheMulticastAddress = '<FILL IN>' cacheMulticastPort = PORT3 cacheMulticastInterface = '<FILL IN>' }	Specify the multicast addresses, ports and (optionally) interfaces to bind to.	multicast { appserverMulticastAddress = '239.192.12.34'     appserverMulticastPort      = 50000     appserverMulticastInterface = '127.0.0.1' tcmMulticastAddress = '239.192.12.34' tcmMulticastPort = 50001     tcmMulticastInterface       = '127.0.0.1' cacheMulticastAddress = '239.192.12.34' cacheMulticastPort = 50002     cacheMulticastInterface   = '127.0.0.1' }
Multicast settings (Gradle Tools ≥ 1.1, for share only)	multicast { appserver {      address = '<IP adress>'      port = <port> } tcm {      address = '<IP address>'      port = <port> } cache {      address = '<IP address>'      port = <port> } orm { address = '<IP address>' port = <port> } }	Specify the multicast addresses and ports. This part of the multicast configuration applies cluster-wide.	multicast { appserver {      address = '239.192.12.34'      port = 50000 } tcm {      address = '239.192.12.34'      port = 50001 } cache {      address = '239.192.12.34'      port = 50002 } orm { address = '239.192.12.34' port = 50003 } }
Multicast settings (Gradle Tools ≥ 1.1, for appserver only)	multicast { all {      networkInterface = '<IP adress>' } }	Specify the network interface to bind multicast connections to. This part of the multicast configuration applies to the deployed appserver only.	multicast { all {      networkInterface = '192.168.0.1' } }
AWS (Amazon Web Service) messaging settings (Gradle Tools ≥ 2.1)	aws { appserver {      topicName = '<topic name>'      region = '<region>' credentialsProvider = '<credentials provider, optional>' receiveMessageWaitTime = <wait time (seconds), optional> sendAsync = <send asynchronously, optional> } tcm { topicName = '<topic name>'      region = '<region>' credentialsProvider = '<credentials provider, optional>' receiveMessageWaitTime = <wait time (seconds), optional> sendAsync = <send asynchronously, optional>  } cache {  topicName = '<topic name>'      region = '<region>' credentialsProvider = '<credentials provider, optional>' receiveMessageWaitTime = <wait time (seconds), optional> sendAsync = <send asynchronously, optional>  } orm { topicName = '<topic name>'      region = '<region>' credentialsProvider = '<credentials provider, optional>' receiveMessageWaitTime = <wait time (seconds), optional> sendAsync = <send asynchronously, optional> } all { topicName = '<topic name>'      region = '<region>' credentialsProvider = '<credentials provider, optional>' receiveMessageWaitTime = <wait time (seconds), optional> sendAsync = <send asynchronously, optional> } }	Specify cluster-wide AWS messaging settings for each messenger channel. The all block can be used to specify common messenger settings.	aws {   all { region = 'eu-west-1' } appserver {      topicName = 'appserver-event' } tcm { topicName = 'tcm-event' } cache {  topicName = 'cache-event' } orm { topicName = 'orm-event' } }
User settings	assemblyDeployment.user = '<FILL IN>' assemblyDeployment.userGroup = '<FILL IN>'	Specify the user to run the deployed application with. The user will not be created during setup. Your need to create it before the deployment starts. You have to execute the deployment with this user.	assemblyDeployment { user = 'iwas1' userGroup = 'iwas1' }
Solr search service (Gradle Tools ≥ 2.0)	solr { server 'http://<HOST>:<PORT>' contextPath '/path'    clusterNodes 'http://<HOST1>:<PORT2>', ... }	Configures the Solr search service in IS7. contextPath is optional, in which case the default value /solr will be used.	solr { server 'http://localhost:8085'    clusterNodes 'http://localhost:8085', 'http://localhost:8086' }		( for Solr)
Tomcat servlet container (Gradle Tools ≥ 2.0)	tomcat { instances { instanceName { port = <HTTPPORT> securePort = <HTTPSPORT> shutdownPort = <SHUTDOWNPORT> } } }	Configures tomcat servlet container instances. Each instance is extensible and may be marked for specific use cases, e.g. Solr search server configuration below.	tomcat { instances { server0 { port = 80 securePort = 443 shutdownPort = 9001 } } }
Java VM settings (Gradle Tools ≥ 2.0)	tomcat { instances { instanceName { jvmArgs { minHeapSize = <SIZE> maxHeapSize = <SIZE>  additionalJvmArgs = ['ARG1', 'ARG2'] } } } }	Configures the Java VM used to start the servlet container instances. Allows configuration of memory settings (in MB) and directly passing in additional arguments. In case of additionalJvmArgs containing a equal sign, use unicode-encoded double quotes	tomcat { instances { instanceName { [...] jvmArgs { maxHeapSize = 1024  additionalJvmArgs = ['\\u0022-XX:MaxPermSize=256m\\u0022'] } } } }
Solr search server (Gradle Tools ≥ 2.0)	tomcat { instances { instanceName { ext.solr = true } } }	Configures which Tomcat instances will act as Solr search servers. Required for hosts of host type solr.	tomcat { instances { solr0 { port = 10080 securePort = 10081 shutdownPort = 10082 ext.solr = true } } }

Config DSL Block for Service Discovery (Gradle Tool ≥ 2.11)

Within ICM 7.8 the microservices were introduced. These and other ICM components (application server, the solr server, web adapter agent) may register at a eureka server. This enables the micro-services to find the appserver (and vice versa) and a recurring order can be triggered.

The following table is valid from IS 7.8.0.1 and shows which extensions need to be added and configured for the different host types:

Configuration	Extension	Description	Example	hostType share	hostType webserver	hostType solr	hostType discoveryserver	hostType microservices
local eureka server deployment	eureka	Provides the possiblity to install a local eureka server.	eureka {     serverHostName = '127.0.0.1'     serverPort = '12345'     serverUrlPath = 'eureka/' }
eureka registration url	eureka	The url, which clients use to register at eureka	eureka {     serviceUrls.default = 'http://127.0.01:12345/eureka/' }
serviceAppName	appserver	The name the application server is using to register at eureka.	appserver{     serviceAppName = 'appServerName'    }
serviceAppName	solr	The name the solr server is using to register at eureka.	solr{     serviceAppName = 'solrServerName'    }
microservices: general configuration	microservices	The configuration of the microservices. It contains information about the database connection, the port the microservices are running and the name the microservices are using to register at eureka	microservices {     port = '<MY_PORT>'     name = 'microserviceName'     instanceId= 'microserviceInstanceId'                   configProperties['javax.persistence.jdbc.url']  = '<CONNECTION_URL_DATABASE>'     configProperties['javax.persistence.jdbc.user']  = '<DATABASE_USER>'     configProperties['javax.persistence.jdbc.password']  = '<DATABASE_PASSWORD>'
mircroservice: naming mapping	microservices	It contains information about the names of the microservices.	configProperties['intershop.naming.service.RecurringOrder'] = 'microserviceName'     configProperties['intershop.naming.service.Scheduling'] = 'microserviceName' }

For further information, please see the following recipes:

• Recipe: Deploy a Local Eureka Server
• Recipe: Register ICM at Eureka
• Recipe: Microservice Deployment

Recipe: Configure Cartridge Location

Problem

I do not want to deploy cartridges into the shared directory. How can I deploy cartridges to a custom location?

Solution

You can change the location where cartridges are deployed, e.g., into the IS_HOME directory.

Moving the cartridge location across host types (e.g., from share to appserver) is not a deployment configuration, but requires modification of host types during the build of your assembly, see Concept - Gradle Assembly Tools.

Discussion

Default Locations

In your Assembly's build.gradle file the includeCartridges flag of a host type controls, whether cartridges will be deployed for this particular host type. By default, this flag will only be true for host type share (and therefore also for all).

To move cartridges from IS_SHARE to IS_HOME, you need to

• Set includeCartridges=true for host type appserver
• Set includeCartridges=false for host type share

This will

• for IS_HOME
  
  • Deploy cartridges (including the cartridgelist) into IS_HOME/cartridges
  • Configure the cartridge location inside intershop.properties
• for IS_SHARE
  
  • Not deploy cartridges into IS_SHARE/system/cartridges
  • Still deploy the cartridge's share artifacts (like static content of the sites folder) into IS_SHARE
  • Configure the cartridgelist location inside the configuration.xml

Custom Cartridge Location

If you do not want your cartridges to reside in either IS_SHARE/system/cartridges or IS_HOME/cartridges, you can specify a custom cartridge location inside your deployment's settings.gradle script. You still need to adjust the host type's flags according to the previous section.

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

target {
    cartridgesPath = '$PLACEHOLDER/relative/path/to/cartridges'
}

In case the cartridges are going to reside on

• The same host type, that is to be deployed (e.g., deployment of host type "appserver" with cartridges in IS_HOME/custom/cartridgeLocation), the placeholder will be resolved as follows:
  • ${IS_HOME} will become target.localDirectory
  • ${IS_SHARE} will become target.shareDirectory
  • Other placeholders will not be handled.
• A different host type, than the one being deployed (e.g., deployment of host type "share" with cartridges in IS_HOME/custom/cartridgeLocation), the placeholder is used as reference to the foreign location.

Recipe: Configure Cartridge Location via settings.gradle

Problem

There is an own settings.gradle for each host type. According to an already created ivy.xml the cartridges are deployed to the <IS_SHARE> directory, but we want the cartridges within <IS_HOME>.

Solution

1. Remove the cartridges from share.
   Add includeCartridges = false to the target extension of the settings.gradle for host type share.
2. Add the cartridge to local.
   Add hostType.includeCartridges = false to the host type extension of the settings.gradle for host type appserver.

Discussion

The ivy.xml, which the deployment is based on, shows the cartridges that should be deployed for host type 'share', which means they are deployed into <IS_SHARE>:

...
    <e:hostType name="appserver" includeCartridges="false" includeShare="false" includeLocal="true" includeJavadoc="false"/>
    <e:hostType name="share" includeCartridges="true" includeShare="true" includeLocal="false" includeJavadoc="false"/>
...

To adapt the deployment locations to <IS_HOME>, the settings.gradle of the host type 'share' and 'appserver' need to be adapted:

        hostType {
            hostType 'appserver'
			hostType.includeCartridges = true
        }

        target {
            includeCartridges = false
        }

Recipe: Configure Encryption

Since Gradle tools Version >= 2.0.

Problem

Intershop 7 can encrypt sensitive database content. To decrypt data the same algorithm and key has to be used like for encryption.

Also it must be possible to use a different algorithm/key starting with a certain point in time to increase security.

Solution

Encryption is configured in three files:

1. A properties file containing a list of encryption configurations (default name: encryption.properties). Each has an ID, an algorithm to use for generating a key and encryption.
2. A keystore file containing a key for each encryption configuration (default name: intershop.keystore).
3. A random file containing a fixed number of random bytes (default name: random).

One of the encryption configurations in the properties file is marked as default configuration. It is used for all encryption processes. Other encryption configurations are used to decrypt data that was encrypted when that configuration was default.

The keystore is protected against unwanted reading and writing by a password. The password is calculated from several different pieces of data. One of them is contained in the properties file, another is the content of the random file.

These three files are provided as input files to the deployment. Like other deployment input files, they become part of the desired state and should be kept under management of an external tool (like a VCS) to be able to restore them on machine failure. Encryption configuration is not modified, but only read by the application (Intershop 7).

Configuring encryption consists of two parts:

1. Create and modify encryption configuration files. This includes specification of algorithms to use, renewal of keys and keystore password. Encryption configuration can be created/modified during or before the deployment (like in a standalone Gradle script).
2. Deploy encryption configuration files to the shared file system of Intershop 7.

See discussion for details.

Discussion

Create Or Modify Encryption Configuration

The tasks described in the following sections are provided by the EncryptionAdminPlugin.

They can be executed using a settings.gradle for deployment. Also, you can run them from a standalone Gradle script, applying the EncryptionAdminPlugin:

buildscript {
    dependencies {
        classpath 'com.intershop:deployment-bootstrap:+'
    }
}

apply plugin: com.intershop.deploy.encryption.EncryptionAdminPlugin
                
encryption {
    propertiesFile = file('encryption.properties')
    keystoreFile = file('intershop.keystore')
    randomFile = file('random')
    algorithm = 'PBEWithMD5AndTripleDES'
}

The above example stores/loads the encryption configuration files in the same folder as the build.gradle file. You may specify a different location by setting propertiesFile, keystoreFile and randomFile to different Java File objects, e.g., propertiesFile = new File('/home/is7admin/encryption.properties').

When executing the tasks during deployment, the files are by default expected in the same folder as the settings.gradle file, see section "Deploy Encryption Configuration" below.

The algorithm property in the encryption block specifies both,

1. which encryption algorithm to use to generate a key from a password and
2. encrypt plain text with.

It must be of the form PBEWith<digest>And<encryption>, see Standard Algorithm Name Documentation for JDK 8 or JDK 7, depending on your version.

Create Encryption Configuration

To create the encryption configuration files initially, including a new encryption configuration and key, run the Gradle task generateEncryptionConfig. This task is called automatically as part of the normal deployment.

The generateEncryptionConfig task is idempotent:

• It creates encryption configuration files if they are missing in the specified location.
• It adds a new encryption configuration, if the current default encryption configuration uses a different algorithm than the one specified in the algorithm property.
• Otherwise it leaves encryption configuration files untouched.

This ensures that after running this task there is always a valid encryption configuration using the specified algorithm, but existing database content can still be decrypted.

Change Algorithm

To use a different encryption/key generation algorithm in future, simply:

1. Change the algorithm property
2. Run the generateEncryptionConfig task

Generate New Key

To generate a new key, even with the same algorithm as the current default configuration, run the Gradle task newKey.

Generate New Password for Keystore

To generate a new random password for the keystore, run the Gradle task newPassword. This changes the random file, the password data in the properties file and rewrites the keystore file using the new password.

Deploy Encryption Configuration Files

Encryption configuration files are deployed using the EncryptionDeploymentPlugin, applied by default. You may specify:

1. Where the encryption configuration files reside before the deployment. By default this is the directory of the settings.gradle file using the default file names given above.
2. Where the encryption configuration files should be deployed to. By default this is in <IS_SHARE>/system/config/cluster using the default file names given above. The files must be deployed to a folder in IS_SHARE and the location is specified as relative path to that.

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

encryption {
    // Paths to the configuration files to deploy from
	// TODO: Adapt paths or remove if the defaults suffice
	propertiesFile = new File('/opt/install/encryption.properties')
    keystoreFile = new File('/opt/install/intershop.keystore')
    randomFile = new File('/opt/install/random')

	// Paths relative to IS_SHARE, that the files should be deployed to
	// TODO: Adapt paths or remove if the defaults suffice
    propertiesTargetPath = 'system/encryption/encryption.properties'
    keystoreTargetPath = 'system/encryption/intershop.keystore'
    randomTargetPath = 'system/encryption/random'
}

If EncryptionDeploymentPlugin and EncryptionAdminPlugin are applied both (by default), encryption configuration files are automatically generated/adapted before deployment. Especially the default algorithm is changed to the algorithm configured in the encryption block, by default to the weak "PBEWithMD5AndTripleDES". To prevent the deployment from changing the encryption configuration in production, add the following line:

generateEncryptionConfig.enabled = false

Recipe: Encrypt Database Password

Since Gradle tools Version >= 2.0.

Problem

The password that is used for connecting the Intershop 7 application with an Oracle database is stored in the <IS_SHARE>/system/config/cluster/orm.properties file. This is the default location though it is possible to change it. The password might be stored as a plain text:

intershop.jdbc.user=INTERSHOP
intershop.jdbc.password=intershop

If you make your shared file system accessible to a larger group of people (like your support department), but do not want to grant full database access, encrypt your database password.

Solution

1. Create an encryption configuration and configure it to be deployed as described in the Recipe: Configure Encryption.
   Make sure to follow the best practices there (limit file permissions on encryption configuration files). If you do not do so, an attacker may gain access to your keystore and decrypt the database password.
2. Encrypt the password using the encrypt task in a deployment or pre-deployment environment, see discussion.
3. Use the encrypted password in the deployment's settings.gradle to the encrypted password and mark it as encrypted, see disucussion.

Discussion

Encrypt the Password

To encrypt the database password, run the Gradle task encrypt provided by the EncryptionAdminPlugin. It can be executed using a settings.gradle for deployment. Also, you can run them from a standalone Gradle script, applying the EncryptionAdminPlugin, see Recipe: Configure Encryption for details.

In any of the two environments, run (replacing yourPasswordInPlainText by your actual database password):

<gradle command> encrypt -PplainText=yourPasswordInPlainText

The resulting output shows your decrypted password (in the example: encryption1@PBEWithMD5AndTripleDes:5FY97GDnsvU=|3viFU8xFc1XmMhLnPXeWcVWDGgX/WUta)

:generateEncryptionConfig
:encrypt
Encrypted text for plain text 'yourPasswordInPlaintext':
encryption1@PBEWithMD5AndTripleDes:5FY97GDnsvU=|3viFU8xFc1XmMhLnPXeWcVWDGgX/WUta

(Running the command with -q will only output the encrypted password.)

Use the Encrypted Password

In the database block of your settings.gradle for the deployment as prepared in Recipe: Configure the Deployment:

1. Specify the encrypted password in property password.
2. Add the property passwordIsEncrypted with value true.

Given the encrypted password in the example above the result looks like this:

...
deploymentBootstrap {
...
    config {
    ...    
        database {
             host = 'localhost'
             port = 1521
             serviceName = 'ISORCL1.world'
             tnsAlias = 'ISSERVER.world'
             user = 'dbuser'
             password = 'encryption1@PBEWithMD5AndTripleDes:5FY97GDnsvU=|3viFU8xFc1XmMhLnPXeWcVWDGgX/WUta'
             passwordIsEncrypted = true
             oracleClientDir = new File('C:/path/to/oracle/client/dir') 
        }
    }
}

After the deployment the resulting entries in the <IS_SHARE>/system/config/cluster/orm.properties look like this:

intershop.jdbc.user=dbuser
intershop.jdbc.password.encrypted=true
intershop.jdbc.password=encryption1@PBEWithMD5AndTripleDes:5FY97GDnsvU=|3viFU8xFc1XmMhLnPXeWcVWDGgX/WUta

Recipe: Configure Mass Data Replication

Problem

I want to deploy systems, that participate in a replication environment.

Solution

1. Use the deployment DSL to configure the data replication system type of each instance:
   

   1. Use none if the instance to be deployed will not participate in a replication cluster.

   2. Use editing if the instance to be deployed will only provide mass data for the replication environment.

   3. Use live if the instance to be deployed will receive mass data in a replication environment.
      This also applies if it is not the last system of a replication chain.

Discussion

Applying StagingDeploymentPlugin (which is part of IntershopPlugins) will let you configure data replication via the following DSL:

staging {
    systemType = 'editing' | 'live' | 'none'
    replicationClustersFile = new File('<FILL IN>')
}

This will:

• Set the data replication system type in <IS_SHARE>/system/config/cluster/staging.properties
• Copy the given replication clusters configuration file to <IS_SHARE>/system/config/cluster/ if provided. This file is only required for editing systems.
• For live systems:
  
  • Since Gradle Tools 2.0:
  • • Files in <IS_SHARE>/sites/*/1 will also be deployed to <IS_SHARE>/sites/*/2
    • Staged content in <IS_SHARE>/sites/*/[1,2] (including the .active flag) will not be overwritten by deployment
  • Until Gradle Tools 1.1:

    • Be aware that deployment of a live system will reset your replicated content.

      Please consider updating to a newer release of Gradle Tools. As a workaround, you may define a custom modification handling strategy as defined in the Recipe: Keep Local Modifications:

      keep('stagedFiles') {
      	priority '<YourPriority>'
      	dir project.target.shareDirectory
      	include 'sites/*/?/**'
      	include 'sites/*/.active'
      	include 'system/config/cluster/solr/solr.xml'
      }

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

Setup the Initialization Cartridges

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

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.

Setup 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 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: Run the Deployment (Initial Installation / Upgrade / Downgrade)

Problem

I want to run the deployment.

Solution

To deploy an assembly execute the following steps:

1. Prepare and configure your environment.
   See Recipe: Prepare the Deployment and Recipe: Configure the Deployment for details.
2. Create the target user.
3. Execute the Gradle task for the deployment.

Discussion

Initial installation / Upgrade / Downgrade

The workflow for initial installation, upgrade, downgrade is always the same.

The only difference is the used assembly (version) in your settings.gradle file. The deployment automatically handles if there is already a version available in the target directory and deploys the difference.

Create a User

The deployment will not create any users on your target system. Therefore, you have to create a user. This users can execute the deployed system. It is the same user that can run the deployed application.

If you want to run different applications like the webserver and the application server on different hosts, you have to run multiple deployments from multiple settings.gradle files.

User name and groups can be chosen freely.

The user name and group must be declared in the settings.gradle file, see Recipe: Configure the Deployment. This allows for a validation that the current user intends to run the deployment. Also the user will run the Windows services. 

The user must have permissions to create files and directories in the directory of the settings.gradle script, as well as IS_SHARE and IS_HOME as configured in the settings.gradle.

Execute Deployment

To execute the deployment:

1. Log in as the user mentioned above and

2. Execute the following command:

   <gradle command> deploy

Post Install

There are some operations which require root/administrator privileges. For those operations, the deployment creates a post install script. The post install script(s) are listed at the end of the deployment:

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

Logging

Gradle does not support writing log output to a file. Use console redirection or the Linux tee command. See also Gradle user guide on Logging (2.11, 2.7, 2.3, 2.0, 1.8).

Problem

I want to run the deployment.

Solution

To deploy an assembly execute the following steps:

1. Prepare and configure your environment.
   See Recipe: Prepare the Deployment and Recipe: Configure the Deployment for details.
2. Create the target user.
3. Execute the Gradle task for the deployment.

Discussion

Initial installation / Upgrade / Downgrade

The workflow for initial installation, upgrade, downgrade is always the same.

The only difference is the used assembly (version) in your settings.gradle file. The deployment automatically handles if there is already a version available in the target directory and deploys the difference.

Create a User

The deployment will not create any users on your target system. Therefore, you have to create a user. This users can execute the deployed system. It is the same user that can run the deployed application.

If you want to run different applications like the webserver and the application server on different hosts, you have to run multiple deployments from multiple settings.gradle files.

User name and groups can be chosen freely.

The user name and group must be declared in the settings.gradle file, see Recipe: Configure the Deployment. This allows for a validation that the current user intends to run the deployment. Also the user will run the Windows services. 

The user must have permissions to create files and directories in the directory of the settings.gradle script, as well as IS_SHARE and IS_HOME as configured in the settings.gradle.

Execute Deployment

To execute the deployment:

1. Log in as the user mentioned above and

2. Execute the following command:

   <gradle command> deploy

Post Install

There are some operations which require root/administrator privileges. For those operations, the deployment creates a post install script. The post install script(s) are listed at the end of the deployment:

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

Logging

Gradle does not support writing log output to a file. Use console redirection or the Linux tee command. See also Gradle user guide on Logging (2.11, 2.7, 2.3, 2.0, 1.8).

Recipe: List All Deployed Resources

Since Gradle Tools Version >= 2.1.

Problem

I want to get more information about my deployed instance.

Solution

The Gradle task listing will create a file listing.txt containing information about all the deployed resources and their current state.

Discussion

The resulting output file may be quite large, therefore mind some hints:

• All entries are sorted alphabetically by resource name, i.e., absolute path of files.
• There is no integrated query functionality, but the entry format is held simple enough to enable easy filtering. Use any filtering tool (like grep) to get only the information you are looking for.

The general syntax for each entry is as follows:

Flags  ResourceName [AdditionalInformation]

• Flags contains the following:
  1. The first position marks the current state of the resource. The symbol displayed is similar to the output of svn status:
     • ' ' (space) unmodified
     • M modified
     • ! missing
     • ? unknown (file has not been created by the deployment)
     • ~ different type (e.g., there is a directory instead of a file)
  2. More flags may be added in future versions.
• Additional information may contain:
  
  1. (:project:taskName) the task that deployed this resource. (Only if the state flag does not indicate unknown)
  2. A human readable description of the local modification. (Only if the state flag does not indicate unmodified)
  3. More notes may be added in future versions.

Recipe: (Windows) Starting a Service Fails

Problem

On Windows starting one of the services fails. There are (at least) two kinds of problems here:

1. Log on failure. The according error message is:

   Windows could not start the <service name> service on Local Computer.
   
   Error 1069: The service did not start due to a logon failure.

2. Service-specific failure. The according message is:

   Windows could not start the <service> on Local Computer. For more information, review the System Event Log. If this is a non-Microsoft service, contact the service vendor, and refer to the service-specific error code <error code>.

Solution

Logon Failure

Typical problems causing this message are:

1. The password you entered in the post-install scripts was wrong.
2. The Log on as a service right is not granted to the executing user.

In both cases the following procedure solves the problem:

1. Open the Windows services dialog (services.msc).
2. Right-click the service.
3. Choose Properties from the context menu.
4. Switch to tab Log On.
5. Re-enter the password.
6. If the user did not have the Log on as a service permission, it will automatically be granted -
   a message will be shown: The account <account> has been granted the Log On As A Service right.
7. Start the service.

Service-specific Failure (Port Blocked)

The most typical reason for a service-specific failure (after an otherwise successful deployment) is that local ports are blocked by other applications. To verify this:

1. Start the Event Viewer (eventvwr.msc).
2. Navigate to Windows Logs/Application in the tree-view pane.
3. Look into recent events of level Error.

The service may file multiple of such errors. The Intershop HTTP Server service reports a blocked port like this:

The Apache service named <service> reported the following error:
>>>
 (OS 10013)An attempt was made to access a socket in a way forbidden by 
its access permissions.  : AH00072: make_sock: could not bind to address
 [::]:<port>     .

To find out which application blocks the port, run the following command on the command line:

netstat -aon | find ":<port>"

The last column of the output is the process ID (which you can connect to a process name in the Task Manager).

Recipe: Configure Intershop 7

Problem

How to change a file based configuration of Intershop 7 as an administrator/developer, i.e., overwriting the default if any?

Examples are:

• Properties in properties-files in <IS_SHARE>/system/config/cluster
• Properties in properties-files in different locations, like <IS_HOME>/webadapter/webadapter.properties
• Non-properties-file based configuration for Intershop 7, like <IS_SHARE>/system/config/cluster/replication.xml
• Configuration of third-party products deployed with Intershop 7, like <IS_HOME>/httpd/conf/httpd.conf or <IS_HOME>/engine/tomcat/servers/appserver0/conf/server.xml

Solution

First of all the solution depends on the operational concept:

Edit the Files Manually After the Deployment

This is straight-forward, but has a few disadvantages (see the discussion). For this approach see the recipe Keep Local Modifications to keep the deployment from restoring the originally deployed content of configuration files.

Change Configuration Automatically Through the Deployment

There a few cases here:

1. For configuration that is commonly changed the deployment DSL offers convenient ways to provide values directly in your settings.gradle file. Use it if available. See the Recipe: Configure the Deployment.
2. The configuration is property/preference based and read through the configuration framework:
   
   1. Provide a file <environment>.properties next to your settings.gradle file, containing only the properties you want to override. Deploy it as an additional file to <IS_SHARE>/system/config/cluster, see the Recipe: Deploy Custom Files.
   2. Alternatively, you can modify <IS_SHARE>/system/configuration/configuration.xml to read other properties-files or preference tables from the database, see section XmlContentFilter of the Recipe: Change Deployed File Content Through Filters.
3. The configuration file is not read by the configuration framework (like webadapter.properties or any non-properties-file).
   
   1. Preferably use a filter that modifies the file's content during deployment. See the Recipe: Change Deployed File Content Through Filters.
   2. Alternatively replace the whole deployed file by your own content, see the Recipe: Replace a File Deployed by Another Component.

The administrator's effort for automatically changing configuration can reduced and moved to the developer. See the Recipe: Provide Custom Deployment Configuration and Logic.

For the special use case of changing the configuration, the following divisions of work are thinkable:

1. If Intershop 7 default configuration is always overwritten in the same way for a certain assembly, the developer can include the deployment code in the deploy.gradle file of the assembly or custom components, releasing the adminstrator entirely.
2. The developer can provide deployment logic in the deploy.gradle  file of the assembly/custom components that is configurable through Gradle extra project properties. The adminstrator only has to provide values for these properties in the settings.gradle file.
3. The developer can provide custom deployment plugins and DSL extensions. He can optionally pre-apply them in the deploy.gradle file of the assembly/custom components. The adminstrator can then apply these plugins and use their DSL for configuration in the settings.gradle file.
4. The developer can provide custom content filters, which can be used by the administrator in the settings.gradle file.

Discussion

Manual vs. Automatic Configuration

Editing configuration files manually after deployment is the easiest solution for disposable or low-frequency deployments. Its big disadvantage is that it cannot be repeated easily and does not help you in monitoring configuration and restoring from broken states. This is against the ideas of continuous delivery/devops, but still possible.

If you use this approach, you must configure the deployment to keep your modified versions of deployed files. The default behavior is to restore the originals on every deployment run. See the the Recipe: Keep Local Modifications.

Configuration Framework

Most configuration of Intershop 7 is read through the configuration framework in forms of properties. If you want to change these properties, provide your values in an additional configuration source and make it have priority over other sources. Configuration sources and their priorities are configured in <IS_SHARE>/system/config/cluster/configuration.xml.

One kind of configuration source are properties- files. The default configuration.xml file declares to load <IS_SHARE>/system/config/cluster/<environment>.properties if it exists. Its priority is higher than most of the properties-files in <IS_SHARE>/system/config/cluster, like appserver.properties or orm.properties. The name of the file must match the environment you specify in your settings.gradle, e.g., <IS_SHARE>/system/config/cluster/production.properties for environment 'production'.

To add additional configuration sources, you may use the XmlContentFilter, see section XmlContentFilter of the Recipe: Change Deployed File Content Through Filters.

 Recipe: Provide Custom Deployment Configuration and Logic

Problem

Where to declare deployment configuration and custom logic?

Solution

Provide deployment configuration and logic by settings properties/calling methods on a Gradle Project object and the DSL extensions attached to it. Developers and administrators can do so in different places. As described in the Concept - Gradle Deployment Tools, there is a hierarchy of Project objects. The root Project represents the assembly itself, while all child Project objects represent components included in the assembly.

Code snippets in this cookbook, unless stated otherwise, can be put in any of these locations:

1. As an administrator use the deploymentBootstrap.config block inside the settings.gradle file of the deployment.

   Configure Project in settings.gradle

   ...
   deploymentBootstrap {
   	...
   	config {
   		// configure the root project here
   		// for configuring child projects, see discussion
   	}
   }

2. As a developer use the deployment/deploy.gradle file of your custom components for configuration and deployment that your component requires.

   Note

   The behaviour of the deployment changes depending on whether a deploy.gradle script is provided or not. When you do not provide a deploy.gradle, the CartridgeDeploymentPlugin is applied by default.

   If you do provide a deploy.gradle, only its content will configure deployment for the according component. If you want to retain the previous behaviour, you have to include the following snippet into your deploy.gradle:

   Cartridge Deployment with Custom deploy.gradle

   apply plugin: com.intershop.deploy.cartridge.CartridgeDeploymentPlugin

3. As a developer use the deploy.gradle file of your assembly for configuration that cannot be associated to a single component or that is only required in the deployment of that assembly, instead of all assemblies that might include that single component. See the Recipe: Add Custom Deployment Logic to an Assembly or Recipe: Add Custom Deployment Logic to an Assembly (valid to 7.8), depending on your version, for details.

4. As a developer use an additional init.gradle script in your Gradle user home for configuration that is specific to your developer environment. (The settings.gradle file is generated for developers and should not be edited manually.)
5. As a developer provide custom deployment plugins for reusable pieces of deployment configuration/logic.
6. As a developer or administrator apply a custom or third-party deployment plugin in any of the above locations.

Some pieces of deployment data are only known by the administrator at deployment time (like paths and ports). The deployment logic/configuration provided by the developer can read these pieces of data from logic/configuration provided by the administrator in the following ways:

1. Through extra Project properties for simple data types and small amounts of data.
2. Through Custom DSL extension objects for complex data structures or larger coherent data sets.

Discussion

See also chapter Multi-project Builds in the Gradle User Manual (2.11, 2.7, 2.3, 2.0, 1.8).

Configuring Different Projects

Each of the above mentioned locations by default configures a certain Project. The following listings describe that default Project object and show how to configure other Project objects.

Gradle projects are always accessed by their path. The path of the root project is the colon ':', the path of other projects is a colon followed by the (unqualified) name of the associated component: :<component name>, e.g., :bc_foundation.

The use of Gradle's afterEvaluate is explained in the next section.

...
deploymentBootstrap {
	...
	config {
		// configure the root project here
		
		// To configure a child project:
		if (findProject(':<component name>')) {
			project(':<component name>') {
				afterEvaluate {
					// configure the child project here
				}
			}
		}
	}
}

For developer deployments (for which settings.gradle is generated and not subject to manual editing) add a Gradle init script:

settingsEvaluated { Settings settings ->
    if (!settings.extensions.findByName('deploymentBootstrap')) {
        // Not a deployment
        return;
    }
        
    settings.deploymentBootstrap {
        config {                
            logger.lifecycle('Applying custom deployment configuration from: ' + initscript.sourceFile)

            //Write any configuration that can be specified
            // in the config-Block of the settings.gradle         
            // this is like appending it to the actual settings.gradle
            // (i.e. it will be executed after the config block of the settings.gradle)                       
        }
    }  
}

// configure the root project here

// To configure a child project:
if (findProject(':<component name>') {
	project(':<component name>') {
		afterEvaluate {
			// configure the child project here
		}
	}
}

For Gradle tools version 1.0 - 1.1:

// configure the project associated with the component here

// To configure another child project:
if (findProject(':<component name>')) {
	project(':<component name>') {
		def configClosure = {
			// configure the other child project here
		}

		if (project.state.executed) {
	        configClosure()
		} else {
	        afterEvaluate(configClosure)
		}
	}
}

// To configure the root project:
project(':') {
	// configure the root project here
}

For Gradle tools version >= 2.0:

Each project has the method evaluatedProject to which you pass in a closure. If the project is already evaluted the closure will be executed immediately. Otherwise it will be executed one the project has been evaluated. This makes configuring other projects easier:

// configure the project associated with the component here

// To configure another child project:
if (findProject(':<component name>')) {
	project(':<component name>').evaluatedProject {		
		// configure the other child project here
	}
}

// To configure the root project:
project(':') {
	// configure the root project here
}

Order of Evaluation

When providing custom deployment configuration/logic in different locations the order of their evaluation is critical. Deployment configuration is mostly a three-step process distributed over different locations:

1. Apply deployment plugins, which provide DSL extensions in the deploy.gradle scripts of a component/the assembly.
2. Configure these DSL extensions in the settings.gradle file and/or different components/the assembly.
3. Read the data from these DSL extensions to configure some lower-level DSL.

For example:

1. The deploy.gradle of the assembly applies the TargetPlugin, which defines adds an extension target to the project for configuration the location of IS_HOME and IS_SHARE.
2. The settings.gradle provides specific locations for IS_HOME and IS_SHARE by setting the properties localDirectory and targetDirectory of the target extension.
3. The deploy.gradle of an infrastructure component uses the value of target.localDirectory to determine where to deploy its start scripts.

The following diagram shows the different locations and the order in which they are evaluated:

...
deploymentBootstrap {
	...
	config {



		// Evaluation-Order: #2
		// configure the root project here

  
		


		




		
		// To configure a child project:
		if (findProject(':<component name>') {
			project(':<component name>') {
				afterEvaluate {
					// Evaluation-Order: #5
					// configure the child project here
				}
			}
		}

	}
}

// Evaluation-Order: #1 
// configure the root project here

 
















// To configure a child project:
if (findProject(':<component name>') {
	project(':<component name>') {
		afterEvaluate {
			// Evaluation-Order: #5
			// configure the child project here
		}
	}
}

// deploy.gradle script of any component









// Evaluation-Order: #3 
// configure the project associated with the component here

// To configure the root project:
project(':') {
	// Evaluation-Order: #4 
	// configure the root project here
}


// To configure another child project:
if (findProject(':<component name>')) {
	project(':<component name>') {
		def configClosure = {
			// Evaluation-Order: #5
			// configure the other child project here
		}

		if (project.state.executed) {
	        configClosure()
		} else {
	        afterEvaluate(configClosure)
		}
	}
}

The order between multiple locations with the same number is not determined. Do not rely on the order and make sure that different orders do not cause different behavior. Examples of this are:

• Do not rely upon a certain order between the deploy.gradle scripts of different components. (This is the reason for checking the project.state first in the listing.)
• Do not rely upon a certain order between different afterEvaluate blocks applied to the same project.

deployment {            
	// Configure the ResourceDeploymentExtension here 
	// Evaluation-Order: #5 (like all afterEvaluate closures)
	// This example adds an additional property file
	files {
		additionalProperties {
            from new File('/etc/config/intershop7/additional.properties')
         
            // Define target of the copy operation
            into new File(target.shareDirectory, 'system/config/cluster/')
       	}
	}
}

Passing Data Through Extra Project Properties

Use extra project properties to pass in data from the settings.gradle file to deployment logic/configuration provided by development. See also Gradle DSL documentation on Project (2.11, 2.7, 2.3, 2.0, 1.8). Extra project properties can be any Java object of any type. Especially, use File, List or Map if applicable.

The following listings show how to use an extra property across the deploy.gradle file of the assembly, provided by the developer, and the settings.gradle, provided by the administrator.

...

//1. Create the extra property and set a default value (you can use null if there is none)
project.ext.additionalPropertiesFilesDir = new File('/etc/config/intershop7')








deployment {
	 //3. Use the value in a location evaluated settings.gradle
	 files {
		additionalProperties {
			
			from new File(project.additionalPropertiesFilesDir, 'additional.properties')         
            into new File(target.shareDirectory, 'system/config/cluster/')
       	}
	}
}

...
deploymentBootstrap {
	...
	configure {

		
		//2. Provide a value
		additionalPropertiesFileDir = new File('/opt/intershop7/config')		
	}
}

Recipe: Change Deployed File Content With Filters

Problem

How can I deploy a different content for a file than the content that was delivered by the development/build process?

Examples are:

• Set property values of a deployed properties-file (e.g., <IS_HOME>/webadapter/webadapter.properties).
• Manipulate XML files (e.g., <IS_SHARE>/system/config/cluster/configuration.xml).
• Replace placeholders (e.g., '@IS.HOME@' inside shell/batch scripts).

Solution

Declare a content filter. You must specify:

1. A content filter type.
2. A unique name for the filter.
3. A set of deployed files to apply it to, by declaring a directory, includes and excludes.
4. Additional parameters depending on the filter type (like which properties to override with which values, how to manipulate the XML structure etc).

Discussion

This discussion initially describes everything that is independent of the filter type. After that comes a section for each built-in filter type. It is also possible to apply custom content filters, see Recipe - Apply a Custom Content Filter.

General Skeleton

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

The general skeleton for filters looks like this:

deployment {
	...
	filters {
		<type dependent creation method>('<name>') {
			dir = <Java File object>
			include '<Ant style pattern>'
			exclude '<Ant style pattern>'
			...
		} 
	}
}

You may define an arbitrary number of includes and excludes. Includes and excludes can be provided by:

• Ant style patterns to match files path relative to the directory dir,
• A closure passed in a Java File object and returning true or false (the represented file may not exist yet, for initial deployments).

A file is affected by a filter if:

• It is located in the directory dir and
• It is matched by at least one include (if any include is given) and
• It is matched by no exclude.

The following example applies a filter to all pagelet-files inside <IS_SHARE>/sites or any nested directory, except for files ending in a digit:

deployment {
	...
	filters {
		<type dependent creation method>('<name>') {
			dir = target.shareDirectory
			include 'sites/**/*.pagelet'
			exclude { file ->
				file.path.matches /\d$/
			}
			...	
		}
	}
}

OverridePropertiesFilter

Use an OverridePropertiesFilter to specify property values in in properties-files. If the property exists, the filter overwrites its value, otherwise creates a new entry.

Create the filter using the method overrideProperties. Fill the map properties with all properties you want to create over overwrite.

The following example overwrites two values in <IS_HOME>/webadapter/webadapter.properties.

deployment {
	...
	filters {
		overrideProperties('customizePageCache') {
       		dir = target.localDirectory
            include 'webadapter/webadapter.properties'
            properties['errorlog.level'] = 'INFO'
			properties['webadapterAgent.pageCache.expiredFiles.deletionDelay'] = 60
		}
	}
}

XmlContentFilter

Use an XmlContentFilter to modify xml-files. Create the filter using the method xmlContent. Specify how to modify the content by passing a closure to the method withXml. The filter passes in an XmlProvider to the closure, which can be used to read and modify the files contents.

For details on XmlProvider see Gradle API (1.8, 2.1, 2.3, 2.7, 2.11).

The following example adds a set element in <IS_SHARE>/system/config/cluster/configuration.xml after the last set element with a scope attribute of "domain". This snippet is useful for adding your own configuration sources to the configuration framework.

deployment {
	...
	filters {
		xmlContent('addPropertiesFileToConfigurationFramework') {
       		dir = target.shareDirectory
            include 'system/config/cluster/configuration.xml'
			withXml { XmlProvider provider ->
				def sets = provider.asNode().sets.first().children()
				def lastDomainSpecificSet = sets.findAll {it.@scope=='domain'}.last()
				def newSet = new Node(null, 'set', [finder:'property', scope:'cluster,server,domain', fileName:'/etc/config/intershop7.properties'])
				sets.add(sets.indexOf(lastDomainSpecificSet)+1, newSet)
			}
		}
	}
}

PlaceholderReplacementFilter

Use a PlaceholderReplacementFilter if a file contains placeholders that need to be filled by the deployment. The filter will treat all substrings of the file that start and end with specific tokens as a placeholder and take the string in between for its name. (Placeholders never span across lines.)

Create the filter using the method replacePlaceholders. Fill the map placeholders with all placeholders you want to provide values for. Optionally specify the start and end token in the properties beginToken and endToken, defaults are '<@' and '@>'.

The following example replaces all occurences of '<@IS.HOME@>' and '<@IS.SHARE@>' by their location in all shell scripts inside <IS_HOME>/bin.

deployment {
	...
	filters {
		replacePlaceholders('placeholders') {
        	dir = target.localDirectory
			include 'bin/*.sh'
			placeholders['IS.HOME'] = target.localDirectory
			placeholders['IS.SHARE'] = target.shareDirectory
		}
	}
}

EditLinesFilter

Use an EditLinesFilter to modify files on a line-by-line basis. Create the filter using the method editLines. Specify how to modify the content by passing a closure to the method action. The filter calls the closure for each line of the file passing in the line as a String. Yield the modified line as return value of your closure.

The following example sets the ServerAdmin directive in the file <IS_HOME>/httpd/conf/httpd.conf.

deployment {
	...
	filters {
		editLines('provideAdminEmail') {
        	dir = target.localDirectory
			include 'httpd/conf/httpd.conf'
			action { String line ->
				line =~ /^\w*ServerAdmin/ ? 'ServerAdmin admin@customer.com' : line
			}
		}
	}
}

FullContentFilter

(Available since Gradle tools version 1.1)

Use a FullContentFilter to gain full access to a files content and modify it arbitrarily. Use it only for text files and files that have reasonable sizes, since the full file content will be loaded into memory at once.

Create the filter using the method fullContent. Specify how to modify the content by passing a closure to the method action. The filter calls the closure passing in a StringBuilder. Modify the content by calling methods of this StringBuilder inside the closure.

The following example appends an Include-directive to the file <IS_HOME>/httpd/conf/httpd.conf.

deployment {
    ...
    filters {
        fullContent ('appendHTTPDConfInclude') {
            dir = target.localDirectory
            include 'httpd/conf/httpd.conf'
            action { StringBuilder content ->
                /*
                 * append:
                 * # MyModule configuration
                 * Include ${target.localDirectory}/etc/httpd/extra/my-module.conf
                 */
                content.append(System.lineSeparator + '# MyModule configuration' + System.lineSeparator + "Include ${target.localDirectory}/etc/httpd/extra/my-module.conf")
            }
        }
    }
}

Recipe: Deploy Custom Files

Problem

How to deploy files not covered by the default deployment routines?

Solution

For the deployment of files you have to configure a Gradle CopySpec, see Gradle API (2.11, 2.7, 2.3, 2.1, 1.8); also see the corresponding Gradle user guide on Working With Files (2.11, 2.7, 2.3, 2.1, 1.8). You may use this to copy a single file, multiple files or extract files from an archive.

Doing this through the deployment, instead of using simple copy commands, will give you all the advantages of our indexed deployment, e.g., collision detection, modification handling and automatic undeployment.

Discussion

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

Artifacts

To deploy files from your source project, those files must be published to the binary repository as standalone Ivy artifact or included in a *.zip file. For further details refer to Cookbook - Gradle Build Tools.

You can then refer to the repository's artifacts in your deployment logic.

deployment {
	files {
		example {
			// Unzip source artifact 'foo'
			from artifacts(type:'foo', extract: true)

			// Select subset to be deployed here
			include '**/*.properties'

			// Define target of the copy operation
			into new File(target.shareDirectory, 'system/config/cluster/')
		}
	}
}

Plain Files

You can also deploy files directly from the local file system.

deployment {
	files {
		productionProperties {
			// Copy a single file from the same folder as this settings.gradle file
			from new File(settingsDir, 'production.properties')
         
			// Define target of the copy operation
			into new File(target.shareDirectory, 'system/config/cluster/')
		}
	}
}

Recipe: Apply a Custom Content Filter

Problem

I have an artifact in which I need to replace some parts according to the environment. The predefined filters do not fit for my scenario.

Solution

To solve this problems execute the following steps:

1. Implement your own filter.
2. Register your filter.
3. Configure your filter.

Discussion

Implement Your Own Filter

The solution starts with implementing your own filter. The best starting point is the com.intershop.deploy.filters.AbstractDeploymentContentFilter. You only need to implement your filter logic on top of this class.

An easy example for a filter replacement is replacing all placeholders in a string with another value.

package com.intershop.deploy.filters;
 
import org.gradle.api.file.ContentFilterable
 
class ReplaceAllFilter extends AbstractDeploymentContentFilter
{
    Map<String, String> placeholders = [:]
    
    ReplaceAllFilter(String name)
    {
        super(name)    
    }
 
    @Override
    public void configureNormalizedFilter(ContentFilterable filterable)
    {   
        filterable.filter { String line ->
            placeholders.each {String key, value -> 
                line = line.replace(key, value)     
            }
            
            line
        }
    }          
}

Register Your Filter

To register your filter, add the following line to your deploy.gradle script. 

import com.intershop.deploy.filters.ReplaceAllFilter
 
deployment {
    filters {
        registerBinding(ReplaceAllFilter, ReplaceAllFilter)
    }
} 

Configure Your Filter 

To configure your filter, add the following lines to your deploy.gradle script.

The configuration varies according to your filter.

import com.intershop.deploy.filters.ReplaceAllFilter
 
deployment {
    filters {
        registerBinding(ReplaceAllFilter, ReplaceAllFilter)
        
        replaceAll(ReplaceAllFilter) {
           dir = infrastructureDeployment.localDirectory
           
           include 'httpd/conf/httpd.conf'
           placeholders['ServerAdmin admin@localhost'] = 'ServerAdmin admin@intershop.com'
       }
    }
}

Recipe: Customize the Deployment of an Archive

Problem

I need to customize the deployment of an archive. This includes renaming of files, exclusion of files or deployment of some files to another target directory.

Solution

Use a FileDeployment, which is a Gradle CopySpec for configuring the deployment.

Discussion

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

The following example shows how to configure the deployment. 

It deploys the init.d files by changing the name to the directory etc/init.d.

deployment {
    files {
        initd {
            from artifacts(type:'local', extract: true)
 
            // Include files in this processing         
            include 'etc/init.d/eserverx*'
 
            // Rename files                       
            rename { String fileName ->
                fileName.replace('eserverx', "eserver${project.instanceId}")
            }
 
            // Change target directory
            into new File(infrastructureDeployment.localDirectory, 'etc/init.d')
        }
    }
}

Recipe: Customize Directory Handling

Problem

I need to create a directory during deployment.

Solution

Parent directories are created automatically when deploying files. There is no need for any action in this case.

To create a directory without deploying files inside,

1. Configure a directory deployment in the deploy.gradle script of your component.

Discussion

Deployment

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

The following example shows a sample configuration.

deployment {
	directories {
		if (target.includeLocal) {
			localLog {
				path new File(target.localDirectory, 'log')
			}
		}

		if (target.includeShare) {
			shareLog {
				path new File(target.shareDirectory, 'system/log')
			}
		}
    }
}

This will create the directories IS_HOME/log and IS_SHARE/system/log regardless of whether or not files will be deployed into these directories.

Undeployment

A directory, that has not been defined as directory resource, will get deleted once its last entry is removed.

However, for directories that are defined as directory resource, the following applies:

• Once the directory resource gets removed, all files that are not desired, will get deleted recursively. If the directory is empty afterwards, it is deleted as well.
• The directory will not get deleted when the last entry inside gets removed (unless the directory resource itself gets removed as well).
• The directory will not get deleted, if the directory resource gets removed, but there are still desired files inside this directory.

Recipe: Create a Custom Symbolic Link

Problem

I want to create a custom symbolic link at my target system.

Solution

Configure the deploy.gradle script of your component to create the link. Links are currently only supported at linux platform.

Discussion

For the creation of the link define:

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

The following example shows a sample configuration.

deployment {
    links {
        varPublic {
            from = new File(project.instanceVarDir, 'webadapter/public')
            to = new File(target.localDirectory, 'webadapter/public')
        }

        varLog {
            from = new File(project.instanceVarDir, 'log/webadapter')
            to = new File(target.localDirectory, 'webadapter/log')
        }
 
        etcDir {
            from = new File(project.instanceEtcDir, 'webadapter.properties')
            to = new File(target.localDirectory, 'webadapter/webadapter.properties')
        }
    }
}

Recipe: Create a Custom Service

Problem

I want to add a custom service.

Solution

 For creating a service do the following:

1. for Windows systems
   1. Create the service executable (not scope of this document).
   2. Configure the service.
2. for Linux systems
   1. Create the service shell script (not scope of this document).
   2. Create the init.d shell script (not scope of this document).
   3. Configure the service.

Discussion

The creation of services differs for Linux and Windows systems. By that reason you need to decide, for which platform you want to create a service. If you need to support both platforms, you need to add two configurations to your deployment script.

Linux Service

To configure a service for Linux you need to set the following attributes at your service definition.

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

The following example shows, how to configure a service for Linux.

deployment {
    services {
        linux {
 	        webAdapter {
                serviceScript = new File(target.localDirectory, "etc/init.d/eserver${target.instanceId}-httpd")
                runLevels = [3,5]
            }
        }
    }
}

Windows Service

To configure a service for Windows you need to set the following attributes at your service definition. 

The following example shows, how to configure a service for Windows.

deployment {
    services {
        windows {
	        webAdapter {
		        serviceName = 'Service 1'
                command = [
                    new File(target.localDirectory, 'httpd/bin/httpd.exe').absolutePath,
                    '-k', 'runservice',
                    '-n', serviceName,
                    '-f', new File(target.localDirectory, 'httpd/conf/httpd.conf').absolutePath]
                displayName = 'INTERSHOP HTTP Server'
                startupType = com.intershop.deploy.resources.WindowsServiceDeployment.StartupType.AUTOMATIC
                user = assemblyDeployment.user
            }
        }
    }
}

Recipe: Deploy a Custom Web Application

Since Gradle tools version >= 2.0.

Problem

I need to deploy an additional *.war file into the servlet container.

Solution

The Tomcat servlet container of Intershop 7 can be used to host any *.war file and is not limited to the Intershop application.

Gradle Deployment Tools 2.0 introduced a new extensible API for Tomcat server instances. You have to

1. Make your web app available as a component.
2. Define your extension API to configure the web app in the DSL.
3. Add the deployment logic to your component's deploy.gradle script.
4. Use your newly defined extension API in the deployment's settings.gradle script.
5. (Optional) Add a new host type for your web app (including tcm, 3rd_tomcat and runtime), see Cookbook - Gradle Assembly Tools or Cookbook - Gradle Assembly Tools (valid to 7.8), depending on your version. 

Discussion

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

Configuration DSL

The following snippet shows the structure of the Tomcat DSL.

tomcat {
	instances {
		instanceName {
			// insert server-specific configuration here
		}
    }
}

Specify a given tomcat instance to host your custom web app. For this purpose each Tomcat instance object is ExtensionAware, see Gradle API (2.11, 2.7, 2.3, 2.1, 2.0) and can be customized via extensions. There are several possibilities to leverage this functionality:

No Additional Configuration Needed

In cases where your custom web app does not need custom configuration, you can just attach a named flag to the Tomcat instance:

ext.myExt = true

This code will create an additional flag named myExt, that just marks the Tomcat instance for your deployment script.

Custom Extension Class

When you need additional configuration properties for your web app, it is recommended to use a JavaBean-compliant class for your extension:

extensions.create('myExt', MyExtClass)
myExt {
	foo = 'bar'
}

This code will create an extension named myExt with a new instance of class MyExtClass. Then you can configure your extension the usual Gradle-way.

Dynamic Extension Object

In case you want to avoid creating your own extension class, you can also use a dynamic Groovy object instead:

extensions.add('myExt', new Expando())
myExt {
	foo = 'bar'
}

This code will create an extension named myExt with a new dynamic Groovy Expando, that you can assign any kind of properties. You can also configure this extension the usual Gradle-way.

Deployment Logic

Alter your component's deployment script to deploy its web app into those servers, that have been configured accordingly:

apply plugin: com.intershop.deploy.assembly.TargetPlugin
apply plugin: com.intershop.deploy.intershop.TomcatPlugin

deployment {
    if (target.includeLocal) {
        files {
    		tomcat.instances.find {
	    		it.hasProperty('myExt')
		    }.each { instance ->
			    "${instance.name}Tomcat" {
                    from artifacts(type:'webapp', extract: true)
                    into instance.baseDir
                }
		    }
        }
    }
}

The instance's baseDir refers to the specific Tomcat CATALINA_BASE directory.

Recipe: Replace a File Deployed by Another Component

Problem

How to replace an file which was deployed by another component?

The typical use case for this is providing a patch for a component.

Solution

To solve this problem execute the following steps:

1. Deploy a custom file to the same location as the file you want to replace.
   See the Recipe: Deploy Custom Files.
2. Run the deployment.
   It will abort with an conflict error, because the file from the original component and your custom file will cause a conflict.
3. Resolve the conflict by excluding the file from the deployment of the original component.

Discussion

If you configured the deployment of your custom file correctly, the deployment will abort with a DuplicateResourceException like this:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':<component 1>:deploy<deployment name 1>Files'.
> Task :<component 1>:deploy<deployment name 1>Files: Resource '<file>' already defined for Task :<component 2>:deploy<deployment name 2>Files

One of the task names belongs to your component and your FileDeployment declaration. (For the assembly the name of the component will be missing.) Fill in the other component and deployment name.

FileDeployment implements a standard Gradle CopySpec, see Gradle API (2.11, 2.7, 2.3, 2.1, 1.8). To exclude the original add the following deployment configuration:

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

if (rootProject.findProject(':<component>')) {
    rootProject.project(':<component>') {
        afterEvaluate {
            deployment.files.<deployment name> {
            	exclude { 
                	new File(destinationDir, it.path) == <file object pointing to the deployed file>)                        
                }
            }
        }
    }
}

Full Example

The following example shows how to replace the <IS_SHARE>/system/config/oracle/tnsnames.ora file deployed by component core.

1. Deploy a custom version:

   Deploy custom tnsnames.ora

   deployment {
       files {
           tnsNamesOra {
               // Copy a tnsnames.ora file from the same folder as this settings.gradle file
               from new File(settingsDir, 'tnsnames.ora')             
               // Define target of the copy operation
               into new File(target.shareDirectory, 'system/config/oracle/')         
           }
       }
   }

2. The conflict message shown during deployment: 

   Conflict Message

   FAILURE: Build failed with an exception.
   
   * What went wrong:
   Execution failed for task ':core:deployShareFiles'.
   > Task :core:deployShareFiles: Resource '...\system\config\oracle\tnsnames.ora' already defined for Task :deployTnsNamesOraFiles

3. Exclude original file:

   • Since Gradle Tools 2.0:

     Exclude original file

     project(':core') {
     	afterEvaluate {
         	deployment.files.share {
             	exclude { 
                 	new File(destinationDir, it.path) == new File(target.shareDirectory, 'system/config/oracle/tnsnames.ora')                        
                 }
             }                                    
         }
     }

   • For Gradle Tools 1.0 and 1.1:

     Exclude original file

     if (findProject(':core')) {
         project(':core') {
             def configClosure = {
                 deployment.files.share {
                     exclude {
                         new File(destinationDir, it.path) == new File(target.shareDirectory, 'system/config/oracle/tnsnames.ora')
                     }
                 }
             }
             if (project.state.executed) {
                 configClosure()
             } else {
                 afterEvaluate(configClosure)
             }
         }
     }

Recipe: Keep Local Modifications

Problem

I want to customize the strategy, how the deployment proceeds when it detects external modifications on deployed resources.

Solution

Modification handling can be configured on two levels:

• It can be configured on a per-file basis via an includes/excludes-based DSL.
• Files not covered by any specific modification handling specification are handled according to a global default strategy.

Discussion

Regardless of the way of configuration, there are four modification handling strategies available:

You must assign a priority to each modification handling specification. A priority is just a string and its rank is defined by a list, that names all available priorities in ascending order. Please, consider the priorities ['default', 'intershop'], in which case intershop has a higher priority than default. These priorities allow for fine-grained control over which modification handling strategy is to be used for any given file. There are two priorities defined per default:

• default is the priority of the global fallback strategy, see below
• intershop is the priority of all file-specific modification handling specifications, that are predefined in standard IS7.

Customer projects are encouraged to use an own priority level, to be able to override both default and intershop specifications.

Global Configuration

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

The global fallback modification handling strategy is configured as a property in the deployment DSL, as is the order of handling priorities:

assemblyDeployment {
	//...
	defaultModificationHandler = 'abort'
	modificationPriorities = ['default', 'intershop', 'myProject']		
}

Configure Handling of Specific Resources

Components can declare how their deployed components are to be handled in case of an external modification. Modification specification via includes/excludes works just like it does for filters:

deployment {
	modification {
		backup('intershopProperties') {
			priority 'myProject'
			dir target.localDirectory
			include 'intershop.properties'
		}
	}
}

Recipe: Deploy Data Replication Environment

Problem

I want to deploy systems that participate in a data replication environment.

Solution

Setting up a simple two-node data replication environment involves the following major tasks:

• Deploying the Target Cluster
• Modifying the Data Replication Configuration
• Deploying the Source Cluster
• Data Replication Post Configuration

Discussion

The data replication deployment involves at least one source cluster and one target cluster. The number of IAS and IWS instances and their distribution is irrelevant to the data replication mechanism. This recipe illustrates a simple two-node data replication deployment, which includes two single-host Intershop 7 clusters (using the host type all).

The following sections assume that the deployment preconditions (as described in Recipe: Prepare the Deployment) are met, i.e., that the Intershop 7 users, the deployment target directories etc are prepared on both nodes.

Deploying the Target Cluster

When setting up a data replication environment, you must first deploy the target (live) cluster in order to get a replication configuration file, which must be copied and modified for deploying the source (editing) cluster later.

To deploy the target cluster, follow the proceedings as described in Recipe: Configure the Deployment. The config DSL block of the settings.gradle file, however, needs some additional information:

• an individual live database user
• a staging type setting

config {
  ...
  database {
    host = '<db-hostname>'
    port = <db-port>
    serviceName = '<db-servicename>'
    tnsAlias = '<db-tnsalias>'
    user = '<live-db-user>'
    password = '<live-db-password>'
    oracleClientDir = new File('</opt/oracle/client|c:/oracle/client>')
  }
  staging {
    systemType = 'live'
  }
}

For more details, see Recipe: Configure Mass Data Replication.

Modifying the Data Replication Configuration

The source (editing) cluster needs a specific data replication configuration, which tells it the required details of the target (live) cluster. To prepare the source cluster configuration:

1. Copy the example replication configuration file to the deployment directory of the source (editing) cluster host.
   This file, replication-clusters.xml.sample, is located in /opt/intershop/eserver1/share/system/config/cluster of the deployed target (live) cluster.

2. Open the copied replication configuration file and edit the settings as required.
   The following parameters must be set:

   Parameter	Description/Example
   Target system, ID and activity	<target-system id="TargetSystem" active="true">
   Web server URL	<webserver-url>http://target(live)-system-host:port</webserver-url>
   Database source/target communication	Use either a database link or, if the source and target system databases reside in the same database instance, a direct schema access. Database link: <source-database-link>ISEDITING</source-database-link> Target schema name for direct schema access: <target-database-user>INTERSHOP_LIVE</target-database-user>

Deploying the Source Cluster

To deploy the source cluster, follow the proceedings as described in Recipe: Configure the Deployment. As with the deployment of the target cluster, the config DSL block of the settings.gradle file needs additional information:

• an individual editing database user
• a staging type setting and the specific data replication configuration.

config {
  ...
  database {
  host = '<db-hostname>'
  port = <db-port>
  serviceName = '<db-servicename>'
  tnsAlias = '<db-tnsalias>'
  user = '<edit-db-user>'
  password = '<edit-db-password>'
  oracleClientDir = new File('</opt/oracle/client|c:/oracle/client>')
  }
  staging {
    systemType = 'editing'
    replicationClustersFile = new File('</opt/intershop/install/replication-clusters.xml|c:/install/replication-clusters.xml>')
  }
}

Data Replication Post Configuration

Preparing data replication environments involves additional post-deployment tasks:

• Checking Replication Configuration Files
• Initializing the Database for Replication
• Creating a Database Link

Checking Replication Configuration Files

Intershop recommends to recheck the configuration files for the data replication after the clusters' deployment. In both the target cluster and the source cluster, the corresponding files staging.properties and replication-clusters.xml are located in <eserver#>/share/system/config/cluster.

Make sure that the following details are properly set:

staging.properties

Provides basic settings like the system role (editing, live) for the current Intershop 7 cluster, must be configured in both clusters (source and target).

In the source cluster, the staging type setting must be

staging.system.type = editing

In the target cluster, the staging type setting must be

staging.system.type = live

replication-clusters.xml

Provides the communication setting for a source cluster to connect to the target cluster(s) via database link or database schema access, must be configured in the source cluster.

When using a database link between two database instances, the target-system section must include a line like

<source-database-link>ISEDITING</source-database-link>

When directly accessing a database schema within one database instance, the target-system section must include a line like

<target-database-user>INTERSHOP_LIVE</target-database-user>

Initializing the Database for Replication

The data replication mechanism is based on a set of specific tables (live and shadow tables), which need to be created before the actual data replication can take place. This requires to initialize the database accordingly. Two basic approaches are available to initialize the database in a new replication environment:

• Running a DBinit process on the source (editing) cluster, then exporting a database dump and importing this dump in the target (live) cluster
  With this approach, you can already prepare the required database tables when executing the DBinit process. For information about DBinit, refer to Cookbook - DBInit. 

• Importing an existing database dump in both the source (editing) and the target (live) clusters
  With this approach, the database tables required for the data replication are created during the first replication process. For information about data replication, the involved procedures, its initialization etc, refer to Cookbook - Mass Data Replication - Administration.

Creating a Database Link

A database link is a probable option to provide for the communication between the source cluster and the target cluster. If you chose to use a database link, you must create it in the database schema of the target cluster. To do so, log on to the target cluster as the live database user <live-db-user> and issue the following SQL commands (replacing the placeholders).

To remove an old database link, execute

DROP DATABASE LINK isediting;

To create a new database link using, for example, the easy connect syntax, execute

CREATE DATABASE LINK isediting CONNECT TO <edit-db-user>
  IDENTIFIED BY <edit-db-password>
  USING '//<edit-db-hostname>:<edit-db-port>/<service_name>';

To test the database link, execute

SELECT tname FROM tab@isediting;

Recipe: Undeploy

Problem

How to undeploy the whole assembly?

Solution

There is a dedicated Gradle task to undeploy all artifacts of the installed assembly. This task undeploys all artifacts, that have been registered in the index file during previous deployment operations. The handling of artifacts, that have not been indexed, can be configured.

Discussion

Execute Undeployment

To start the undeployment:

1. Execute the following command as the user, who originally deployed the assembly.

   <gradle command> undeploy

Configure Cleanup

Additional files are placed into the installation directories by the running server, e.g., log files or page compile artifacts. As those files are not registered in the index, undeployment cannot associate those files with installed components.

You can configure whether or not those artifacts are to be deleted in your local installation's settings file:

...
deploymentBootstrap {
	...
	config {
		// Insert code examples here
	}
}

// Insert code examples here

//...
assemblyDeployment {
	//... 
	purgeUnknownFiles = false    
}

Setting this value to true will cause the undeployment process to delete all files inside known directories (such as local or share).

Recipe: Deploy a Local Eureka Server

Problem

I want to deploy a local Eureka server and want to use it for service discovery.

Solution

It is necessary to configure the Eureka extension in the settings.gradle file for the host type 'serviceDiscovery' before deploying the server. For details, see: Recipe: Configure the Deployment.

Example

config {
	...
	eureka {
		serverHostName = 'localhost'
    	serverPort = 'my_port'
    	serverUrlPath = 'eureka/'
    	serverReplicaUrl = 'replica_url'
		serverEnvironment = 'LIVE'
		// service url is mandatory for clients instances (appserver, solr, microservices, etc.), but not within the settings.gradle for the host type serviceDiscovery it's not necessary
		// serviceUrls.default = 'http://<host_name>:<my_port>/eureka/'
  	}
}

Following attributes can be configured within a Eureka extension:

Discussion

The serviceUrls attribute provides the possibility to choose at which server the clients should be registered. This means, another Eureka server can be chosen to register clients.

Resiliency

For a software system using service discovery, both the clients and the servers need to be resilient.

• Eureka clients are built to handle the failure of one or more Eureka servers. Since Eureka clients have the registry cache information in them, they can operate reasonably well, even if all of the Eureka servers go down.
• Eureka servers are resilient to other Eureka peers going down. Even during a network partition between the clients and servers, the servers have built-in resiliency to prevent a large scale outage.

Further information can be found here: Eureka Wiki

Recipe: Register ICM at Eureka

Problem

I want to register the ICM application server, the SolR server and the Web Adapter agent at the Eureka server.

Precondition

You need to have access to an Eureka server: You can accomplish this by:

• The deployment of a local eureka server Recipe: Deploy a Local Eureka Server or
• Access to another Eureka server

Solution

It is necessary to configure the extensions within the settings.gradle file for the according host types before deploying the server. For details, see: Recipe: Configure the Deployment.

Host Type: share

config {
	appserver{
		serviceAppName = 'appServerName'    
	}
	solr{
		serviceAppName = 'solrServerName'    
	}
	eureka {        
        serviceUrls.default = 'http://<host_name>:<my_port>/eureka/'
   	}
	microservices {
        configProperties['intershop.naming.service.RecurringOrder'] = 'microserviceName'
        configProperties['intershop.naming.service.Scheduling'] = 'microserviceName'
   }
} 

Host Type: solr

config {
 	solr{
		serviceAppName = 'solrServerName'    
	}
	eureka {        
        serviceUrls.default = 'http://<host_name>:<my_port>/eureka/'
   	}
 } 

Host Type: webserver

config {
	appserver{
		serviceAppName = 'appServerName'    
	}
	eureka {        
        serviceUrls.default = 'http://<host_name>:<my_port>/eureka/'
   	}
 } 

Recipe: Microservice Deployment

Problem

I want to deploy the microservices.

Precondition

It is is necessary to have access to an Eureka server: You can accomplish this by the fulfillment of:

• Deployment of a local Eureka server Recipe: Deploy a Local Eureka Server or
• The URL of a global Eureka server

Solution

It is necessary to configure the extensions in the settings.gradle file for the host type 'microservices' before deploying the server. For details, see Recipe: Configure the Deployment.

config {
	microservices {
		port = '<MY_PORT>' 
		name = 'microserviceName'
		instanceId= 'microserviceInstanceId'
            
		configProperties['javax.persistence.jdbc.url']  = '<CONNECTION_URL_DATABASE>'
		configProperties['javax.persistence.jdbc.user']  = '<DATABASE_USER>'
		configProperties['javax.persistence.jdbc.password']  = '<DATABASE_PASSWORD>'
            
		configProperties['intershop.naming.service.RecurringOrder'] = 'microserviceName'
		configProperties['intershop.naming.service.Scheduling'] = 'microserviceName'
 	}
	appserver{
        serviceAppName = 'appServerName'   
    }
    eureka {        
        serviceUrls.default = 'http://<host_name>:<my_port>/eureka/'
    }

 }

Discussion

The configProperties attribute allows to add further properties, which can be set during deployment without the need to adapt the microservice extension.

There is another JDBC property: javax.persistence.jdbc.driver which is listed within the environment.properties of the microservices. This property was separated from the other JDBC properties, since it does not belong to the configuration.

Deploy the Recurring Order Service and the Scheduling Service Together

The names of microservice, the Recurring Order service and the Scheduling service must be the same (name = 'microserviceName').

config {
	...
	microservices {
		...
		name = 'microserviceName'
		...
            
		configProperties['intershop.naming.service.RecurringOrder'] = name 
		configProperties['intershop.naming.service.Scheduling'] = name
	}
}

Deploy the Recurring Order Service and the Scheduling Service Separately

Assume you have two instances <Instance_1> and <Instance_2>.

• The Recurring Order service should be installed on <Instance_1>
• The Scheduling service should be installed on <Instance_2>

The service name (configProperties['intershop.naming.service.RecurringOrder'] = 'recurringOrder'), that should be deployed on this instance, has to match to the name (name = 'recurringOrder'), which is used to register at Eureka server. The service name of the other service, which is deployed on the other instance, has to match to the name used by the other instance. So the settings.gradle files for the instances have to be configured the following way

config {
	microservices {
		name = 'recurringOrder'
            
		configProperties['intershop.naming.service.RecurringOrder'] = 'recurringOrder'
		configProperties['intershop.naming.service.Scheduling'] = 'scheduling'
	}
}

config {
	microservices {
		name = 'scheduling'
            
		configProperties['intershop.naming.service.RecurringOrder'] = 'recurringOrder'
		configProperties['intershop.naming.service.Scheduling'] = 'scheduling'
	}
}