User Guide - KonaKart
- 03/05/2007 4:30 PM
Applicable Plans: Standard Plus VPS, Standard Max VPS, All Advanced VPS, all Premier VPS plans (CentOS 5 plans)
KonaKart is a open source online shopping cart application written in Java. It is built upon the foundation of osCommerce making it database compatible with this widely used eCommerce solution. With KonaKart you can build an eCommerce application from scratch, or convert an osCommerce deployment to take advantage of the power and performance of a Java environment.
Requirements
This documentation will guide you through the steps necessary to configure Tomcat to serve the KonaKart application in your eApps Virtual Private Server (VPS). Before you proceed, make sure you have the required applications installed. Please note that KonaKart has been packaged for the eApps VPS without Tomcat bundled together. We have separated these two open source software components out to achieve more flexibility and consistency for your use of Tomcat.
Java (any version can be used)
TomcatX (TomcatX = tomcat5, tomcat6, etc depending on the version you have installed)
mod_jk (if you are on a CentOS 5 or higher OS you may choose to use mod_proxy_ajp instead, which is available by default)
MySQL
KonaKart (install last)
We recommend that you install the latest versions of the applications listed above, but earlier versions should work as well. These applications can be selected during the order process of your VPS or can be installed from the Add Applications area on the System tab of your Control Panel. Since KonaKart is dependent on Tomcat and MySQL it is best that it's installed after all the other required applications. This is because the KonaKart installation process will need the Tomcat home to deploy the application and MySQL to create the KonaKart database.
During installation the KonaKart application is deployed in /opt/tomcatX/vhostwebapps/KonaKart. In this location the ROOT application (konakart), konakartadmin application and the birt-viewer application will be found. The configuration examples below will be based on this location.
Java (any version can be used)
TomcatX (TomcatX = tomcat5, tomcat6, etc depending on the version you have installed)
mod_jk (if you are on a CentOS 5 or higher OS you may choose to use mod_proxy_ajp instead, which is available by default)
MySQL
KonaKart (install last)
We recommend that you install the latest versions of the applications listed above, but earlier versions should work as well. These applications can be selected during the order process of your VPS or can be installed from the Add Applications area on the System tab of your Control Panel. Since KonaKart is dependent on Tomcat and MySQL it is best that it's installed after all the other required applications. This is because the KonaKart installation process will need the Tomcat home to deploy the application and MySQL to create the KonaKart database.
During installation the KonaKart application is deployed in /opt/tomcatX/vhostwebapps/KonaKart. In this location the ROOT application (konakart), konakartadmin application and the birt-viewer application will be found. The configuration examples below will be based on this location.
Configuration Examples
NOTE: As mentioned earlier, this document is to assist you with configuring Tomcat to serve the KonaKart application. For details on Tomcat please see our Tomcat User Guide.
Upon installation, KonaKart will be placed in a virtual host document base inside the Tomcat home directory. Please read further for the exact location and details on using KonaKart. Also, if your eApps VPS is running the CentOS 5 or later Operating System version, you have the option of using mod_jk or the mod_proxy_ajp to integrate the Apache web server with Tomcat. To find out what version of OS you are running, login to your Control Panel, and from the My Account tab click on the Subscriptions link. Then click on your VPS subscription. You will see the operating system at the top of the page. The CentOS 5 and higher operating systems use Apache 2.2 which is required for mod_proxy_ajp.
Each of the following examples explains a specific way to deploy your KonaKart application.
Upon installation, KonaKart will be placed in a virtual host document base inside the Tomcat home directory. Please read further for the exact location and details on using KonaKart. Also, if your eApps VPS is running the CentOS 5 or later Operating System version, you have the option of using mod_jk or the mod_proxy_ajp to integrate the Apache web server with Tomcat. To find out what version of OS you are running, login to your Control Panel, and from the My Account tab click on the Subscriptions link. Then click on your VPS subscription. You will see the operating system at the top of the page. The CentOS 5 and higher operating systems use Apache 2.2 which is required for mod_proxy_ajp.
Each of the following examples explains a specific way to deploy your KonaKart application.
| Example 1 - Configuring Tomcat to use KonaKart as a standalone store accessable at yourdomain.com, www.yourdomain.com or store.yourdomain.com. Using a text editor of your choice open /opt/tomcatX/conf/server.xml and add the lines below just after the last closing </Host> tag. <Host appBase="vhostwebapps/konakart" name="yourdomain.com" unpackWARs="true" autoDeploy="true"> <Alias>www.yourdomain.com</Alias> <Context path="" docBase="ROOT" debug="0" reloadable="true"/> <Context path="/konakartadmin" docBase="konakartadmin" debug="0" reloadable="true"/> <Context path="/birt-viewer" docBase="birt-viewer" debug="0" reloadable="true"/> <Logger className="org.apache.catalina.logger.FileLogger" prefix="yourdomain.com." suffix=".txt" timestamp="true"/> </Host> If you want to host your store over a subdomain like store.yourdomain.com the name on the Host tag above should be "name=store.yourdomain.com" and the www.yourdomain.com alias must be replaced with any aliases you have. Next you must add the mod_jk or mod_proxy balancer directives for the Apache web server. The directives must be entered in the Custom Settings area of your your Control Panel. DO NOT add these to the the Apache configuration file (httpd.conf). Go to your Control Panel > Site tab > Website Settings > Custom Settings tab and add the appropriate mod_jk OR mod_proxy_ajp directives below. mod_jk DirectivesJkMount /* ajp13# Directives to enable Apache to continue serving applications dependent on it. SetEnvIf Request_URI "/webmail*" no-jk SetEnvIf Request_URI "/mail*" no-jk SetEnvIf Request_URI "/awstats*" no-jk SetEnvIf Request_URI "/myadmin*" no-jk SetEnvIf Request_URI "/pgadmin*" no-jk SetEnvIf Request_URI "/cgi-bin*" no-jk SetEnvIf Request_URI "/openwebmail*" no-jk mod_proxy_balancer Directives# Directives for eApps applications dependent on ApacheProxyPass /webmail ! ProxyPass /mail ! ProxyPass /joomla ! ProxyPass /awstats ! ProxyPass /myadmin ! ProxyPass /cgi-bin ! ProxyPass /pgadmin ! ProxyPass /openwebmail ! # Directives for your application ProxyPass / ajp://localhost:8009/ |
| Example 2 - Configuring Tomcat to add KonaKart context to an existing Host in your server.xml file accessable at yourdomain.com/konakart and www.yourdomain.com/konakart. Using a text editor of your choice open /opt/tomcatX/conf/server.xml and add the lines below just after the last closing </Host> tag. <Host appBase="vhostwebapps/yourdomain.com" name="yourdomain.com" unpackWARs="true" autoDeploy="true"> <Alias>www.yourdomain.com</Alias> <Context path="" docBase="ROOT" debug="0" reloadable="true"/> <!-- context for konakart apps --> <Context path="/konakart" docBase="/opt/tomcatX/vhostwebapps/konakart/ROOT" debug="0" reloadable="true"/> <Context path="/konakartadmin" docBase="/opt/tomcatX/vhostwebapps/konakart/konakartadmin" debug="0" reloadable="true"/> <Context path="/birt-viewer" docBase="/opt/tomcatX/vhostwebapps/konakart/birt-viewer" debug="0" reloadable="true"/> <Logger className="org.apache.catalina.logger.FileLogger" prefix="mydomain.com." suffix=".txt" timestamp="true"/> </Host> Note: You can set path= to a value of your choice. In other words, if you want your visitors to access konakart at yourdomain.com/store your path will be path="/store". Next you must add the mod_jk or mod_proxy balancer directives for the Apache web server. The directives must be entered in the Custom Settings area of your your Control Panel. DO NOT add these to the the Apache configuration file (httpd.conf). Go to your Control Panel > Site tab > Website Settings > Custom Settings tab and add the appropriate mod_jk OR mod_proxy_ajp directives below. mod_jk DirectivesIf you want to use mod_jk to have Apache send your KonaKart request to Tomcat please add the directives below.JkMount /konakart* ajp13 JkMount /konakartadmin* ajp13 JkMount /birt-viewer* ajp13 mod_proxy_ajp DirectivesIf you want to use mod_proxy_ajp to have Apache send your KonaKart requests to Tomcat, please add the directives below.ProxyPass /konakart ajp://localhost:8009/konakart ProxyPass /konakartadmin ajp://localhost:8009/konakartadmin ProxyPass /birt-viewer ajp://localhost:8009/birt-viewer Note: If the path in your context is something other than /konakart, /konakartadmin and /birt-viewer make sure the correct values are in the directives above. For example if your path is path=/store then the directives for mod_jk and mod_proxy_balance will look like the following. Jkmount /store* ajp13 or ProxyPass /store ajp://localhost:8009/store |
| Example 3 - Configuring Tomcat to use Konakart with an existing site served by Apache (PHP, PERL, JavaScript, Ruby on Rails, etc) that can be accessed at yourdomain.com/konakart and www.yourdomain.com/konakart. Using a text editor of your choice open /opt/tomcatX/conf/server.xml and add the lines below just after the last closing </Host> tag. <Host appBase="vhostwebapps/yourdomain.com" name="yourdomain.com" unpackWARs="true" autoDeploy="true"> <Alias>www.yourdomain.com</Alias> <Context path="/konakart" docBase="/opt/tomcatX/vhostwebapps/konakart/ROOT" debug="0" reloadable="true"/> <Context path="/konakartadmin" docBase="/opt/tomcatX/vhostwebapps/konakart/konakartadmin" debug="0" reloadable="true"/> <Context path="/birt-viewer" docBase="/opt/tomcatX/vhostwebapps/konakart/birt-viewer" debug="0" reloadable="true"/> <Logger className="org.apache.catalina.logger.FileLogger" prefix="mydomain.com." suffix=".txt" timestamp="true"/> </Host> Note: You can set path= to a value of your choice. In other words if you want your visitors to access KonaKart at yourdomain.com/store your path will be path="/store". Next you must add the mod_jk or mod_proxy balancer directives for the Apache web server. The directives must be entered in the Custom Settings area of your your Control Panel. DO NOT add these to the the Apache configuration file (httpd.conf). Go to your Control Panel > Site tab > Website Settings > Custom Settings tab and add the appropriate mod_jk OR mod_proxy_ajp directives below. mod_jk DirectivesIf you want to use mod_jk to have Apache send your KonaKart request to Tomcat please add the directives belowJkMount /konakart* ajp13 JkMount /konakartadmin* ajp13 JkMount /birt-viewer* ajp13 mod_proxy_ajp DirectivesIf you want to use mod_proxy_ajp to have Apache send your KonaKart requests to Tomcat, please add the directives below.ProxyPass /konakart ajp://localhost:8009/konakart ProxyPass /konakartadmin ajp://localhost:8009/konakartadmin ProxyPass /birt-viewer ajp://localhost:8009/birt-viewer Note: If the path in your context is something other than /konakart, /konakartadmin and /birt-viewer make sure the correct values are in the directives above. For example if your path is path=/store then the directives for mod_jk and mod_proxy_balance will look like the following. Jkmount /store* ajp13 or ProxyPass /store ajp://localhost:8009/store |
Accessing the Administrative Interface
The default username and password for the KonaKart administrative web interface can be found in your Control Panel. Login and go to the System tab. Click on All Applications, then click on KonaKart. In the description you will see the default username and password. To change the username and password please take the steps below.
1. Log into the administrative interface with the default login information.
2. Click Configuration > Configuration Files
3. Click "KonaKart Admin Properties File" then click Edit
4. In the file look for the lines below and change the values to the username and password of your choice.
A. konakart.admin.user=xxxxxxxx
1. Log into the administrative interface with the default login information.
2. Click Configuration > Configuration Files
3. Click "KonaKart Admin Properties File" then click Edit
4. In the file look for the lines below and change the values to the username and password of your choice.
A. konakart.admin.user=xxxxxxxx
B. konakart.admin.password=xxxxxxx
Click Save > Reload
Stop and Start Tomcat from the Control Panel.
Stop and Start Tomcat from the Control Panel.
Configuring KonaKart Report Settings
The KonaKart report settings can be changed in the administrative interface with the instructions below.
1) Login to the administrative interface
2) Click configuration > Reports Configuration and change the value of the fields below as follows:
A. Report definitions base path: /opt/tomcatX/vhostwebapps/konakart/birt-viewer/reports/ where X is the version of Tomcat you have installed.
B. Report viewer URL: http://your-domain.com:8080/birt-viewer/frameset?__report=reports/. 8080 will not be required if mod_jk or mod_proxy_ajp has been configured.
C. Status Page Report URL: http://your-domain.com:8080/birt-viewer/run?__report=reports/OrdersInLast30DaysChart.rptdesign. Again 8080 will not be required if mod_jk or mod_proxy_ajp has been configured.
1) Login to the administrative interface
2) Click configuration > Reports Configuration and change the value of the fields below as follows:
A. Report definitions base path: /opt/tomcatX/vhostwebapps/konakart/birt-viewer/reports/ where X is the version of Tomcat you have installed.
B. Report viewer URL: http://your-domain.com:8080/birt-viewer/frameset?__report=reports/. 8080 will not be required if mod_jk or mod_proxy_ajp has been configured.
C. Status Page Report URL: http://your-domain.com:8080/birt-viewer/run?__report=reports/OrdersInLast30DaysChart.rptdesign. Again 8080 will not be required if mod_jk or mod_proxy_ajp has been configured.
Common Issues and Solutions
Please visit the KonaKart forum at http://www.konakart.com/forum/index.php
Links to other information
KonaKart Home Page: http://www.konakart.com
eApps Tomcat User Guide: http://support.eapps.com/hsp/tomcat
eApps Tomcat User Guide: http://support.eapps.com/hsp/tomcat