Home » Devtech review » LangsNTechs » Java » ElasticPath » 6.1.2 » Getting Elastic: attention points for EP6.1.2 starters

Getting Elastic: attention points for EP6.1.2 starters

For anyone who decided to start e-commerce with ElasticPath (version 6.1.2 in particular): if you’re digging though official documentation already trying to get an understanding of what the EP "ecosystem" is and what installation/configuration process should be – here are some quirks and highlight points that are worth knowing.

Points covered here are: system overview; URLs, ports, credentials configurations; localization configuration for indexing/searches.

System and environment
ElasticPath is pure Java web-application (actually 4 separate web-applications: storefront, commerce manager server, search server and webservices server AKA connect server; one of which is optional – the "connect server" that provides SOAP WebServices support) + Eclipse RCP based desktop application for managing EP known as the Commerce Manager Client.

Obviously, this means that for EP installation you need Java runtime (JRE) and Java Application server. Officially supported Application Servers for EP6.1.2 are Apache Tomcat 5.5, BEA Weblogic 9.2MP2 & 10.0, IBM Websphere AS 6.1 and JBoss AS 4.0.4.
One thing to note right away is that HTTPS connections should be enabled.

The nuance that might not be obvious about JRE is that you need to install JAI (Java Advanced Imaging) support for it. Yet this is described in detail in official documentation.

Also since EP is relational database backed, you obviously need RDBMS server, and EP6.1.2 officially supports Microsoft SQL Server 2005, MySQL Server 5.x and Oracle 10g/11g.

A bit less obvious point is that EP also requires SMTP server to send emails, so be sure to have one (I guess your hosting-provider will probably have it, but it depends).

And least obvious point is that you better have FTP server for sharing "assets" with Commerce Manager Client (although other ways of sharing are possible, FTP seems to be the most reasonable one to use, and this way is described in official documentation). More on this point below.

Commerce Manager Client connections
As mentioned already, Commerce Manager Client (CMClient as we call it) is desktop application that is used to manage EP configuration, stores, products etc. On EP server side Commerce Manager Server (CMServer) webapp is handling connections from CMClient instances. However, this is not enough. CMClient also needs to have: a) direct connection to Search server; and b) ability to download/upload files from/to "assets" folder, where pages templates, images and that sort of stuff is kept.

Since it’s not a very good idea to expose Search Server webapp to whole Internet, official documentation recommends to make VPN connections for CMClient users, and thus only expose Storefront webapp to WAN (and, if installed/needed WebServices server webapp), keeping Search server, and actually also CMServer + assets FTP, accessible only from inside LAN.

To make it even more entangled, at some rare cases CMClient might need to connect to Storefront (on HTTPS by the way), and also it can optionally update itself using update server.

Explaining and configuring these connections:
1. Commerce Manager Server
URL and credentials for Commerce Manager server are entered in dialog window that appears on Commerce Manager Client startup.
Also there is system setting "COMMERCE/SYSTEM/assetsHttpHost" which should practically contain same URL as the one used in login dialog mentioned above.
2. Search Server
Is configured via "COMMERCE/SYSTEM/SEARCH/searchHost" system setting. This setting should contain URL that could be accessed by your Commerce Manager Client, and also by EP webapplications like Storefront and Commerce Manager Server.
3. Assets share
URL, credentials, path and protocol are configured via "COMMERCE/APPSPECIFIC/RCP/ASSETS/vfs*" system settings. Note that protocol can be any of the ones supported by Apache VFS (version 20070730 is used in EP6.1.2). For more info see http://commons.apache.org/vfs/filesystems.html
As already mentioned, most reasonable way to share assets is FTP server, and this variant is described in official documentation.
4. Storefront HTTPS connection
URL configured via "COMMERCE/STORE/storefrontUrl" system setting.
Here’s what comment to system setting says:

"The secure (HTTPS) storefront URL. This URL is used by the Commerce Manager client application for CSR login on behalf of customers. Certain customer service activities, such as editing orders, require the CSR to log in as the customer. The Commerce Manager client application uses this URL to perform the login. If the specified URL does not begin with {{https://}}, the login request will fail and the CSR will not be able to perform the action."

