Installing dotProject in Linux

1 IMPORTANT WARNINGS - READ THIS SECTION

Before commencing installation please check Category:Known Issues and make sure that you meet the System Prerequisites [edit] 1.1 Do Not Manually Install As of version 2 of dotProject, manual use of SQL files and running PHP scripts is no longer required and is contra-indicated. The web based installation program (www.yoursite/dotproject/install) must be run to correctly instantiate permissions. If you do not run that program you will never be able to login. NOTE: DO NOT use the dotproject.sql file and create the database manually. This will generate a dpversion table which will guarantee that the installer will not upgrade your database and therefore will not generate your permissions. Go back and correct the error that meant that the installer was unable to complete correctly. [edit]

2 Installing a New System

Do not attempt to hand install dotProject 2.0 OR THE DATABASE OR ANY COMPONENT THEREFORE OR ANYTHING TO DO WITH 2.0 and/or adjust configuration files manually as this will fail and the permissions environment will not be correctly generated. [edit]

2.1 Step One - Unpack the Files

Unpack the distribution file somewhere on your system under your web server's root directory. If you are using a web hoster this is likely to be called www or public_html in your home directory. Check with your hosting provider or your system administrator if you are unsure. [edit]

2.2 Step Two - Running the Installer

1

After you have checked that the web server is correctly configured, point your browser to dotproject/install. (Depending on where you put your files you may need to provide a different path). Make sure you include your server details. For example, if you are installing on http://mydomain.com/ and you have unpacked in your public_html directory, the URL to use would be http://mydomain.com/dotproject/install/ [1][2] If all is well you should be in the dotProject Installer. [edit]

2.3 Step Three - Check and Start Installation

Before continuing, review the details on the page, as some of the settings may result in either partial or complete failure of your dotProject installation. For instance, you may need to make changes to your directory permissions to support file uploads or to allow the main configuration file to be written. If you need to make changes do so and then refresh the install page. When you are satisfied, click on the Start Install button. [edit]

2.4 Step Four - Database Settings

At this point the Database Settings page will be shown. The Database Server Type should be left at MySQL unless you have technical knowledge and a patch to support an alternative. Enter the name of your database host. This is often the same host as your web server, so can be left as 'localhost'. Check with your service provider for details.[3] Either enter the name of a database that you have previously created, or if you have permission to create databases, the name of a new database. The database should not have any tables or other data in it at this stage. Enter the name and password of the DATABASE user [4] that has access to the above named database on the database host you have entered. If you have not yet created a database, and your database user has sufficient permissions, check the Create Database checkbox. If not, or if you already have created the database, leave this clear.

You can safely leave the other options clear. Select the upgrade db & write cfg button. If all is well the next screen will display the progress as dotProject is installed. The most common problem at this stage is incorrect database details. If this is the case, go back and enter the correct details before proceeding. [edit]

2.5 Step Five - Config.php

The config.php file is the file that dotProject reads for all it's basic operational activity. No config.php and you won't have a properly functioning dotProject installation. When complete, you may be asked to cut and paste the config file contents to dotproject/includes/config.php. This will only occur if the web server could not write to the includes directory. If this is shown, create the config.php file with the information displayed before you click on the Login and Configure the dotProject System Environment link, otherwise you will be redirected back to the installer. [edit]

2.6 Step Six - Login with Default User Name and Password
When you click on the Login and Configure the dotProject System Environment link, you will be asked to login. The default login is: User Name: admin Password: passwd [edit]

2.7 Step Seven - Secure your dotProject Installation

There are two steps you should undertake within dotProject to protect your installation.[5] 1. Remove the install directory from your dotProject environment. Failure to do this may affect your system security. 2. Change the admin password immediately. [edit]

3 Upgrading an Existing System

3

IMPORTANT NOTE for people upgrading to 2.1.4 and ABOVE. As of 2.1.4 dotProject provides table prefixing in the database. There is NO upgrade path from previous systems that were installed without table prefixes to table prefixed environments. If you are upgrading from a version previous to 2.1.4 and ABOVE ensure that you CLEAR the Table Prefix field in the upgrade screen. (For experienced database administrators you can manually change the table names in the database BEFORE upgrading.) [edit]

3.1 Backing Up
Before Upgrading an existing system BACKUP. EVERYTHING Backup your data and SQL schema Backup your dotProject software installation Make sure you can restore from your backups

If you are using phpMyAdmin, use the Export option to export both data and schema of the database. If you are using command line tools use mysqldump, which by default backs up both data and schema. Use mysqldump --help for information on its usage.[6] Make sure you also backup the files in your dotproject installation. This includes code and uploaded files (in the files directory). There is no way to retrieve these from the database backup if you manage to delete them from the filesystem. Make sure before you proceed that you can read the backups, and that you have some method of getting them back into the system. It is no good having a backup that you cannot restore in the event of a problem. [edit]

