Prerequisites

The following perl modules are required to run Common Cents. The easiest way to install them is through CPAN. As the root user on the machine you are installing Common Cents on, type the following command to install through CPAN:

perl -MCPAN -e "install [module_name]"

Required Modules:

DBI (with MySQL DBD) (Usually installed by default on Redhat and Fedora)
CGI (Also normally installed by default)
Number::Format
Net::SMTP
MIME::Lite
Date::Calc
PDF::Create
GD::Graph

(Note about GD::Graph. It was the hardest module to install and in some cases I wasn't able to get it to install on certain versions of Redhat. Make sure that you have version 2 or greater of gd (type rpm -qa | grep gd to find out). You will also need gd-devel, freetype-devel, libpng-devel, and libjpeg-devel to successfully install GD::Graph module. If you are running apt, the easiest way to get the development libraries is by typing the following command: apt-get install [rpm file] where "rpm file" is either "gd-devel", "freetype-devel", "libpng-devel", or "libjpeg-devel". When installing the module, you are asked if you want various types of support. The last time I tried to install GD::Graph, I couldn't successfully get XPM support to be included. It is not needed for Common Cents graphs and so you can indicate "No" without loosing any functionality)

Setting up the Database

Common Cents was written to run on MySQL. Before configuring your scripts, you need to have a new empty database setup as well as a user with access to the new database. If you are using phpMyAdmin, the easiest way to do this is to create a new database (call it ccweb) from the main page of your server. Then click on the privileges link. Create a new user (call it ccuser). Make sure to make the host local (this is assuming that the database will be on the same server the application is running on. If not, then provide a hostname or set to "%" for any host). Leave all the global rights unchecked. Then go ahead and create the user. Once the user is created, return to privileges and grant all rights to the new ccweb database.

Installing the Scripts

• Start by downloading the latest version of Common Cents from sourceforge.net. Look for a tar file named ccweb-[version].tar.gz


• Copy the file to the document root of your webserver and run the following command to extract the files from the archive:
  
  tar -xzf ccweb-[version].tar.gz.
  
  This will create a new directory off the root called ccweb. I will refer to this directory as the application root directory from now on.


• Under the application root directory, there will be an sql directory. From inside that directory, run the following command to setup the database tables and initial data:
  
  mysql -u [db_user] --password=[db_pass] --exec="source db_setup.sql" [db_name]
  
  where "db_user" (ccuser), "db_pass", and "db_name" (ccweb) are the ones you chose under the Setting up the Database section.


• Now go back to the application root directory and then enter the lib directory. You will need to edit the config.pm file next. The variables in this file are divided into three sections. The top section are variables you are required to edit before Common Cents will work. The second section are variables that you can change if you want to, but don't need to. And the final section are variables that you shouldn't touch. Let's talk about each of the required variables now.
  
  base_url The base_url variable contains the URL that points to the ccweb directory on your web server. Make sure that it starts with either "http://" or "https://" and it does not contain a trailing slash (/).
  
  mailhost The mail host variable is the server or IP address of the machine on your network serving as an SMTP mail relay. This is used for payment reminders and invoice delivery as well as any other outgoing messages and requests.
  
  db_name This is the name of the database (usually ccweb) where the Common Cents tables are located.
  
  db_host This is the hostname or IP address of the machine where the database is located. If the database is located on the same machine as the application, then leave this value blank.
  
  db_user This is the database user name (usually ccuser) which has been given full rights to the database identified by the db_name variable.
  
  db_pass The is the password used in conjunction with the user to connect to the database.


• Under the application root directory there is also a directory called cron. You need to move the agent.pl file to somewhere outside of the documentRoot for the webserver so that it can't be visible on the web. You need to also edit line 28 of that file to point to the location of the lib directory under the application root directory.
  
  Example: My application root directory is located at /var/www/html/ccweb. I am going to create a new directory under /var/www called cron and copy the agent.pl file to that location. Then I'm going to remove the original agent.pl file from the /var/www/html/ccweb/cron directory. Now I will edit the agent.pl file and change line 28 to read the following:
  
  use lib ( "/var/www/html/ccweb/lib" );
  
  Once the file has been moved and edited, then you will need to create a cron job to run this script every morning.

Apache Considerations

In order to run Common Cents in the default configuration, you will need to ensure that the following Apache settings are turned on or set correctly in the httpd.conf file (you will need to be root user to update this file). Check to see that the following values are set:

Make sure the tag for the document root (typically for "/var/www/html" for Redhat) has the following Options list:
Options Indexes FollowSymLinks ExecCGI (ExecCGI is required to run cgi scripts in a non-cgi-bin directory)

Locate the line that starts with DirectoryIndex. Make sure that index.cgi is included in the list of names following it.

Make sure that AddHandler cgi-script .cgi is not commented out (Does not have a pound (#) sign in front of it).

If you ended up having to make any changes to the apache configuration, make sure to restart httpd before you attempt to run any scripts

Admin Login, Master Accounts and User Setup

Once the database is setup and the config.pm script is modified, you are ready to login to the system. Set your browser address to the base_url defined in the config.pm file. You can create a shortcut or set a bookmark to remember this. This will always be your starting point. You should be taken to a login page. Login as user admin with a default password of master. The admin user is the only user with access to maintain master account definition records and setup new users. If you click on the Utilities tab, you will see these options along with other normal user options as well.

Common Cents comes with a default set of master account records pre-installed. This is to give you an idea of how accounts are setup. In Accounting 101, you learn that there are 5 types of accounts. Assets, Liabilities, Capital, Income, and Expense accounts. They generally are listed in that order with each type using a specific number series. Asset accounts generally start with 1, Liability accounts start with 2, Capital 3, Income 4, and Expense 5 or greater. The master list of accounts is global for all users on the system, however, not every user has to use all defined accounts in their own ledger. One other feature is that account numbers can be changed later on without effecting transactions or balances. The account number in reality is the same as the account description. The account definition records are actually indexed and related on an internal key value that doesn't mean anything to the normal user. This means that an administrator can change or renumber accounts for all users on the system without effecting balances or transactions already on the system for those users.

Users are setup by an administrator in the User Maintenance module. The admin user can setup new users, reset the password of any user, unlock a locked account, and assign modules to users in user maintenance. When a new user is added, that user is assigned the Common Cents module by default (which cannot be removed from any user). Additional modules such as "Invoice Cents" and "Music Cents" can be added to a user's profile so that user will be able to access that module when logged into "Common Cents".