This pretty much explains it all. If your store is somewhere at http://www.mystore.com, URL will be https://www.mystore.com (assuming you use default port for HTTPS, which is 443).
5. Update site for Commerce Manager Client
Configured via two system settings "COMMERCE/APPSPECIFIC/RCP/updateSiteEnabled" – to switch updating on or off (by setting to "true" or "false"), and "COMMERCE/APPSPECIFIC/RCP/updateSiteHomebase" which will contain URL to update site.
Purely optional, so better just switch it off until you know you need it. For more info check official documentation.

Identifying troubles:
1. Searching for products or anything else in CMClient fails with exception – quite obviously search server URL config might be wrong.
2. When creating/editing Store on "Theme" tab there are no themes listed, or when editing product image selecting/uploading image doesn’t work, or when running import job uploading CSV file doesn’t work – something is wrong with assets VFS share config.

EP webapps connections
ElasticPath webapplications are also connecting to each other to perform different tasks. CMServer and Storefront (and WebServices server if present) connect to Search server to perform searches. Storefront connects to CMServer to make it send emails (like order confirmation email etc).
Besides this, CMServer in it’s turn connects to SMTP to perform actual email sending.

Explaining and configuring these connections:
1. Search server
Exactly same as p.2 for Commerce Manager Client connections (see above).
Is configured via "COMMERCE/SYSTEM/SEARCH/searchHost" system setting.
2. CMServer
Configured via "COMMERCE/SYSTEM/EMAIL/emailCmUrl", "COMMERCE/SYSTEM/EMAIL/emailAuthenticationUsername" and "COMMERCE/SYSTEM/EMAIL/emailAuthenticationPassword" system settings, that should contain CMServer URL, valid CM Client User login and his password respectively. You can use same credentials as you use for CMClient to login to CMServer, but since EP is asking user to change his password once a month, it may be pain in the neck to update those each time. So it is reasonable to create special CMClient user for email sending.
3. SMTP server
Host and port configured via "COMMERCE/SYSTEM/EMAIL/mailHost" and "COMMERCE/SYSTEM/EMAIL/mailPort" system settings respectively.

Identifying troubles:
1. When doing search on storefront error occurs – search server URL config might be wrong.
2. When ordering products, requesting new password with "forgot password" functionality or registering new user, expected order/password/registration confirmation mails are not sent – email configuration might be wrong.
Obviously, it’s a good idea to check logs to see what exactly went wrong. Not that if Storefront couldn’t connect or authenticate with CMServer to send emails, errors will be in Storefront webapp logs. But if CMServer could not send email via SMTP server, errors will be in CMServer webapp log.

Storefront HTTP/HTTPS ports and port mapper
Storefront webapp is the one users will connect to with their browsers and see actual stores pages. Some pages related to login/checkout process are better server over secure channels, i.e. HTTPS. For more information on this please check official documentation.

