If you already have dotProject installed, you probably don't even need to skim this article, unless something has gone horribly wrong. In this article by Lee Jordan, we will cover the key information you need to know to successfully install dotProject, what to do if things are not working right, and how to avoid common pitfalls and hours of frustration.

This article will include:

• dotProject setup options including server, database, and browser issues
• Prerequisites for installation of the tool
• The process for control panels and browser-based installations
• Troubleshooting your installation

Installing dotProject is usually an automated process if your server and database are already installed and configured. dotProject is packaged with an installation wizard that walks you through the basic setup process. It is always wise to have an understanding of the process and the setup options before you begin.

Prerequisites

It is important to make sure that everything is ready and in place for dotProject to be installed. Let's go over what we need to have prepared for a successful installation of dotProject.

Before you Install

It seems redundant to review the requirements again, doesn't it? There are a few last-minute things to discuss, especially if a control panel installation is not possible. First, make sure that the software required to run dotProject is already installed. Installing a web server, MySQL, and PHP is beyond the scope of this book. There are many fine books and online materials that explain the installation of web servers, MySQL, and PHP in detail. The dotProject team recommends the following environment:

• Apache web server (version 1.3.x or 2.x).
• MySQL server (version 3.23.x).
• A downloaded copy of dotProject. 2.0.4 or later is ideal. The most recent stable release can be downloaded from SourceForge.
• MySQL should be set up first, so that a dotProject user can create temporary tables during installation. Specifically, the database user should have ALTER and DROP permissions.
• In the section on browser-based installation, we will go over how to deal with the config.php file. If your installation already contains a config.php file (not a config_dist.php file, etc.), then dotProject will assume you are trying to upgrade.

Your PHP installation should have register_globals set to OFF in order for dotProject to run in an optimized and more secure mode. The dotProject installer automatically detects the state of register_globals. dotProject will work with register_globals set to ON, but it is not recommended.

LAMP, WAMP, or WIMP?

There are several key requirements to run dotProject. You must have an active web server running PHP and MySQL, and an Internet browser. There are three main web-server setups that people running dotProject use. Which one you pick depends on what you already have and whether you have a preference for one over the other. If you use an Internet Service Provider (ISP) you may not have a choice on which to use.

• LAMP : Linux, Apache, MySQL, PHP
• WAMP : Windows, Apache, MySQL, PHP
• WIMP : Windows, IIS, MySQL, PHP

LAMP is the most popular in the open-source community. Using LAMP provides an entirely open-source environment.

Web Server

Most web servers used today are either Apache or Microsoft IIS. Apache version 1.3.x or 2.x should be used. Your ISP or that clever person in the IT department knows which one your organization is using. There are always exceptions, so check the dotProject forums if you are using a different web server.

Apache is the preferred environment for running dotProject.

PHP

To install dotProject 2.0, you must be using version 4.1 or higher of the very popular online programming language PHP. If you are using an Internet Service Provider, check your service details to see if PHP is provided. PHP can be downloaded from http://www.php.net/downloads.php. PHP 4.46 is the last stable version of PHP 4. PHP 5 is not recommended for use with version 2.0.4.

MySQL

dotProject uses the MySQL database system. You will need to have it installed before you begin as well. Version 3.23.x is recommended for use with dotProject. MySQL can be downloaded from http://www.mysql.org/downloads/. The dotProjectteam recommends that MySQL version 5 and above should not be used with version 2.0.4 of dotProject.

The recent release of dotProject, version 2.1.0-rc 1 has been made more compatible with PHP 5 and MySQL 5; however, the changes incorporated does not take care of this completely. The features of this release are discussed in http://docs.dotproject.net/index.php/What's_New_-_2.1.0_-_rc1.

Windows

Using a bundled combination of PHP/Apache/MySQL is the best way to go if you do not already have them installed. This will save you the time and headache of installing them one at a time. The dotProject volunteers list the Apache2Triad available at http://apache2triad.sourceforge.net. Since there are limitations of dotProject being compatible with PHP5, version 1.2.3 is the download that is advisable.

Browser

dotProject works best with browsers that support cascading style sheets (CSS) and JavaScript. JavaScript and cookies should be turned on for full functionality. Most recent browsers such as Internet Explorer (version 5.5 or better), Mozilla 1.2, Netscape 7.x, and Firefox will work just fine. dotProject's PNG image files with alpha-transparency render best in Internet Explorer 6.0 and above. Internet Explorer 7 provides increased support for PNG image files.

Mail Server

As of version 2.0, sending mail is not a requirement. Administrators can set up the outgoing mail in the Administration panel.

Fonts