3.2 config.php
The installation package does not include a config.php file by design.

If there is a config.php file in your dotProject hierarchy then it will assume that it is an upgrade and advise you accordingly. Logic now also checks the contents of the config file and the connectivity to the database. It also makes some basic checks on the database to see if people have done a manual upload of the dotproject.sql file as well. [edit]

3.3 Step One - Unpack the Files

Be aware that you are unpacking your dotProject files into a directory that already contains dotProject (and is, presumably totally backed up). File permissions may need to be resolved. Remember that your existing config.php file must be left in your dotProject directory. [edit]

3.4 Step Two - Running the Installer

We are assuming that you already know the required URL (if not see discussion above), but point your browser to dotproject/install [edit]

3.5 Step Three - Check and Start Installation

Follow the on-screen instructions taking note of ALL of the recommendations [edit]

3.6 Step Four - Start Upgrade

Click on Start Upgrade to proceed. Working on the existing config.php, the installer will check:

Does the config.php file exist? o If Y, does the dbhost variable exist? o If Y, can the database be contacted? o If Y, does the database have the phpGACL tables and are they fully populated?

If the config.php file exists we assume an upgrade[7] If the phpGACL tables exist but aren't populated it is an install. If they don't exist it is an update (pre 2.x installs didn't have these, so we assume we are upgrading from a previous version). [edit]
5

3.7 Step Five - Backup Function

Be aware that although the installer currently has a backup function built in this generates an XML output and we DO NOT CURRENTLY HAVE XML restore - do not use this option unless you are prepared to work out how to restore from XML yourself.[8] [edit]

3.8 Step Six - Upgrade Options

Choose Upgrade DB Only OR Upgrade DB and Write CFG if you have made any changes to earlier details [edit]

3.9 Step Seven - Run Installer

Follow as per installation instructions above and resolve as per installation instructions [edit]

3.10 Step Eight - Secure your dotProject Installation

There is only one step required on an upgraded site (provided that your initial installation is secure), as the admin password will not be altered by the update. 1. Remove the install directory from your dotProject environment. Failure to do this may affect your system security. [edit]

4 Security Considerations
[edit]

4.1 register_globals
Running dotProject with register_globals turned on is a known security risk and we do not recommend / support or consider it as an option. Your installer will check for and report if you have register_globals turned on in your php installation. register_globals ON has been deprecated since php4.1.0 and been set to OFF by default since php4.2.0

For more information on the KNOWN security flaws in the use of register_globals on please refer to the myriad of php reference materials. For your dotProject installation to be optimised REGISTER_GLOBALS should be turned OFF. If you are using other applications that go against recommendations and have REGISTER_GLOBALS turned on - then use a .htaccess file or take it up with the other applications. [edit]

4.2 docs directory

If you are concerned about path disclosure you may choose to remove the docs directory as well, alternatively you may choose to move the check.php and phpinfo.php files from that directory remembering that these are two files that are used in diagnosing issues with your installation. [edit]

5 Secure Installation with SSL (optional)

Once you have installed your SSL certificate for the domain on which your dotProject installation is hosted, you'll need to add the following code to a .htaccess file (if using Apache) in the root folder of your dotProject installation.
<IfModule mod_rewrite.c> RewriteEngine on RewriteCond %{SERVER_PORT} !443$ RewriteRule ^(.*) https://%{SERVER_NAME}/$1 [R,L] </IfModule>

Once that's in place all requests for http://your.project.site/ will be redirected to http'''s'''://your.project.site/ [edit]

6 LDAP Authentication
dotProject can be configured to use LDAP bind Authentication as an alternative to authenticating from the SQL database. The LDAP Authentication feature was introduced in v2.0 [edit]

6.1 Configuration

In order for LDAP Authentication to work you will need to set up these system configuration variables: auth_method ldap_host ldap_port Set this to "ldap" to use your LDAP server for authentication of dotProject users. The hostname or IP address of the LDAP Server to contact for authentication (defaults to localhost). The port number of the LDAP service, in most cases you should leave this as the default (port 389). The version of the LDAP protocol to use. OpenLDAP installs as default with support for LDAP Version 3, although you might have to change this to version 2 for other directory systems. If you are not sure just leave the default value (version 3), you can come back later to change this value if you get a protocol error while trying to login. The base DN to search for Users of dotproject, this varies depending on your LDAP installation - this is also used in the LDAP bind authentication process. The filter used for finding an LDAP entry. This will also vary depending on your LDAP installation, the default assumes each user will have a posixAccount object class from the NIS schema (default is "(uid=%USERNAME%)"). Use the string %USERNAME% to denote where the username parameter should be applied.

ldap_version

ldap_base_dn

ldap_user_filter

The Full DN of the user you want to bind as for searching. The user must ldap_search_user have permission to search your users directory. Note: Recently changed to Full DN ldap_search_pass The Password of the LDAP search user. ldap_allow_login (Allow standard logins) - Allow SQL users to login, in addition to the LDAP system (Recommended).

Once these system configuration variables are correct, LDAP users will be able to login. By default, they will be given the permissions of the role "Anonymous". If you wish your users to have greater access to the system, you will have to add access permissions or user roles via the User Admin module. [edit]

6.2 Example Active Directory Setup

This explains how you would set up LDAP authentication with Active Directory: Example domain is: dotproject.com, the domain controller is called dc.dotproject.com.

- set the LDAP host to: dc.dotproject.com - set the Base DN to: cn=Users,dc=dotproject,dc=com - this indicates that the system should search the Users folder for valid users. - set the user filter to: (sAMAccountName=%USERNAME%) - this will be the same for all Active Directory installations. - set the LDAP search user and password: You could set this to a user with the administrator role but its safer to make an ldapsearch user with only the permissions required to read the users folder. - set allow standard login on - this is recommended so that if your directory system fails, you can still login to dotproject. [edit] 6.2.1 Note from Contributor sebmind on Original Wiki The configuration that works best with active directory, especially if you have multiple OUs in your directory tree: Host: "ldaps://dc.somedomain.com" Port: "3269" Base DN: "dc=somedomain,dc=com" Filter: "(sAMAccountName=%USERNAME%)" Works for me using AD 2000. Nice work, dotproject! [edit] 6.2.2 Note from Contributor snosty on Original Wiki The filter "(sAMAccountName=NaV)" does not work in 2.01, however, "(sAMAccountName=%USERNAME%)" does. [edit]

6.3 Technical Notes

The LDAP Authentication fills in the details, such as the users full name, e-mail address, etc.. by searching for the entry matching the username that is entered, and re-inserting the information into Contacts. The default attributes that are copied are based on the inetOrgPerson object class. Most of these attributes should correlate well with Microsofts AD schema. [edit]

7 Free Online Installation Tutorial

If you would like to access a free online tutorial on installing dotProject please go to: http://sites.sakienvirotech.com/moodle/ [edit]
9

8 Footnotes
1. ? If you get an error page, or a directory listing, then your web server does not support index.php as a valid directory index. Contact your web server support staff to resolve this, as dotProject will not work without it. 2. ? If you get a page that starts with a copyright notice, then your web server does not support PHP files. Again, you will need to get this resolved before you can continue. 3. ? 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. If the user does not have permission it will fail. If the database already exists (ie you have used some other means of creating it) you do not need to check the Create Database box. 4. ? Not the web server user, the ftp user, the dotProject admin login or your own login name (UNLESS you know that you have permission, within MySQL) to generate a database 5. ? Obviously you need to do a lot more than this if your server is accessible to the outside world. One source of information for securing PHP applications is http://au3.php.net/manual/en/security.php BUT DO NOT RELY ON JUST ONE SOURCE - use your own initiative to sort out your own security environment 6. ? Please note that the use of either environment is outside the scope of dotProject and you should consult the relevant authorities for details 7. ? In other words do not create on which has nothing / incorrect details in it and expect a new installation to work 8. ? As of 2.0.1 the backup module has been upgraded and incorporated into dotProject. This is a new implementation however and you should NOT trust it - make sure that you have an alternative backup available until such time as this module has been extensively tested and used. Categories: Install Manually | Manual Install | Installation | Install New System | Install - Unpack Files | Install - Running the Installer | Install - Check and Start Installation | Install - Database Settings | Database Before Installation | Install - Config.php | Default User Name and Password | User Name and Password on Installation | Installation User Name and Password | Install Security | Upgrade an Existing System | Upgrade an Existing System - Backup | Upgrade an Existing System - config.php | Upgrade an Existing System - Unpack Files | Upgrade an Existing System - Running the Installer | Upgrade an Existing System - Check and Start | Upgrade an Existing System - Upgrade Options | Upgrade an Existing System - Run Installer | Upgrade an Existing System - Security | Security | SSL | LDAP
Search

Article Discussion Edit History

10

 General

Log in / create account

General Information Status and Roadmap

Quick Lookups

By Functionality Core Modules Addon Modules

Installation

Prerequisites and Installation

FAQs/Errors etc

FAQ TopOfThePops FAQs Error Messages Known Issues Troubleshooting

User Manual

User Manual Glossary of PM Terms

System Administration

Permissions System Administration

Programmer Info

Programmers Manual Join the Dev Team

Add on Modules

Add On Manuals Third Party Extensions

Odds and Ends

Recent changes
11

Random page Who Is Online

Conversion Toolbox

UNFINISHED

What links here Related changes Upload file Special pages Printable version Permanent link

Skin by Peter This page was last modified 02:11, 15 January 2011. This page has been accessed 155,933 times. Content is available under Copyright. Privacy policy About DotProjectWiki Disclaimers

12