<adam@onshored.com>
New York City
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/.
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:
Pentium 133 or above, 64 Megabytes or more of 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:
Sun Solaris 2.6
Sparc 20, narrow SCSI disk array
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.
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:
Where do you want the application files installed? By default, the application is installed in /home/httpd/html/timesheet, but this can be overridden in the Makefile or on the command line. Red Hat, and likewise Caldera users are safe with this default but Solaris and other systems probably need to change the APPROOT variable, depending on your web server configuration. In addition, there is the variable for IMAGE_DIR for where the images should be accessed from (not currently implemented yet).
What is the document root for the application? This is the relative URL. By default, the variable for this, TIMESHEET_URL is set to /onshore-timesheet. Please remember, this is the path to the application from the document root as defined in your webserver's configuration files. /onshore-timesheet may actually be /usr/local/etc/httpd/htdocs/onshore-timesheet on the server. The same is true of the variable IMAGE_URL, which is set to /images. This can be set to wherever you put images under the document root of the web server (this is not currently implemented).
Where do you want the configuration file installed? On most unix filesystem layouts, /etc is considered the normal place to drop configuration files. By default, onShore TimeSheet will install the configuration file, timesheet.conf, in a subdirectory called etc under the above directory you chose as the application's root. A link can later be made to /etc/timesheet.conf or as you please. The Makefile can be modified to suit your preference by changing the CONFFILE variable.
What is the name of the user id that the HTTP server is running as? By default this is set to nobody but you can override this on the command line by changing the WWWUSER variable in the Makefile.
If you're not sure, check in Apache's httpd.conf for the User setting. Other web servers may set this variable in other ways.
Where can a Perl library be added so Perl can find it? By default, this is set to /usr/lib/perl5/site_perl but can be overridden by changing the PERLINC in the Makefile. If you are not sure what Perl's default INC path is set to, simply run this on the command line:
# perl -e 'print join "\n", @INC'
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
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).
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:
PostgreSQL's postmaster isn't running
postmaster isn't configured to listen on a TCP port, or the same port you defined in onshore-timesheet.conf
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.
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.