TrueType fonts are used for JpGraph, which is in turn used by the Gantt charts module. Most of the fonts JpGraph uses should already be installed on your system. All the fonts are not provided with dotProject because some of them have very specific licenses. If the Gantt charts module is insisting that font files are missing and you don't already have a spare copy of the files, search SourceForge or another reliable site for available fonts.

Memory Limit

The Gantt charts module can eat up your allocated memory. If the Gantt charts won't appear, and there is no error, chances are, you've reached your memory limit as set in the php.ini file. If your service is hosted, you will need to talk to your Internet Service Provider about increasing the memory limit set in your php.ini file.

Installation

There are two methods of dotProject installation:

• Online control panel installation
• Browser-based installation

The most recent versions of dotProject, 2.0 and later, are not meant to be manually installed. The online control panel method is very simple and usually takes between five and ten minutes. The browser-based installation generally takes a little longer, roughly ten minutes to an hour.

Which should you choose? If you already have an ISP who hosts your domain, they probably already provide you with an installation script for dotProject using one of the popular online control panels such as cPanel or Plesk. If they do not have the script available, they may be willing to install it for you if you make the request. dotProject can also be installed using a browser-based installation wizard. I recommend the online control panel installation for people who want a quick installation or are not technically inclined. The browser installation method is best for IT administrators or those who are comfortable installing web applications. If your only choice is a browser installation, don't worry; we will walk through one later in this article.

Backup First

It is always smart to take back up of any crucial files or databases that might be affected by a new installation. Always have a backup plan when a new installation is about to be performed.

Installing with an Online Control Panel

Most control panel installations can be completed in a few steps. Be sure to write down or otherwise make a note of any file, folder paths, or other crucial information as you go. We will walk through a control panel installation using cPanel/Fantastico. If you have never used cPanel before, this is a great opportunity to get your feet wet. Your ISP should have provided you with a link to your cPanel when you first setup your service. You will need a user name and password provided by your ISP to log in to cPanel. Once you are logged in you will see a screen with icons for different online tools.

1. Log into your cPanel control panel.
2. Select Fantastico (double mouse-click). The Fantastico icon is usually located at the bottom right corner of the screen.
   
3. Scroll down the Fantastico screen until the Project Management category appears.
   
   Left mouse-click on dotProject. There will be a short description about dotProject. Make a note of the version of dotProject available. The latest stable installation should be listed. The version of dotProject is in parenthesis by the new installation link. We will be using version 2.0.4 in the examples.
4. Click on the New Installation link to begin the installation process.
   
   Type in the name of the subfolder, where your dotProject installationshould be installed. If you leave it blank, then dotProject will be installed in the root folder of the URL path. For example, if I had left the folder field blank, the install tool would have placed the dotProject files directly in the public_html folder of www.leesjordan.net. I do not recommend leaving the folder field blank unless you already have a special URL set aside or are using a sub-domain.
   This article has been extracted from: Project Management with dotProject: Implement, Configure, Customize, and Maintain your DotProject Installation
   

   A complete beginner’s guide to every aspect of setting up and administering your dotProject installation Install and use the dotProject project management system Customize and extend dotProject Work with reports and Gantt charts Configure dotProject for LDAP authentication and PostNuke Customize dotProject to blend with your corporate sites For more information, please visit: http://www.packtpub.com/dotProject/book

   
   Enter the username for your dotProject admin, and the Password. You can add more administrators after dotProject is installed. Choose the username carefully. It is very difficult to change it.
5. Enter the email address of the dotProject administrator. A copy of the installation information will be sent to this email address.
6. Type the first and last name of the administrator.
7. Click the Install dotProject button when you are ready to continue.
8. The second installation screen gives you confirmation of the installation process so far. You should see information about your dotProject database, your subdirectory folder or other location where dotProject is being installed, and the URL from which dotProject will be accessed. Click the Finish installation button for the final installation screen.
   
9. The first thing you should see on the final installation screen is information about your config.php file and data.sql file. They should both have been successfully configured. The username and password  chosen on screen 1 should be listed again. Make note of them now if you haven't already. The administrator URL, which in this case is the same as the URL everyone will use, is displayed as well. The option to email a copy of the installation information is available. It is best to go ahead and send this information to a stakeholder or an alternative email address for backup purposes. If you choose not to send the information to another email address, then this is your last screen. Your installation process is done.
   
   An email confirmation screen will be displayed, after sending installation information to an additional email address.
   
   
10. Now it is time to check the URL where dotProject was installed and to make sure it is up and running. Type the URL into the browser. The login screen should appear.
    
    

Browser-Based Installation

How long will it take? A standard installation should take approximately 10 minutes to an hour. Does this seem like a large range of time? If things go well, the installation will go quickly. If corrections have to be made, it will take a little longer. To prepare for installing dotProject, you will need:

