What platforms are supported ?
How do I install KonaKart ?
Which version of Java do I need ?
I already have an osCommerce database, can I use that for KonaKart ?
How do I upgrade the database between releases of KonaKart ?
How do I start the KonaKart Server ?
How do I shut down KonaKart ?
What are the Default Admin App Credentials ?
Where do I define the database parameters ?
Notes for Oracle and DB2
Notes for PostgreSQL
Notes for MySQL
How do I run the Admin App?
Known Problems
What platforms are supported ?
Currently KonaKart can be installed on Linux, Unix, or Windows XP/2003/Vista. It has been successfully installed on other platforms including Mac OS using the manual installation.
Please contact us if you would like to see KonaKart support running on another platform.
How do I install KonaKart ?
You will need:
- a Java v5 runtime environment
- a database loaded with the KonaKart tables
- KonaKart itself
Install Java v5
KonaKart requires the Java 2 Standard Edition Runtime Environment (JRE) version 5.0 or later.- Download the Java 2 Standard Edition Runtime Environment (JRE), release version 5.0 or later, from http://java.sun.com/j2se.
- Install the JRE according to the instructions included with the release.
- It is not essential for you to set JAVA_HOME, or JRE_HOME globally. The installation wizard will set up KonaKart to run with the selected java location regardless of the global settings of JAVA_HOME or JRE_HOME.
Create a Database
KonaKart needs a JDBC-compliant database. For the downloadable osCommerce-compatible version of KonaKart you must use either MySQL (with the InnoDB engine to get support for transactions), PostgreSQL, Oracle, DB2 or MS SQL Server but if you would like KonaKart to be supported on any other database please contact us. MySQL works well with KonaKart and is free so this makes a popular choice. You can obtain MySQL from http://www.mysql.com/.Check the specific notes for each database to verify that the database you plan to use is fully supported (see below in this FAQ) or whether you might have to take a few additional manual steps to load the database objects.
Since KonaKart is compatible with the osCommerce database, if you already have an osCommerce database you can use that for KonaKart. If this is the case you only need to run a small supplementary SQL script for KonaKart (see below). (If you wish to keep the data in your existing osCommerce database (as you probably will do) take care not to run the full database initialisation script which will re-create all your tables).
Once the database is installed, create a new database user for KonaKart then either run the installation wizard which will (optionally) load up the database ready for using KonaKart, or if you prefer, execute the SQL script appropriate for your chosen database manually. The database initialisation scripts are provided for all supported databases under the database directory under your KonaKart installation directory.
If you already have an osCommerce database
If you are already an osCommerce user you can use the database that you have already created. The advantage of doing this is that you will not have to load up all of your configuration parameters again (especially the product catalog!). All that you have to do in this case is run a small supplementary SQL script, appropriate for your database platform (this will almost certainly be MySQL as osCommerce is currently only supported on MySQL). The supplementary script can be found under the database/MySQL directory under the KonaKart home directory (i.e. where you installed KonaKart).Note that executing this supplementary script should not break your current osCommerce system from working, but we only recommend that you run it on a test database and not a production database. The SQL run for KonaKart does not change any osCommerce database values, it merely adds a few configuration parameters, specific to KonaKart.
Note that if you wish to keep the data in your existing osCommerce database (as you probably will do) take care not to run the full database initialisation script which will re-create all your tables.
How do I upgrade the database between releases of KonaKart ?
Starting with the upgrade from KonaKart v2.2.0.0 to v2.2.0.1 there will always be an upgrade script provided that can be run on your database without risking the loss of your existing data (although it is always recommended to backup your database on a regular basis). The upgrade script will apply all the database changes that are required to upgrade a database being used for a specified KonaKart version to the next.As an example a script called upgrade_2.2.0.0_to_2.2.0.1.sql is provided that will upgrade your database being used on a KonaKart v2.2.0.0 system to one suitable for a KonaKart v2.2.0.1 system.
If you chose to skip KonaKart releases for whatever reason, you will have to apply the upgrade scripts for all intermediate releases - all upgrade scripts are planned to be shipped with all future releases.
Another option is to run the full database creation script (see above) which is always provided for every release. Note that this has the disadvantage of clearing away all of the data you may have set up for your KonaKart store (eg. your special configuration data, your catalogs etc) so will probably not be the preferred option for existing storekeepers.
Install KonaKart
Once you have java v5 installed and a database (either pre-loaded with all the necessary tables etc or ready to be loaded), you are ready to install KonaKart itself. To do this, download an installation kit, compatible with your chosen platform, and follow the installation instructions below for your platform :Note that if the GUI or silent installers do not work on your platform you should download the zip version of KonaKart and follow the manual installation instructions.
Under Windows:
Run the set-up program that executes a graphical installation wizard - see Graphical Installation Wizard below. (You can use the "Silent Mode" installation if you prefer, but the graphical version is probably easier if you're installing for the first time).Under Linux/Unix:
Create a terminal session on your machine and enter the following: (You may prefer to use commands to do the same thing from your X-desktop if you have one installed).chmod +x KonaKart-2.1.0.0-Linux-Install
(replace 2.1.0.0 with the version you have downloaded)
./KonaKart-2.1.0.0-Linux-Install
If you have a graphical environment on your Linux/Unix machine you will be able to run the GUI. In which case see the Graphical Installation Wizard below (identical steps to the Windows installation).
If you don't have a graphical environment you will see this warning message:
./KonaKart-2.1.0.0-Linux-Install
This program must be run in a graphical environment
or in silent, unattended mode (with the -S option).
Silent Mode
When running in "silent" (-S) (or "unattended") mode you are able to specify configuration parameters on the command line, for example:
./KonaKart-2.1.0.0-Linux-Install -S -DDatabaseType mysql
-DDatabaseUrl
jdbc:mysql://localhost:3306/mykkdb \
-DDatabaseUsername kkdbusr \
-DDatabasePassword ikk8271
Silent Mode Parameters
The following parameters can be added to the command line, as in the example above, to specify default values for KonaKart at installation time:| Parameter | Default Value | Explanation |
| DatabaseType | mysql | mysql, postgresql, db2net, oracle, mssql |
| DatabaseUrl | jdbc:mysql://localhost:3306/dbname?zeroDateTimeBehavior=convertToNull | Database URL |
| DatabaseUsername | root | Database User's Username |
| DatabasePassword | Database User's Password | |
| DatabaseDriver | com.mysql.jdbc.Driver | Database Driver |
| mssqlDBO | dbo | Database Owner (only used by MS SQL Server) |
| InstallationDir | Windows: C:\Program Files\KonaKart *nix (as root): /usr/local *nix (as user): ~/konakart |
Installation Directory |
| DBLoad | 0 | 1=Load DB 0=Do not Load DB |
| JavaJRE | The Java runtime location | |
| PortNumber | 8780 | KonaKart Port Number |
Graphical Installation Wizard
This shows a typical installation that uses the wizard:Either double-click on the installation setup program (either KonaKart-2.2.0.4-Windows-Setup.exe on Windows, or KonaKart-2.2.0.4-Linux-Install on Linux - or respective later version numbers) or run it from a command shell. You are first presented with this small window which allows you to confirm that you wish to proceed with the installation:
Click on Yes to continue to:
Check that you have the correct version number and click on next to get to the next screen. Note in passing the email address for support questions. Please contact us and / or search the forum if you have any difficulties at all with the installation and we will endeavour to help you as soon as possible.
Please read the license agreement carefully and if you are happy to do so under the terms of the agreement, click on the "I accept the terms of the license agreement" bullet and click next to continue. If you are not prepared to accept that license agreement please quit the installation at this point.
Click on next to reach:
This is where you specify where you want KonaKart to be installed. On Windows this defaults to "C:\Program Files\", on Linux this is the user's home directory (if the user is not root) or "/usr/local" (if the user is root). This can be specified in the silent mode of on the command line of the GUI version using -DInstallationDir.
It is recommended that you accept the default location, but not essential.
On clicking next you reach:
Here you have to confirm or specify the location of the java runtime environment. The wizard will try to find this for you but it is not always successful. In the cases where it isn't successful you will have to enter the location manually. If you have installed java v5 in the default location or it appears in your environment's path, the wizard should find it for you.
Click on next to get to:
This is where you define the port number that KonaKart will run on. Actually, KonaKart uses Apache Tomcat, so this is the port number that Tomcat is configured to run on. Whilst it is certainly possible to choose another port, it's advisable to accept the default which is 8780. KonaKart will not start up if another application is using the port you select, so make sure the port you select here is not currently being used.
Clicking next moves you on to:
This is your final chance to check your settings before copying the files into position.
Clicking next will start the process of copying the KonaKart files into position as can be seen on the next screen:
After about a minute or so the file copying will have completed and you are presented with this screen to choose the Database Type that you wish to use:
Choose your preferred database type. You must set up the database yourself - this is not done as part of the installation (see database creation).
Click next to continue to :
It is very likely that you will have to modify values on this screen. You have to define the database connection parameters to KonaKart for the database that you created earlier (see database creation)
KonaKart currently supports MySQL, PostgreSQL, Oracle, DB2 and MS SQL Server and includes all the JDBC driver jars required to access these.
Note that you must append "?zeroDateTimeBehavior=convertToNull" to your Database URL if you're using MySQL.
After clicking next, the installer wil check the database connection and report the results on the next screen as follows. For an unsuccesful connection you will see something like this:
At this point you can go back and modify the database connection parameters and then click next to try the database connection test again. If successful you will see a screen like this:
If the database connection fails, you can choose to click on next and finish the installation without executing the database initialisation. Normally, for a fresh install, you are advised to correct your database connection parameters so that you see a successful database connection message, then proceed to the database initialisation screen which looks like this:
Note that the default is that the database initialisation is NOT executed. To execute it you must click on the checkbox and click next to reach the next step.
Be warned that the database initialisation script will drop and re-create all the KonaKart tables and populate them with a default set of starting data. This default starting position is ideal for users who are setting up KonaKart for the first time but this is probably not what you want to do if you already have a KonaKart database with a product catalog loaded for your store.
Note that for users who already have an existing KonaKart database (or an osCommerce database) there may be additional steps to ensure your database is suitably-configured for the version of KonaKart that you're installing. See Database Creation.
If you do not check the 'Create the tables..' box then click next you would jump to the final page of the wizard.
Alternatively, if you do check the 'Create the tables...' box then click next, you will be presented with a screen that shows the loading of the database initialisation script in a scolling window which will look like this:
In the above example the script ran successfully (see last comment "SQL executed successfully" in the scrollable text area). If the script does not run successfully you will see the error message in this window.
After clicking next you reach the following screen:
Finally you are congratulated on a successful installation on the final screen of the wizard:
Finally you have the option to create a desktop icon (which is defined to start the KonaKart server and launch the GUI) and launch the application immediately after the installation has completed. The "Launch KonaKart" option executes a startup of the KonaKart server and then launches the default browser to show the KonaKart UI, and the KonaKart Administration Application.
Starting up KonaKart
The KonaKart Server can be started by executing the following commands:
%CATALINA_HOME%\bin\startkonakart.bat
(Windows)
${CATALINA_HOME}/bin/startkonakart.sh
(Unix/Linux)
On Windows there are also shortcuts created under the KonaKart program group that can be used to:
- start the KonaKart Server
- stop the KonaKart Server
- launch the KonaKart application in your default browser
- launch the KonaKart Administration application in your default browser
- uninstall KonaKart
Shutting Down KonaKart
KonaKart can be shut down by executing the following command:
%CATALINA_HOME%\bin\shutdownkonakart.bat
(Windows)
${CATALINA_HOME}/bin/shutdownkonakart.sh
(Unix/Linux)
On Windows a shortcut is created under the KonaKart program group that can be used to shut down the KonaKart server.
What are the Default Admin App Credentials ?
Three users are created with different roles assigned.| username | password | roles |
| admin@konakart.com | princess | KonaKart Super-User |
| cat@konakart.com | princess | KonaKart Catalog Maintainer |
| order@konakart.com | princess | KonaKart Order and Customer Manager |
Choose new usernames and passwords to secure the KonaKart Administration Application at the earliest opportunity.
The default users and roles are set up as examples of typical configurations of the role-based security system. You may wish to add new Admin users or adjust some of the roles as you see fit. The three users above should give you a few ideas about how the system can be configured.
The three users above are defined as "Admin Users". Note that "Admin Users" can actually log in to the KonaKart store using the same credentials. It doesn't work the other way around however: "Non Admin Users" cannot log into the Admin Application.
Although it's not recommended, it is possible to disable security completely if you wish. To configure this, see the comments inside the konakartadmin.properties file which can be found under the konakart installation directory at:
webapps\konakartadmin\WEB-INF\classes\konakartadmin.properties
(There are a number of additional configuration options that you can adjust to modify the behaviour of the KonaKart Administration Application - please refer to the comments in in the above properties file for details).
DEFINING THE DATABASE PARAMETERS
You define the database parameters in two configuration files underneath your konakart installation directory at:
webapps\konakart\WEB-INF\classes\konakart.properties
and
webapps\konakartadmin\WEB-INF\classes\konakartadmin.properties
(Therefore, the default on Windows will be at C:\Program Files\KonaKart\webapps\konakart\WEB-INF\classes\konakart.properties).
Inside these files you will find: (the url parameter is broken into two lines for readability only - you should keep it on one line)
# -------------------------------------------------------------------
# D A T A B A S E P R O P E R T I E S
# Database Connection Parameters Set by Installer on 3-Sep-2006
# -------------------------------------------------------------------
torque.database.default = oscommerce
torque.database.oscommerce.adapter = mysql
torque.dsfactory.oscommerce.connection.driver = com.mysql.jdbc.Driver
torque.dsfactory.oscommerce.connection.url =
jdbc:mysql://localhost:3306/mydb?zeroDateTimeBehavior=convertToNull
torque.dsfactory.oscommerce.connection.user = root
torque.dsfactory.oscommerce.connection.password =
-------------------------------------------------------------------
Leave the torque.database.default equal to oscommerce.
You need to set the five parameters appropriate for your environment:
- torque.database.oscommerce.adapter (either "mysql", "oracle", "db2net", "mssql" "postgresql")
- torque.dsfactory.oscommerce.connection.driver (All JDBC drivers for the supported databases are on the default classpath)
- torque.dsfactory.oscommerce.connection.url (keep the value on the same line after the equals sign)
- torque.dsfactory.oscommerce.connection.user
- torque.dsfactory.oscommerce.connection.password
NOTE FOR DB2 and ORACLE:
In addition to the settings above, you have to set the validationQuery for DB2 and Oracle slightly differently to the others, as follows. This section is defined just below the database parameter definitions in the two properties files (konakart.properties and konakartadmin.properties):
# The SQL query that will be used to validate connections from
this pool before
# returning them to the caller. If specified, this query MUST be an SQL
SELECT
# statement that returns at least one row.
# Recommended settings:
# for MySQL/PostgreSQL/MS SQL use: SELECT 1
# for DB2
use: SELECT 1
FROM sysibm.sysdummy1
# for
Oracle
use: SELECT 1 from dual
torque.dsfactory.oscommerce.pool.validationQuery=SELECT 1 from dual
Notes for PostgreSQL
Note that the SQL that is optionally run at installation time uses the "DROP TABLE IF EXISTS TABLE-NAME;" command. This works fine for PostgreSQL 8.2 and above (which support "IF EXISTS") but not for earlier versions.This is only a problem during the installation process; KonaKart performs well on versions of PostgreSQL prior to 8.2. To workaround this problem, for example for PostgreSQL 8.1, you will have to edit the database/konakart_demo.sql file and remove all the "DROP TABLE" commands then run this SQL manually. In addition to modifying the "IF EXISTS" syntax you will also have to add SQL statements to create sequences for all the SERIAL primary keys. For example, for the counter table, which is created like this:
CREATE TABLE counter (
counter_id SERIAL,
startdate char(8),
counter integer,
PRIMARY KEY (counter_id)
);
You have to create the SEQUENCEs with these conventions:
CREATE SEQUENCE <table>_<SERIAL column>_seq
for example:
.. for the counter_id column in the counter table above, you need to create a SRQUENCE like this:
CREATE SEQUENCE counter_counter_id_seq
INCREMENT 1
MINVALUE 1
MAXVALUE 9223372036854775807
START 1
CACHE 1;
Another, preferable, alternative is to update to the latest version of PostgreSQL and run the standard GUI installation and have all the data loaded by the installer.
Notes for MySQL
Note that the SQL that is optionally run at installation time uses the "DROP TABLE IF EXISTS" syntax. This works fine for MySQL 5 and above, but not on MySQL 4.1.This is only a problem during the installation process; KonaKart performs well on MySQL 4.1 but you have to modify the konakat_demo.sql file and run it yourself manually. You have to edit the database/konakart_demo.sql file and remove all the "DROP TABLE" commands then run this SQL manually. After successfully running this SQL you will be able to run KonaKart with MySQL 4.1.