CoreMedia Digital Experience Platform 8 Developer Manual, Version 7.5.45-10
3.5.4. Developing with Apache (optional for e-Commerce) | 3.5.4.3. Configuring the Network

Connect the following machines as described below:

VMware Clone of an IBM WCS RAD

Vagrant Box containing the Apache Server

You have already started the Vagrant VM. Now you must add an entry to its /etc/hosts file and restart the Apache server. Just apply the following steps, replacing <your-commerce-vm-ip> by the IP address of your IBM Commerce VM. The exact shop-ref domain must be the same as the value of the livecontext.ibm.wcs.host property in the localEnvironment Maven profile which you have already configured.

cd blueprint
vagrant ssh
sudo su -
echo "<your-commerce-vm-ip> shop-ref.ecommerce.mycompany.com" >> /etc/hosts
service httpd restart

Your Development Computer

You must add the Apache Vagrant VM and the IBM Commerce VM to your local /etc/hosts file, so that your browser can resolve the links of the Blueprint application.

sudo su -
echo "192.168.252.100 blueprint-box.vagrant helios.blueprint-box.vagrant studio-helios.blueprint-box.vagrant \
preview-helios.blueprint-box.vagrant shop-helios.blueprint-box.vagrant shop-preview-helios.blueprint-box.vagrant \
shop-preview-production-helios.blueprint-box.vagrant" >> /etc/hosts
echo "<your-commerce-vm-ip> shop-ref.ecommerce.mycompany.com" >> /etc/hosts

On a Windows machine the hosts file is C:\Windows\System32\drivers\etc\hosts

Now you can start the three Tomcat instances for Studio, Preview CAE and Delivery CAE:

cd blueprint/modules/cae/cae-preview-webapp
mvn tomcat7:run -PlocalPreviewEnvironment,<profile-to-your-content-server>

cd blueprint/modules/cae/cae-live-webapp
mvn tomcat7:run -PlocalEnvironment,<profile-to-your-content-server>

cd blueprint/modules/studio/studio-webapp
mvn tomcat7:run -PlocalPreviewEnvironment,<profile-to-your-content-server>

If all systems are up and running, you should visit each of the following URLs in order to install the SSL certificates into your browser. Otherwise, you will be bothered with the pop-ups later, and the Studio preview will not work properly at all.

Checklist

If you followed the instructions so far, all components and virtual machines are wired correctly. However, throughout the project lifecycle you possibly adapt the setup to your specific needs, invent some shortcuts for redeployment or modify the configuration of a component temporarily or permanently. Tracking down the indirections of machines referencing each other can be tedious, so here is a list of the relevant host configurations which you should check first in case of problems. The following table shows the involved machines with their default addresses as provided by the setup and the symbolic names used to reference the machines.

The concrete values may be adapted to your particular environment. Just make sure that you change it consistently at all of the following checkpoints. The Preview CAE and the Live CAE are supposed to run on your local machine. They do not need fancy symbolic names, because they are not exposed to user agents but only accessed internally by Apache. The network adapter with the mapping for 192.168.252.1 is set up by Vagrant. The IP address 192.168.252.100 of the Vagrant machine which hosts the Apache server is configured in the blueprint/Vagrantfile. The symbolic names are Apache virtual hosts and server aliases. You find their configurations in the various .conf files under /etc/httpd/conf.d. Once the machines are up and running, you should check their connections as follows. The wiring of the machines includes some entries in their /etc/hosts files, because the names of development machines are usually not resolved by a DNS server.

WebSphere Commerce System

The WCS needs entries for fragment.supplier.blueprint-box.vagrant and preview-fragment.supplier.blueprint-box.vagrant in its C:\Windows\System32\drivers\etc\hosts file. The URL prefix of the CAE to fetch the fragments from is configured in Stores\WebContent\WEB-INF\web.xml:

<context-param>
  <description>
    This is the base for all fragment URLs for the preview site. It must point to a CoreMedia Preview-CAE. An empty value is allowed.
    In this case the liveCaeHost will be used instead and all fragments will be received from the Live-CAE.
  </description>
  <param-name>com.coremedia.fragmentConnector.previewCaeHost</param-name>
  <param-value>http://preview-fragment.supplier.blueprint-box.vagrant/</param-value>
</context-param>
<context-param>
  <description>
    This is the base for all fragment URLs for the live site. It must point to a CoreMedia Live-CAE.
    This parameter is mandatory.
  </description>
  <param-name>com.coremedia.fragmentConnector.liveCaeHost</param-name>
  <param-value>http://fragment.supplier.blueprint-box.vagrant/</param-value>
</context-param>

CAE

The CAE references the WCS via the livecontext.ibm.wcs.host property. Therefore, the CAE machine (that is, your local machine) needs a hosts entry for shop-ref.ecommerce.coremedia.com.

User Agent

You probably want to check the results of your development work in a browser, so your local machine does not only serve as CAE host but also as a user agent. In order to access the CoreMedia DXP 8 applications, you must configure the Apache virtual host names helios.blueprint-box.vagrant and shop-helios.blueprint-box.vagrant for the Live application and the respective virtual hosts for the Preview application in your hosts file.

Apache

shop-ref.ecommerce.coremedia.com is referenced in various Apache configuration files, thus the Apache machine needs a hosts entry for it. The CAEs are referenced by their IP addresses.

The Apache configuration files, which are located under /etc/httpd/conf.d, declare virtual hosts for the names mentioned in Table 3.6, “Components of the Apache Development Setup” and map them to the CAEs and the WCS. For example, the virtual host shop-preview-helios.blueprint-box.vagrant is configured in commerce-shop-preview/commerce-shop-preview.conf and looks like this:

<VirtualHost *:80>
  ServerName shop-preview-helios.blueprint-box.vagrant
  RequestHeader set X-FragmentHost preview

  <Proxy balancer://commerce-shop-cluster>
    BalancerMember http://shop-ref.ecommerce.coremedia.com route=shopWorker loadfactor=1 ttl=300
  </Proxy>
  <Proxy balancer://cae-cluster>
      BalancerMember ajp://192.168.252.1:40010 route=studioWorker loadfactor=1 ttl=300
  </Proxy>
  ...
</VirtualHost>

<VirtualHost *:443>
  ServerName shop-preview-helios.blueprint-box.vagrant
  RequestHeader set X-FragmentHost preview

  ...
</VirtualHost>

There are two virtual host declarations for each name, one for HTTP and one for HTTPS. The RequestHeader defines a context to identify from which CAE (Live or Preview) the fragments will be received.

Since this development setup uses a shared WCS for the Preview and Live CAEs, a request header is used to identify which CAE will be used to receive fragments. If the request header X-FragmentHost is set to preview, the fragments will be received from preview-fragment.supplier.blueprint-box.vagrant. If this request header is set to live or is not set, all fragments will be received from fragment.supplier.blueprint-box.vagrant. For catalog image delivery in a shared WCS environment see Section 8.7.4.2, “Placeholder Resolution for Asset URLs”

Developing New Apache Configurations

If you have successfully built your local development system as described above, you can change the Apache configuration.

cd blueprint
vagrant up      # or vagrant resume if you suspended it
mvn clean install -am -pl :studio-apache -PlocalPreviewEnvironment
mvn clean install -am -pl :delivery-apache -PlocalEnvironment
cd boxes
mvn antrun:run
cd ..
vagrant provision

For Linux Blueprint provides a script for this task: workspace-configuration/apache/updateApaches.sh. There are two more scripts which update only the Preview Apache or the Delivery Apache, respectively. You can also apply these scripts from IntelliJ Idea as follows: