Manual KwaMoja Installation

The installer is currently undergoing some major work, so for the moment it is advisable to install manually. This is a a tutorial on how to achieve this.

A manual installation consists of the following five steps:

1. Copying all the PHP scripts and include files to a directory under the web server document root directory.
2. Creating the database and populating it with initial data
3. Editing config.php for the database connection information and any other requirements
4. Logging into the system for the first time
5. Setting system parameters
6. Setting up company specific information in the system

Copying the PHP Scripts

The latest archive of the code can be downloaded from my GitHub site at https://github.com/timschofield/KwaMoja/archive/develop.zip

All files in the archive should be copied to a directory under the web server Document Root directory. This varies by web server and operating system, and you should refer to the documentation to find the location on your server.

Extract the archive into this location. A KwaMoja directory will be created in this location and all scripts and other directories will be copied to that directory.

Creating the Database

KwaMoja currently only works with MySQL or MariaDB database servers.

You need to know the user name and password for your database server. If you have not set these up the default is often:

user root
password “”

BUT … you should NOT use this account. You should set up another user for your MySQL installation and change the root password to something other than “”.

All instructions for using MySQL refer to the command line client that comes with MySQL. To run this under Windows a DOS box must be opened. The mysql.exe binary is located by default under C:\mysql\bin\mysql.exe. This would be the command line statement required to run the MySQL client. The options discussed below should be appended as required. There are a number of graphical clients for MySQL and if you prefer to use one of these you should be prepared to amend the instructions below appropriately.

From the MySQL manual (edited):

The MySQL root user is created as a superuser who can do anything. Connections must be made from the local host. NOTE: The initial root password is empty, so anyone can connect as root without a password and would have all privileges. Because your installation is initially wide open, one of the first things you should do is specify a password for the MySQL root user. You can do this as follows (note that you specify the password using the PASSWORD() function):

You can, in MySQL Version 3.22 and above, use the SET PASSWORD statement:

shell> mysql -u root mysql
mysql> SET PASSWORD FOR root=PASSWORD(‘new_password’);”

where ‘new_password’ is the new password you chose for the root user.

Also from the MySQL manual (edited):
Also, if you have changed the root user password, you must specify it for the mysql commands below. You can add new users by issuing GRANT statements:

shell> mysql –user=root -p ‘new_password’ mysql
mysql> GRANT ALL PRIVILEGES ON *.* TO kwamoja@localhost IDENTIFIED BY ‘some_pass’ WITH GRANT OPTION;”

Where ‘some_pass’ is a password of your choice for the new user ‘kwamoja’. Note that this user ‘kwamoja’ can only connect from the local machine so if the web server is on a different machine then the MySQL server you need to give privileges to connect from other computers. See the MySQL manual.

Innodb tables must be enabled in the MySQL server. These tables allow database transactions which are a critical component of ERP software. Innodb tables require some parameters to be set up in my.cnf. There are some examples in the MySQL manual under table types – Innodb tables.

If you have an account set up already in MySQL and Innodb tables enabled, then all you need to do is to run one of the sql scripts.

Two scripts are provided under the KwaMoja/sql/mysql directory (folder):

1. structure.sql As the name implies this file contains the structure of the database. Running this will just create all the necessary tables for KwaMoja to run. By default the database name will be KwaMoja. If you want a different database name, then change the ‘CREATE DATABASE’ and the ‘USE’ lines.
2. base.sql This script has only the basic data necessary to start a new company. If you wish to set up your company using the KwaMoja software, then this is the script to use. This creates a KwaMoja database and populates it with only the very basic starting data.

The files structure.sql and base.sql should be in the directory with all the PHP scripts. Change to the directory where the scripts are held or use the full path and enter:

shell > mysql –user=kwamoja –password=’some_pass’ < path_to_web_server/KwaMoja/sql/mysql/structure.sql

and

shell > mysql –user=kwamoja –password=’some_pass’ < path_to_web_server/KwaMoja/sql/mysql/base.sql

Modify the user entered here as ‘kwamoja’ to the user you created in MySQL for the purpose, and modify the password stated here as ‘some_pass’ to the password appropriate for the user. Also modify the path_to_the_sql_script to the appropriate path.

Editing config.php

config.php contains a series of user defined variables that determine how the system behaves. Critically it contains the host (computer name), username and password of the database connection required to connect to the database server. There is also an option to chose which type of database server is to be used. Currently there are only options for MySQL and MySQLi. There is no going forward without this data.

The default settings for config.php are in the file config.distrib.php and this file should be renamed config.php.

The default contents of the config.php file are as follows and must be edited in an editor of choice. Then, save config.php in the web directory where the scripts are located. Note, the system is continually evolving and may well have changed since this was written.

The file is well commented, with each setting having a detailed explanation. It is vital that at a minimum the database settings are changed to your own.

At this point you should also copy the contents of the companies/default/ folder into a new sub folder called companies/KwaMoja/ or whatever the name of the database you created above.

Logging in to the system

If you now point your web browser at the location you loaded the code you should see a login box looking like this:

To improve the look of this you can create a file companies/KwaMoja/Companies.php which looks something like this:

So that the company name will now appear in the login box. The user name and password combination will be admin/kwamoja. As soon as you login KwaMoja will insist you change this password to a more secure one. Once this is done the system will log you out, and you can log back in with the new password. You now have a working KwaMoja system

When you are back in, KwaMoja will take you through some steps to initialise important information, but I will go through this in a later blog.