onShore TimeSheet™ Installation Manual

Adam Di Carlo

onShore, Inc.

adam@onshore.com
  New York City

Greg Gallagher

$Revision: 1.18 $

Table of Contents
Introduction to onShore TimeSheet
What Do I Need to Run onShore TimeSheet?
Installing the onShore TimeSheet Application
Configuring Your Web Server and Database Server
Where To Go From Here

Introduction to onShore TimeSheet

onShore TimeSheet full timesheet management system. It is a collection of CGI SQL-embedded Perl scripts which offer a graphical interface to a relational database back-end. onShore TimeSheet enables employees or contractors who need to track their hours worked on a particular project for a client to use an intuitive front end to a database. They can log hours, search for hours logged to a client or clients during a certain time period, and change their entries. Supervisors have the ability to track their time and the total time spent on a project or logged by an employee and to approve the hours worked.

onShore TimeSheet was developed by onShore, Inc. and is used to track a large number of hours spent on clients and projects undertaken by the company. Because of onShore, Inc.'s belief in the Open Source movement, onShore TimeSheet has been released to the general software community free of charge under the conditions and terms of the GNU Public License. More information about the project and links to the mailing list and other documentation can be found at the project's main home page, http://www.onshore-timesheet.org/.


What Do I Need to Run onShore TimeSheet?

Operating Systems and Hardware

onShore TimeSheet uses a variety of utilities and tools, such as the Perl interpreter and PostgreSQL relational database management system, which should run on most flavors of unix and hardware platforms. However, since the onShore TimeSheet is in the beginning stages of wide-spread distribution, we are going to list what things are certified to work because they are what has already been used in production and extensive testing.

The general rule for hardware configuration is that whatever you feel comfortable with for decent web and database performance is an ideal configuration for onShore TimeSheet Any machine that Linux will run on will work, but keep in mind that the main components are a web server and a database back-end. The more memory you throw at both of those things, in general, the better they will perform. Also, since databases are usually pretty disk intensive, putting the database on a dedicated or less-used drive, separate from the web server and operating system will help performance. Here is what we certify will work:

  • Linux

  • Pentium 133 or above, 64 Megs+ memory, at least 2 drives. PostgreSQL's data storage should be on its own spindle and preferable spread across several different spindles using a RAID striping for maximum performance boost.

The following should generally work, in theory but are considered mostly untested and uncertified to work properly without more extensive testing:


Required Software

To run onShore TimeSheet you must have a HTTP server capable of basic authentication and CGI scripting. Any web server should work in theory. The database back-end currently must be PostgreSQL, but we hope to enable onShore TimeSheet to plug into any relational, SQL-compliant relational database management system. Here is a list of certified software to run onShore TimeSheet:

  • Apache HTTP Server version 1.3 and above

  • Perl version 5.004_04 and above

  • PostgreSQL version 6.4.2 and above. 6.3.x should work on most systems, but we recommend you upgrade to 6.4.2 as there are some issues with 6.3.x and creating users with "-" in the username, as some HTTP servers such the one in Debian's Apache distribution, configure the HTTP server to run as the userid "www-data", which createuser will error out on trying to create as a PostgreSQL user in 6.3.x; this can be worked around, but it is easier to just upgrade, especially as the PostgreSQL site itself recommends upgrading to 6.4.2 because of bugs in previous versions.

    You need to make sure that you also have the PostgreSQL/Perl modules, Pg.pm installed and on the standard Perl path.


Installing the onShore TimeSheet Application

The first thing to do it to identify answer the following questions before installing onShore TimeSheet from the source distribution. If you are running Debian GNU/Linux there is an onshore-timesheet.deb available. We hope to support other Linux and Unix packaging systems in the future, such as RPM and Solaris' pkg files. Make sure there isn't a maintained package available for your system before installing onShore TimeSheet from the source distribution. If there isn't, begin by answering these questions:

Before running 'make install' you need to make sure that PostgreSQL is running. On a Linux distribution that uses SysV style init scripts, Such as Debian and Solaris, the command to start will be along the lines of /etc/init.d/postgresql start. Red Hat puts init scripts under /etc/rc.d/init.d/

After the above is taken are of you can run 'make install' as the root user with the appropriate variables:

	# make install
      


Configuring Your Web Server and Database Server

After you have installed the onShore TimeSheet application, you must now configure your HTTP Server properly.

Be sure to have cgi execution enabled for the onShore TimeSheet installation directory. If you are running apache, you can do so by adding the following stanza to your access.conf (under RedHat Linux, /etc/httpd/conf/access.conf). Replace /timesheet with the path to the timesheet application.

<directory /timesheet>
Options +ExecCGI
AddHandler cgi-script .cgi
</directory>
      

PostgreSQL needs to be configured to listen on a TCP/IP socket in order for onShore TimeSheet to function properly. By default, Debian and RedHat do not have PostgreSQL configured to listen on a socket so you will need to enable it explicitly. In Debian, edit /etc/postgresql/postmaster.init, uncomment the PGALLOWTCPIP line and change the 'no' to 'yes' so it looks like this:

PGALLOWTCPIP=yes
      

To enable for RedHat the important line is in /etc/rc.d/init.d/postgresqlreads as follows:

su postgres -c '/usr/bin/postmaster -S -D/var/lib/pgsql'
      

Postmaster needs to be started with the "-i" switch to have it listen for IP connections, so modify accordingly:

su postgres -c '/usr/bin/postmaster -i -S -D/var/lib/pgsql'
      

For more details, see postmaster (1)


Where To Go From Here

You should now use the default username admin and password admin to get into the application. If everything is setup properly you should be able to access the onShore TimeSheet start page with your browser. The right frame should load with a default onShore TimeSheet banner and the left frame should load up with the action buttons, a blank Client list at the top left. If the left frame is grayed out and you get an error like the following:

Sorry I cannot complete your request:

   Cannot Connect to backend:
       localhost:5432:timesheet
       ERROR: connectDB() failed:
       Is the postmaster running and
       accepting TCP/IP(with -i)
       connections at 'localhost' on
       port '5432'?
      
You know that one or more of the following are true and where you should look to fix the error:

  1. PostgreSQL's postmaster isn't running

  2. postmaster isn't configured to listen on a TCP port, or the same port you defined in onshore-timesheet.conf

  3. The HTTP server's user id doesn't have permissions to access the timesheet database. Make sure the PostgreSQL user exists and is in the pg_shadow file.

Assuming you fix the error and both frames load up properly in your browser, you should now read the operations.html document to understand how to use the onShore TimeSheet application.

You should change the admin password as soon as possible by selecting the view/edit user icon. Type admin as the username, and when the details page comes up, change the n to a y to change the password, type in the new password for admin in both form fields, and hit update to change it. Still logged in as admin just repeat these steps for guest if you wish to change the password from the default guest to something more secure.