One thing to keep in mind is that when you access some URLs like http://mystore.com/checkout.ep, which are configured by default to be server over HTTPS, your browser will be redirected to https automatically, so http://mystore.com/checkout.ep should lead to https://mystore.com/checkout.ep.
However ports for HTTP and HTTPS connection might not be default ones in your case (you should know that port 80 is default for http, so typing http://mystore.com in browser address bar is same as typing http://mystore.com:80 , and 443 is default for https, so https://mystore.com practically means https://mystore.com:443). To let EP know how to send you from HTTP to HTTPS you have to specify which ports are you using. This is configured in "WEB-INF\conf\spring\security\acegi.xml" file inside Storefront webapp (and if you change this config you have to restart Storefront webapp for changes to apply).
In this file you should look for bean id="portMapper" token, you’ll see something like

    <!-- port # are specified in default.xml -->
    <bean id="portMapper" class="org.acegisecurity.util.PortMapperImpl">
	<property name="portMappings">
		<entry key="80"><value>443</value></entry>

This entry tells EP that requests to secure resources that came to port 80 should be redirected to port 443.

If in your installation you use some special ports, like 7001 for HTTP and 7002 for HTTPS for example, you should put those numbers in.
Best way though is to still have 80 and 443 configured too, as you can put two entries in the map, like this:

    <!-- port # are specified in default.xml -->
    <bean id="portMapper" class="org.acegisecurity.util.PortMapperImpl">
	<property name="portMappings">
		<entry key="80"><value>443</value></entry>
		<entry key="7001"><value>7002</value></entry>

This way if you will someday, for example, put Apache in front of your Application server, and apache will be accessible on 80/443 ports, you won’t have to change your config, and both direct connects to 7001/7002 and through-Apache connects on 80/443 will work ok.

Identifying troubles:
1. When going to some pages like /checkout.ep you get “Redirect loop” error in browser – this most probably means port-mapping is configured incorrectly.

Internationalization/Localization quirks – catalog and store locales
When configuring products catalog for EP stores you can specify a locale. Also when creating a store you can specify locale for it.
It is recommended to use exactly same locale for catalog and store. We have a catalog which has “NL_nl” / “Dutch (Netherlands)” as it’s default locale, and when we used “NL” (Dutch) locale for store (or maybe it was vice versa, don’t remember clearly now), indexing products didn’t found products titles with exactly this locale, and didn’t do any fallback. As a result, sorting products by title didn’t work for users when they were doing products search/browsing in this store.

Internationalization/Localization quirks – stopwords, synonyms and stemmer for non-English languages
SOLR/Lucene indexes used in ElasticPath are quite complex subject on their own.
Long story short, you’re lucky if you have all product’s titles, descriptions and text attribute values contain texts in same language. And a bit less lucky if this language isn’t English (if it is you may skip this part completely).
We’re lucky – we only need Dutch everywhere.

So what’s the problem?
In order for full-text searches to work fine a bit of “magic” is applied by indexing engine (Apache Lucene), and this magic is language dependent.
First part of magic is stopwords and synonyms. Stopwords are words like “the” and “of” that are thrown away from indexed text and search keywords in order not to affect relevance score, because it would be meaningless to let them do so. Synonyms are synonyms, and Lucene engine allows you to configure them so that looking for some term X would match fields that doesn’t contain it, but contain it’s synonyms.
Second part is stemming, which is there to allow searches on keywords like “accountancy” match texts like “accountant book XYZ” with hight relevance, despite difference between strings “accountancy” and “accountant” (obviously, these strings are quite different for a machine, though may seem similar for human, because human can understand the meaning of the words – but not the machine, which only “knows” the codes of symbols).
Obviously, stopwords, synonyms and stemming are language-specific. So what to do if you need to operate with language other than English?

In Search Server webapp there is folder WEB-INF\solrHome\conf that contains configurations related to indexing.

You can see it contains stopwords.txt and synonyms.txt – names are pretty self explanatory. Put your language-specific synonyms and stopwords in respective files (see comments on format inside files themselves) and you’re done.

Next, you see there are a lot of *.xml files in there, and some of those files contain this token inside them:
<filter class="solr.EnglishPorterFilterFactory" protected="protwords.txt"/>
This is the english stemmer. You should replace this entry with stemmer for your language. See http://wiki.apache.org/solr/LanguageAnalysis for possible configurations and more information.
For example, as you can see, for Dutch language the above-mentioned link suggests using this config:
<filter class="solr.SnowballPorterFilterFactory" language="Dutch" />
(Ignore the “LowerCaseFilterFactory” – it’s already in those XMLs, don’t add it twice). So we just replace the line from XMLs that has solr.LowerCaseFilterFactory with this line, restart CMServer, do complete reindexing (in EP6.1.2 it’s done via CMClient – you have to choose each index and click “Rebuild index” button – easy), and that’s it.

Don’t forget that this document is just an addition to official documentation, but hopefully a useful one.
I hope it’ll help to understand some unclear moments about EP installation and configuration, and highlight some points that are kind of “hidden” but in fact require attention.
Good luck!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s