The Commerce Reference Store (CRS) is an important part of Oracle Commerce/ATG because it is a fully functional implementation that is rich in features, and a reference for how to do things for many projects. I originally wrote a blog post on installing CRS with ATG 10, but thought I’d make an update for ATG 11.1. With Endeca thrown into the mix, it has certainly gotten more complicated, but also easier in a way because of the large Endeca community.
I’d highly recommend battling through the installation of the whole stack by yourself if you’re looking to learn more about the fundamentals of Oracle Commerce/ATG. If not, continue on and I’ll hopefully make this as painless as possible.
Tips before starting:
- Plan on at least half of a day to do this. One working day is more realistic. If you’re new to the platform, plan on a few days of struggle.
- Take extra time to verify functionality of the individual pieces we setup before moving on. You need to have 100% confidence before adding more layers on.
- Don’t be afraid to reference the Oracle documentation for this setup.
We’re going to install everything on a prebuilt Linux VM released by Oracle. You can get better performance by building one yourself from a clean Linux distro, however using a prebuilt VM saves time. Below is an overview of what’s being installed.
| Name | Location |
| JDK 1.7.0_55 | /opt/java/jdk1.7.0_55 |
| JBoss 6.1 EAP | /opt/jboss/jboss-eap-6.1 |
| Endeca MDEX 6.5.1 | /opt/endeca/MDEX |
| Endeca Tools & Frameworks 11.1 | /opt/endeca/ToolsAndFrameworks |
| Endeca Platform Services 11.1 | /opt/endeca/PlatformServices |
| Endeca CAS 11.1 | /opt/endeca/CAS |
| ATG 11.1 | /opt/atg/ATG11.1 |
| CRS 11.1 | /opt/atg/ATG11.1/CommerceReferenceStore |
Everything is installed under the Oracle user and stems from the /opt directory.
Prerequisite Steps
1. Download and install VirtualBox and 7zip if you do not already have them.
2. You’re also going to need JBoss 6.1 EAP version. I can’t provide this. If you can’t find the EAP version, the community releases should work, but I can’t guarantee. You could also use a different application server, but then a few steps in this document won’t work.
3. Next, download this prebuilt Oracle VM. We only care about having Oracle Database 11g installed, since it’s a pain to install it yourself. Obviously this isn’t ideal, but it will work to get your feet wet with the whole Oracle Commerce/ATG installation process.
4. Stitch up the VM using 7zip and double click the resulting .ova file to import it into VirtualBox.
5. Once imported, open up the settings for the VM, go to the “Shared Folders” tab and add a folder in.
I’m adding my local ATG folder and will be referencing it for the rest of this post. All files we download will also be placed into this folder. They can be accessed on the VM in the directory /media/sf_ATG.
6. Now navigate to the “Network” tab, then click “port forwarding”. These ports on the guest (the VM) are forwarded out to the host (your PC), which allow the host to access services from the guest. Add/remove the ports until you get what’s shown below.
7. Start VM and login with oracle/oracle. The root password is also oracle. There’s an overview of the VM here.
Note: You should also be able to ssh into the VM using the command:
ssh oracle -p 2222 localhost
8. Once started and the desktop launched, navigate to Applications > Oracle Database 11g Express Edition > Run SQL Command Line:
connect system/welcome1
EXEC DBMS_XDB.SETHTTPPORT(0);
8. By default Oracle Database has a service on port 8080, which we will use for our JBoss server. We will move it to a different (invalid) port (credit from here).
9.Finally shutdown/startup the database using the options in the menu.
JDK Installation
Download JDK 1.7.0_55 for the 64 bit Linux platform from here. I unzipped it before transferring into the VM.
su – root
mkdir /opt/java
cp -R /media/sf_ATG/jdk1.7.0_55 /opt/java
chown oracle -R /opt/java/
JBoss Installation
JBoss is really easy, you just copy the JBoss folder into it’s new home:
su – root
mkdir /opt/jboss
unzip /media/sf_ATG/jboss-eap-6.1.0.zip -d /opt/jboss
chown oracle -R /opt/jboss
Endeca Installation
Head over to edelivery.oracle.com and download the following software for the Linux 64 bit platform:
- Oracle Commerce MDEX Engine 6.5.1 for Linux
- Oracle Commerce Guided Search Platform Services 11.1 for Linux
- Oracle Commerce Experience Manager Tools and Frameworks 11.1 for Linux
- Oracle Commerce Content Acquisition System 11.1 for Linux
We want to install everything under the Oracle user in this VM. Run these to get the installation directory setup:
su – root
mkdir /opt
chown -R oracle /opt
Installing MDEX
su – root
unzip /media/sf_ATG/V46002-01.zip -d /opt
chown oracle /opt/OCmdex6.5.1-Linux64_829811.sh
exit (back to oracle user)
sh /opt/OCmdex6.5.1-Linux64_829811.sh –target /opt
It should be painless to install. Afterwards, run this to set the proper environment variables to a shell file we’ll use when starting/stopping Endeca.
echo ‘source /opt/endeca/MDEX/6.5.1/mdex_setup_sh.ini’ >> ~/endeca-env.sh
source ~/endeca-env.sh
The recommended method is to add this into your ~/.bash_profile file, however I prefer to keep these variables outside of the user, because it can get complicated if another version of Endeca is added to the user down the road. I will do the same with a file named atg-env.sh for ATG a bit later on.
Installing Platform Services
su – root
unzip /media/sf_ATG/V45999-01.zip -d /opt
chown oracle /opt/OCplatformservices11.1.0-Linux64.bin
exit (back to oracle user)
/opt/OCplayformservices11.1.0-Linux64.bin –target /opt
- Oracle Guided Search HTTP Service port: 8888
- Shutdown port: 8090
- Choose Y for EAC
- Use /opt/endeca/MDEX/6.5.1 for the MDEX engine path
- Choose N for the reference implementation
After you’re done, run:
echo ‘source /opt/endeca/PlatformServices/workspace/setup/installer_sh.ini’ >> ~/endeca-env.sh
Installing Experience Manager
For the Experience Manager installation, refer to this document if you have any troubles. Experience manager is a bit different to install than others.
su – root
unzip /media/sf_ATG/V46389-01.zip -d /home/oracle/Desktop
chown oracle -R /home/oracle/Desktop/cd
mkdir /u01/app/oraInventory
chown oracle -R /u01/app/oraInventory
From the desktop, navigate to the cd/Disk1/install folder and double click the runInstaller executable.
Click through. Do the complete installation option. Specify /opt/endeca/ToolsAndFrameworks as the home directory when prompted.
After the installation, run:
su – root
sh /u01/app/oraInventory/orainstRoot.sh
exit (back to oracle)
echo ‘export ENDECA_TOOLS_ROOT=/opt/endeca/ToolsAndFrameworks/11.1.0’ >> ~/endeca-env.sh
echo ‘export ENDECA_TOOLS_CONF=$ENDECA_TOOLS_ROOT/server/workspace’ >> ~/endeca-env.sh
Installing Content Acquisition System (CAS)
su – root
unzip /media/sf_ATG/V46393-01.zip -d /opt/
chown oracle /opt/OCcas11.1.0-Linux64.sh
exit (back to oracle user)
sh /opt/OCcas11.1.0-Linux64.sh –target /opt
Use these installation values (the defaults):
- CAS port: 8500,
- Shutdown port: 8506,
- CAS hostname: localhost.
It should be painless.
Verifying Endeca Installation
The Endeca installation is now complete, but we should test it before moving forward. Follow the steps listed later in this document to provision and deploy a basic Endeca application.
You should be able to click the facets on the left to narrow down the search, as well as click on the products. If this does not work, do not continue until you’ve fixed it.
ATG Installation
Once again, head on over to edelivery.oracle.com and download the following software for the Linux 64 bit platform:
- Oracle Commerce Platform 11.1 for UNIX
- Oracle Commerce Reference Store 11.1 for UNIX
su – root
mkdir /opt/atg
chown oracle -R /opt/atg
unzip /media/sf_ATG/V46005-01.zip -d /opt
chown oracle /opt/OCPlatform11.1.bin
exit (back to oracle)
/opt/OCPlatform11.1.bin
- Products to install: 1,2,3,4 (there should be 6, select everything except Motorprise and Quincy Funds)
- Use /opt/atg/ATG11.1 as the installation folder
- Select JBoss as the application server
- JBoss Home: /opt/jboss/jboss-eap-6.1
- JDK Home: /opt/java/jdk1.7.0_55
- JBoss port: 8080
- RMI port: 8860
After installation, make a file named ~/atg-env.sh that has these contents. Then run source ~/atg-env.sh to place those variables into your current shell session.
CRS Installation
su – root
unzip /media/sf_ATG/V46007-01.zip -d /opt
chown oracle /opt/OCReferenceStore11.1.bin
exit (back to oracle)
/opt/OCReferenceStore11.1.bin
Ensure it’s getting installed into /opt/atg/ATG11.1 and take all the defaults. It shouldn’t be a problem.
Next, we need to make the two database schemas required for CRS. You can do this from sqlplus as we did earlier to change the Oracle process listening on port 8080, or you can use sqlplus, which I prefer. Anyway, use these connection details:
Once in, run the following:
create user crs11_core identified by crs11_core;
create user crs11_pub identified by crs11_pub;
grant connect, resource, dba to crs11_core, crs11_pub;
commit;
Oracle Commerce/ATG almost always has two database catalog schemas, plus one called core that contains things like user data and order info. In this setup, we’re going to combine these three schemas into a single one to take some complexion out of the setup process.
Important:
After the database is ready, we need to get a driver for the Oracle Database. Download ojdbc6.jar here, and copy it into /opt/atg. Be sure the Oracle user has full permissions on it.
Finally, create the Apps directory for the new CRS app that we’ll make:
mkdir /opt/endeca/Apps
Next, run CIM using:
source ~/atg-env.sh
sh $DYNAMO_HOME/bin/cim.sh
Steps through the CRS installation:
- Choose “Product Selection” and the 9th option for only Commerce Reference Store. This option includes the necessary dependencies.
- Addons: None
- Demo Apps: None
- Choose non-switching datasource
- Index by sku
- Setup databases:
- The ending database URL should be jdbc:oracle:thin:@localhost:1521:xe
- Production uses crs11_core
- Publishing uses crs11_pub
- Specify ojdbc6.jar for the driver
- Then do the schema creation and data imports
- Despite what CIM says, you can skip the OPSS Security configuration
- Create the publishing JBoss server
- Ports should be +100, meaning all ports are +100 of the standard JBoss configuration
- Create the production JBoss server, accepting the defaults
- Along with the production server, choose option D to provision the endeca application
- With Experience Manager Preview
- App deployment path: /opt/endeca/Apps
- CAS Path: /opt/endeca/CAS/11.1.0
- User segment server port: 8180
- Oracle Wallet jps-config.xml: /opt/endeca/ToolsAndFrameworks/11.1.0/server/workspace/credential_store/jps-config.xml
- Tools and Frameworks: /opt/endeca/ToolsAndFrameworks/11.1.0
- MDEX: /opt/endeca/MDEX/6.5.1
- Platform Services: /opt/endeca/PlatformServices/11.1.0
- Then deploy the endeca app. See troubleshooting at the end for help if it doesn’t work.
- Assemble and deploy the application
At this point, CRS is configured and should start correctly. You can start each server by calling:
source ~/atg-env.sh
sh /opt/jboss/jboss-eap-6.1/bin/standalone.sh –server-config=atg_publishing_lockserver.xml -b 0.0.0.0
sh /opt/jboss/jboss-eap-6.1/bin/standalone.sh –server-config=atg_production_lockserver.xml -b 0.0.0.0
Verify that the BCC comes up and that you can login. Also, verify that the storefront has a clean log and you can access it. The store will look empty because we haven’t yet deployed some assets over from the publishing schema.
Deploying Fresh Content
When you initially do the CRS installation, some assets require a deployment from the publishing instance over to the storefront. You don’t have to do this, but you’ll have very limited CRS storefront data.
Make sure the store is also started. Login to the BCC at localhost:8180/atg/bcc using admin / <your password>.
Follow these steps from the CRS 11.1 installation documentation exactly.
This will probably not work the first time, and you’re probably on your own to figure out what’s wrong. See the troubleshooting section below for some help.
After the content has been deployed, an index should be kicked off. You can view the index status by going to http://localhost:8080/dyn/admin/nucleus/atg/commerce/endeca/index/ProductCatalogSimpleIndexingAdmin/.
You can also kick off a new index here by clicking “Baseline Index”.
Afterwards, no matter if you did an index manually or from the BCC full deployment, run the following:
sh /opt/endeca/endeca/Apps/CRS/control/promote_content.sh
Do not do this until the index is 100% successful. If all went well, you should be able to navigate to localhost:8080/crs and successfully search for an item. I would also recommend doing a checkout, just to ensure that side of things is functional.
At this point, you’ve successfully setup Oracle Commerce 11.1 (ATG 11.1 + Endeca 11.1) as well as the Commerce Reference Store. In the next post, we’ll be walking through the steps to setup the native iOS app.
Troubleshooting and Extra Help
I ran through this setup twice on my own to make sure my instructions actually worked. I ran into quite a lot of issues. Here are the biggest problems you might face:
Database Space Issues
You may run into some errors complaining about insufficient tablespace sizes. This means that the tablespace for the schema we’re trying to insert into has insufficient space.
You can run:
select file_name, bytes, maxbytes from dba_data_files;
To get a listing of these files, and how full they are crs11_core and crs11_pub should write to system.bdf.
To expand system.bdf, run:
alter database datafile ‘/u01/app/oracle/oradata/XE/system.dbf’ autoextend on maxsize
2048M;
This will expand the tablespace as needed to a max of 2gb (previously it was ~600mb).
Dyn/admin Password Invalid
I can’t remember if I fat-fingered the production dyn/admin password, but it suddenly stopped working for me halfway through the installation. This can be fixed by assembling the application with the Admin.Reset module.
This can be added from CIM in the Application Assembly & Deployment section for the production server.
Endeca Problems
I’m fairly new to Endeca, and certainly had many Endeca problems. They stemmed from 2 issues:
1. Not provisioning the CRS Endeca app correctly from CIM
It’s really picky to get the app to import correctly (especially if you’ve imported it and deleted it once before). After doing this a few times, I came up with this script to help remove the CRS app entirely so that it can be retried.
2. Endeca is not running
You should be 100% sure that all parts of Endeca are running before doing almost everything in the post. You can start the various parts of Endeca using:
Platform Services:
/opt/endeca/endeca/PlatformServices/11.1.0/tools/server/bin/startup.sh
Tools & Frameworks (workbench):
/opt/oracle/endeca/ToolsAndFrameworks/11.1.0/server/bin/startup.sh
Experience Manager:
/opt/endeca/PlatformServices/11.1.0/tools/server/bin/startup.sh
CAS:
/opt/endeca/endeca/CAS/11.1.0/bin/cas-service.sh
Although now I prefer to just start the workbench, then login and manually turn the other services on.
Port Reference
All port configurations mentioned here take the default values, except:
- The ATG publishing instance should have ports +100 in value than normal, because you can’t run production and publishing at the same time if they’re on the same port set
- The Endeca user segment server should have port 8180