• The latest stable version downloaded from SourceForge either as a tar.gz or zip package at http://sourceforge.net/projects/dotproject /.
• A web server as described earlier in this article.
• PHP 4.4 or above (but not 5) already installed on your server. If you have PHP 5 or greater, visit the dotProject forums if you run into any problems.
• A database ready for your dotProject installation, preferably MySQL.
• An Internet browser such as Firefox or Internet Explorer.

Carefully follow the instructions for installing PHP and a database on your server if they are not already provided by your service provider. If you do not know what version of PHP you have, you should be able to find out by running a PHPInfo() script. Be sure to delete the script after you have used it. Visit php.org to learn more about PHP if you are not sure how to do this.Database management and PHP information should be available on your control panel, if your ISP provides you with one. The database and PHP must be installed before trying to install dotProject.Hopefully no one has been scared off by the preparation necessary to manually install dotProject. Usually ISPs will already have PHP and MySQL available.We're going to walk through the installation using the zip file. Those of you who want to use the tar.gz version just need to unpack the tar ball where you want your installation to be. Why are you advanced people even reading this article? Beats me. OK, while the gifted students show-off the rest of us will take it slow, and do the install step by step.

• Unpack the zip file. By default it has the thrilling name of dotProject. You can do better than that, can't you? Yeah, I'll wait while you go ask permission. After you've chosen a name for your installation, we're ready to begin. Now for the easy stuff.
• Fire up your FTP program and place the folder where you need it to go. If you are using a sub-domain, then you can install directly underneath it. If you are using a subfolder for your installation, place it under the public_html folder. Example: For this installation I am using the browserdp folder so the URL for my dotProject installation will be http://leesjordan.net/browserdp/.
• After the files are uploaded, point your browser at the installation subfolder. For this example it will be: http://leesjordan.net/browserdp/install/.
• The Check for Requirements screen will be displayed. It should look similar to the one displayed overleaf. Notice that under Database Connectors there are many red 'X's with the phrase Not available. It is a very long screen, and shows many optional configurations. The only requirement under Database Connectors is for the MySQL database to be prepared. If any of the mandatory requirements are not met, the installation will not be successfull. The config.php file can actually be uploaded after the installation is done. Click Start Installation when ready.


Enter the name of your database, the admin user, and the admin database user password. Click on install db & write cfg button. Be sure to have the drop existing database checkbox checked if you have a database you want to reuse. Make sure that the database name matches the one created in MySQL.

This article has been extracted from: Project Management with dotProject: Implement, Configure, Customize, and Maintain your DotProject Installation


A complete beginner’s guide to every aspect of setting up and administering your dotProject installation Install and use the dotProject project management system Customize and extend dotProject Work with reports and Gantt charts Configure dotProject for LDAP authentication and PostNuke Customize dotProject to blend with your corporate sites For more information, please visit: http://www.packtpub.com/dotProject/book

• If your database was successfully created, a green success message Database successfully setup will be displayed. The config file creation feedback may display an error message in red. This is normal.
  
  
• If the database setup was not successful, a screen like the following one will be displayed. Click the back button and double-check that you entered the database information correctly. Syntax is very important. The error screen looks like this:
  
  Still having trouble? See the troubleshooting section in this article for more help.
• Copy and paste the configuration file text into a text editor such as Notepad and save it as config.php. Upload the file to the server in the /includes/ subfolder of your dotProject folder.
  
  The config file's properties should be set so that it is writable to the server or 755 should do it. After you have uploaded the configuration file, it is time to take a look at the installed application.
• Open a new browser window and type the full URL of your dotProject installation. For this example we would type: http://leesjordan.net/browserdp/. A login screen like the one below should appear. The dotProject installation scripts create a default administrator username and password for you. Log in using the username as "admin" and the password as "passwd". You will want to change the password as soon as possible for security.
  
  You should now be finished with installing dotProject. The next section covers secure install with SSL, an optional method.

Secure your Installation with SSL

Sensitive information is stored by many organizations on websites. If your company stores and/or shares project information, it may be necessary to encrypt it. Banks, medical organizations, government entities, or any other groups who have proprietary or private information can benefit from secured sites.Using an SSL certificate will provide an encrypted, more secure way to access dotProject. Having an SSL certificate is not required for installing dotProject. Since there may be situations where a more secure installation is required, the dotProject volunteers have provided a code snippet for those using Apache servers. It is recommended that the SSL certificate be installed after dotProject. The installation of an SSL certificate is beyond the scope of this book.Digicert, an SSL certificate provider, has detailed instructions for installation of certificates on many different servers. Visit http://www.digicert.com/ssl-certificate-installation.htm for more details Your ISP may already provide secured hosting as part of your service package. Contact them for more information if you are not sure. If you see a /httpsdocs/ folder when you FTP into your domain, then a secure folder has already been prepared for you.The dotProject volunteers suggest that the following code be added to the end of the .htaccess file where the dotProject installation is located.

RewriteEngine on
RewriteCond %{SERVER_PORT} !443$
RewriteRule ^(.*) https://%{SERVER_NAME}/$1 [R,L]

The code snippet will cause requests for http://sitedomain/ to be redirected to https://sitedomain/ instead, where sitedomain is the location of your dotProject installation. Example: If http://www.leesjordan.net/browserdp/ was changed to an SSL site, the following steps would need to be followed:

• Obtain an SSL certificate.
• Install the certificate.
• Paste the code snippet above at the end of the web server's .htaccess file if using an Apache server.
• The redirection should be to https://www.leesjordan.net/browserdp/.

Need more in-depth information about SSL for your situation? Verisign has a section of its site with a variety of information about SSL: http://www.verisign.com/ssl/ssl-information-center/.

Troubleshooting

You faithfully followed the installation instructions and something horrible happened. Or, you went ahead and tried to install dotProject without reading the instructions and now want to know how to fix what went wrong. We will take a look at the most common issues that can occur when installing dotProject. If the user does not have permission, it will fail.

Database Installation Fails

The installer will create a database if you have checked the Create Database box and the MySQL user you have nominated has sufficient permission within MySQL to do so.

config.php Not Created

A config.php file must be in place for dotProject to operate properly

Since this file is not automatically included as part of the installation, it is recommended that the config.php code shown in steps 5 and 7 (under the section Browser-Based Installation) should be copied and pasted into a text file then uploaded to the server. This should be done before attempting to log in to dotProject. The PHP file shown in the section on browser installation should work fine as long as the Database Name, Database User Name, and Database Password information are modified. So, don't use the exact ones I used in the example. If you are using an online control panel to manage your database, it will usually append the same group of letters to each new database you create. For example, you can see during the installation that my database began with "rumour", which happens to be the name of my cat.

Using a Different Web Server/OS/Setup

Many different setups run dotProject successfully. Visit the dotProject forums at http://dotproject.net/vbulletin/ for installation help with a particular setup. Be sure to list all the details, including the operating system, web server, database, and programming language. Version numbers of these should also be included. Please read carefully about the compatibility of MySQL 5 and PHP 5.

dotProject Pages Display Differently for Me

Your dotProject installation pages do not look the same as the examples in this book. There are several different situations where this can happen.What browser and operating system are you using to view dotProject? dotProject uses Cascading Style Sheets (CSS) files for presentation and formatting of most of the data. While most pages should display the same in all browsers, it is possible that there may be some differences between how they look on a Mac running Safari and for a Windows XP user running Internet Explorer 7.What theme is being used as the default theme? The classic dotProject default theme is being used in this book. There are other themes available, which will alter the way dotProject looks.The skin or "look" of dotProject can be further customized by altering the files in the styles folder. Back up any files before you attempt to make changes.

JpGraph/Gantt Fonts Error

An error message displays when the user attempts to go to the Todo section of dotProject or view Gantt charts. The actual error will depend on the web server and system configuration, but it will probably look similar to this:

Errors of this type usually occur when the font file cannot be found. dotProject does not install the fonts for JpGraph by default. This issue is discussed fully in Appendix B of this book.

Summary

In this article, we installed dotProject in several different ways and covered what to do when things go wrong. The quickest way to install dotProject was using a control panel. Installing dotProject using the browser took more time, and required a little bit more technical know how. Now you should be able to install dotProject successfully using a control panel or a browser. This article also delves into common installation issues and how we can elude them. At the end of this article, dotProject has been successfully installed.

This article has been extracted from: Project Management with dotProject: Implement, Configure, Customize, and Maintain your DotProject Installation

A complete beginner’s guide to every aspect of setting up and administering your dotProject installation Install and use the dotProject project management system Customize and extend dotProject Work with reports and Gantt charts Configure dotProject for LDAP authentication and PostNuke Customize dotProject to blend with your corporate sites For more information, please visit: http://www.packtpub.com/dotProject/book

About the Author

Lee Jordan is a web developer with a large collection of web technology acronyms on her resume that sound like the names of laundry detergent and cause glazed expressions in school children. She designs and maintains internal and external enterprise-level websites and web-based applications as part of a project team for a privately held technical services company. Her work includes proposing, writing, and editing web content and user guides people actually read.

She began her career in 1997 as a web designer after graduating from Florida State University with a Bachelor of Fine Arts, where she swears that she missed at least one home football game while in the computer lab. Lee later convinced Seminole Community College to give her a Web Programming degree in 2003, even though her final project was a Java-based application that actually contained a usable help file. Web development topics or whatever she can think of at the time are posted on her blog at http://leesjordan.net.