phpaga

Installation instructions

Florian Lanthaler


          <florian at phpaga dot net>
        

$Revision: 769 $

$Date: 2006-12-08 01:54:52 +0100 (Fri, 08 Dec 2006) $

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Table of Contents

1. Installation

    Requirements

        RDBMS
        Web server
        PHP and PEAR
        JpGraph
        Graphviz
        ImageMagick

    Additional requirements for the development version

        Smarty
        R&OS pdf class
        smarty-gettext
        The coolest DHTML calendar widget

    Installation

        Installation layout
        JpGraph
        Additional steps for the development version
        The database

2. Configuration
3. Upgrading phpaga from previous versions

    In general
    Upgrading from 0.2 to 0.3
    Upgrading from 0.2rc1 to 0.2
    Upgrading phpaga from previous versions

        PostgreSQL
        MySQL
        Migrating phpaga from MySql to PostgreSQL

A. Appendix

    Bugs
    Contact

Chapter 1. Installation

Table of Contents

Requirements

    RDBMS
    Web server
    PHP and PEAR
    JpGraph
    Graphviz
    ImageMagick

Additional requirements for the development version

    Smarty
    R&OS pdf class
    smarty-gettext
    The coolest DHTML calendar widget

Installation

    Installation layout
    JpGraph
    Additional steps for the development version
    The database

Installing phpaga is not a fully automated process, there are a few simple
steps that you must go through. If you are upgrading from a previous version
you might be interested in the chapter Upgrading phpaga from previous versions.

For a fresh install you need to do the following steps:

  ● Copy phpaga files to the destination folder(s).

  ● Install the requirements.

  ● Create a database and grant the necessary rights to the phpaga user.

  ● Set some base configuration parameters.

This document will guide you through the installation and give you some help.
If you don't know how to install PHP or how to compile it with support for the
packages listed under "requirements", then refer to the PHP website and the
official PHP Documentation.

Requirements

The following software packages have to be installed on your server in order to
use phpaga. The version numbers mentioned below are known to work. Please refer
to each package's website for installation instructions.

RDBMS

Currently PostgreSQL and MySQL are supported. If you are unsure about which to
pick go for PostgreSQL - phpaga is developed and tested under PostgreSQL, and
database-related parts are better tested with that platform.

PostgreSQL

7.4 - 8.1.4

http://www.postgresql.org/

MySQL

4.1.15, 5.1.2

http://www.mysql.com/

Web server

phpaga should work with any PHP-enabled web server. It has been tested with
lighttpd 1.4.x and Apache (both 1.3.x and 2.x).

http://lighttpd.net/

http://httpd.apache.org/

PHP and PEAR

4.3.3, 5.1.2

You will need to enable PHP with support for PostgreSQL (or MySQL), gettext and
gd. Visit http://www.php.net/ for more information on how to compile and
install PHP, and http://www.php.net/gettext for information about PHP's gettext
support. For the various supported languages to actually work, make sure you
have the corresponding locales installed. Keep in mind that after installing a
new locale you will need to restart the web server.

The following line is an example of how one could launch ./configure, of course
you need to modify the paths to match your installation.


               ./configure  --with-apxs=/path/to/apache/apxs \
               --with-pgsql=/path/to/local/postgres \
               --with-gd --with-gettext



The php.ini settings register_globals and magic_quotes_gpc can both be Off. In
case magic_quotes_gpc is On all escaping slashes in $_REQUEST, $_GET and $_POST
will automatically be removed by phpaga.

The amount of memory available to PHP is defined by the memory_limit setting in
php.ini. This value defaults to 8M, but you might need to raise it 16M or 32M
if you encounter error messages like "*Fatal error*: Allowed memory size of
8388608 bytes exhausted (tried to allocate 65211 bytes) in *<some filename>* on
line *<some line number>*". etc/config.local.php also provides the possibility
to change this setting.

http://www.php.net/

The following PEAR packages need to be installed:

 1. DB >= 1.7.6

 2. Log >= 1.9.7

 3. Mail >= 1.1.10

 4. Image_GraphViz >= 1.2.1 (optional)

 5. HTTP_Upload >= 0.9.1

 6. HTTP_Download >= 1.1.1

 7. HTTP_Header >= 1.2.0

http://pear.php.net/

JpGraph

>= 1.20.2 (for PHP 4), >= 2.1 (for PHP 5)

phpaga's chart displaying routines are based on the excellent JpGraph by Johan
Persson. JpGraph is a OO graph class library for PHP version 4.1 and above.
Make sure you get the correc version: The 1.x branch is for PHP 4, the 2.x
branch is for PHP 5.

http://www.aditus.nu/jpgraph/

Graphviz

2.2.1

This package is optional. If you would like to see project relationship graphs
you will need to install Graphviz and set the related option "Enable Graphviz"
under the sitewide configuration to "Yes". phpaga uses PEAR::Image_GraphViz
(see above) as an interface to Graphviz. Note that phpaga will work nicely
without this package (provided you set the option "Enable Graphviz" to "No") -
you will just be missing the relationship graphs.

http://www.graphviz.org/

ImageMagick

6.0.6, 6.2.4

ImageMagick's "convert" is used to create preview thumbnails for uploaded
files.

http://www.imagemagick.org/

Additional requirements for the development version

If you fetched the source directly from phpaga's subversion repository you will
need to install the following libraries. (They come already bundled with the
official phpaga packages.)

Smarty

2.6.16

http://smarty.php.net/

phpaga uses Smarty as its templating engine. Smarty is written by Monte Ohrt
and Andrei Zmievski.

R&OS pdf class

009e

The R&OS pdf class is a PHP class that allows the easy creation of PDF files.
Get the file named pdfClassesAndFonts_009e.zip which contains the class,
sample, and the required font metric files.

http://www.ros.co.nz/pdf/

smarty-gettext

1.0b1

http://sourceforge.net/projects/smarty-gettext/

smarty-gettext is a Smarty plugin written by Sagi Bashari that allows to use
gettext with Smarty templates.

The coolest DHTML calendar widget

1.0

This is a very nice and popular DHTML calendar widget written and maintained by
Mihai Bazon (mishoo). phpaga uses the calendar in English only, as not all
languages provided with the calendar package are updated.

http://www.dynarch.com/projects/calendar/

Installation

Installation layout

Only phpaga's htdocs/ directory needs to be read by the web server. All other
directories can and should be outside the web server's document root. This can
be achieved either by creating a virtual host and have it's document root point
to the full path to htdocs/, or by installing phpaga completely outside the
document root of an existing website and then adding an alias to the web
server's configuration. This can be achieved under Apache with the following
example:

  Alias /phpaga /usr/local/phpaga/htdocs/


If you can't modify the web server's settings (for example because you are
using the services of a webhosting company) you should use the following
strategy: Say your home directory is /home/exampleuser, and all your website
content is stored under /home/exampleuser/www/. You copy phpaga to /home/
exampleuser/phpaga/, move /home/exampleuser/phpaga/htdocs to /home/exampleuser/
www/phpaga and mofidy /home/exampleuser/www/phpaga/config.php to include /home/
exampleuser/phpaga/etc/config.php.

JpGraph

If you have JpGraph already installed on your server you can use it by
uncommenting and editing the definition of JPGRAPH_DIR in etc/config.local.php
accordingly.

      define("JPGRAPH_DIR", "/some/other/path/to/jpgraph/src/");


Otherwise install JpGraph into ext/ (no need to change etc/config.local.php).

      % cd phpaga/ext
      % tar zxf jpgraph-x.x.tar.gz
      % mv jpgraph-x.x jpgraph


Additional steps for the development version

If you fetched the source directly from phpaga's subversion repository you will
need to perform the following steps. If you are installing an official package
you can skip this section.

 1. Use the sample file etc/config.local.php_sample to create etc/
    config.local.php and fill in the necessary parameters.

 2. Give the web server full permissions to the pictures/ directory. This
    directory will contain the images that can be uploaded and associated to
    persons.

              % chown www-data pictures/
              % chmod 0700 pictures/


    If you do not have administrative rights on the server and therefore cannot
    change the directory's ownership, simply chmod 0777 the directory.

              % chmod 0777 pictures/


 3. Give the web server full permissions to the files/ directory. This
    directory will contain the files users can upload and associate to objects
    (project, person, company, ...).

              % chown www-data files/
              % chmod 0700 files/


    If you do not have administrative rights on the server and therefore cannot
    change the directory's ownership, simply chmod 0777 the directory.

              % chmod 0777 files/


 4. Create a directory called templates_c in your phpaga-root directory (ie, /
    data/webs/phpaga/) and change its owner to your webserver's user (as the
    webserver has to write into it). Chmod it to 700. This directory is needed
    by Smarty, the template engine.

              % mkdir templates_c
              % chown www-data.www-data templates_c/
              % chmod 0700 templates_c/


    If you do not have root or sudo permissions on your server (as is the case
    in many shared hosting environments), then you must chmod the templates_c
    directory 0777, giving everyone permission to read, write and execute the
    compiled smarty templates:

              % mkdir templates_c
              % chmod 0777 templates_c/



Install required 3rd party packages

 a. If you have Smarty already installed on your server you can use it by
    editing the definition of SMARTY_DIR in etc/config.local.php accordingly.

            define("SMARTY_DIR", "/some/other/path/to/smarty/libs/");


    Otherwise install Smarty into ext/ (no need to change etc/
    config.local.php).

            [ % cd phpaga/ext ]
            % tar zxf Smarty-x.x.x.tar.gz
            % mv Smarty-x.x.x smarty


 b. Install The coolest DHTML calendar widget under htdocs/ into _jsc/

            [ % cd htdocs/ ]
            % unzip jscalendar-1.0.zip
            % mv jscalendar-1.0/ _jsc


 c. Install the R&OS pdf class

            [% cd ext/ ]
            % mkdir pdfclass
            % cd pdfclass
            % unzip pdfClassesAndFonts_009e.zip


 d. Install smarty-gettext

            [% cd ext/ ]
            % tar xvzf smarty-gettext-1.0b1.tgz
            % mv smarty-gettext-1.0b1 smarty-gettext


 e. If you want to use relationship graphs, install Graphviz and
    PEAR::Image_GraphViz.

The database

Create a database and a database user with the necessary permissions - we'll
name both the database and the user "phpaga" in the examples provided below -
and set the appropriate configuration settings in the file etc/config.local.php
accordingly.

If you are using phpaga with a webhosting provider, chances are that the
provider will create the database for you and give you the credentials.

If you are upgrading from a previous version of phpaga refer to the section
Upgrading phpaga from previous versions. For information about converting from
MySQL to PostgreSQL read the section Migrating phpaga from MySql to PostgreSQL.

For PostgreSQL


    % psql template1
    template1> create database phpaga with encoding 'LATIN1';
    template1> create user phpaga password 'yourpasswd';
    template1> grant all on database phpaga to phpaga;
    template1> \c phpaga
    You are now connected to database "phpaga".
    template1> create language plpgsql;



Depending on your setup, you may also need to modify pg_hba.conf. This file is
part of PostgreSQL and controls which hosts are allowed to connect, how clients
are authenticated, which PostgreSQL user names they can use, which databases
they can access. Refer to the PostgreSQL documentation if you are unsure about
the proper settings.

For MySQL


    % mysql -uroot -p mysql
    mysql> create database phpaga;
    mysql> grant all on phpaga.* to phpaga@localhost identified by 'yourpasswd';
    mysql> flush privileges;


Chapter 2. Configuration

Fire up your browser of choice and point it to the right URL. A simple wizard
will guide you and help you to create the database structure, populate it with
core data, and create the first user.

[install]

Insert the data as required and submit the form. The user will be created with
all available permissions, and you are invited to log in.

In case you have any problems accessing phpaga, try to open test.php in your
browser and check its output for helpful information.

PLEASE NOTE: If you can log in and everything is running smoothly, remove
htdocs/test.php (or chmod it so that the webserver does not have access to it)
- it might expose critical information.

Once you are logged in you can configure the default settings by selecting
"Sitewide settings" from the admin menu.

From there you have the option to manage your categorie sections (task/project/
job and other categories) from the admin menu, before you (or your users) start
to add tasks.

For the graphic logo that can be included in the PDF output only JPG format
will work, anything else will cause the output to be invalid.

Chapter 3. Upgrading phpaga from previous versions

Table of Contents

In general
Upgrading from 0.2 to 0.3
Upgrading from 0.2rc1 to 0.2
Upgrading phpaga from previous versions

    PostgreSQL
    MySQL
    Migrating phpaga from MySql to PostgreSQL

In general

CREATE A BACKUP OF YOUR DATABASE BEFORE PERFORMING ANY UPGRADE.

An upgrade should be a low risk activity, nonetheless you are advised to back
up your data before performing any upgrade.

If you are upgrading from a previous release of phpaga you need to take care of
a few things.

Check whether the software requirements have changed at the section
Requirements.

Apply the changes to the database structure by following the instructions in
the sections PostgreSQL or MySQL. Execute the proper upgrade*.sql script from
sql/.

If you were using phpaga with MySQL and would like to switch to PostgreSQL then
read the section Migrating phpaga from MySql to PostgreSQL.

If you need additional help consider joining the user's mailing list.

Upgrading from 0.2 to 0.3

After 0.2 the internationalization mechanism was switched from definitions to
gettext. Make sure your version of PHP supports gettext and has the locales for
the languages you want to use installed. (See Requirements)

All application settings that were formerly defined in etc/config.php are now
managed within phpaga itself. Once you have configured etc/config.local.php,
you can fire up your browser and change these settings from the Admin menu
("Sitewide settings").

Make sure you have PEAR DB version >= 1.6. Install the PEAR packages Log and
Mail and all other required PEAR packages.

Execute the scripts required to upgrade the database structure. Depending on
the RDBMS you are using, this will be sql/upgrade_0.2-0.3.pgsql for PostgreSQL
or sql/upgrade_0.2-0.3.mysql for MySQL. If you use MySQL, execute also sql/
mysql-innodb.mysql; this will convert all database tables to the InnoDB format.

phpaga 0.3 introduces a permission system. In order to migrate to the
permission system, the former administrator gets all available permissions. It
is then in her responsibility to assign the proper permissions to the remaining
users. The necessary SQL statement to perform this migration is contained in
the upgrading scripts (see above paragraph).

phpaga 0.3 introduces news to the billing system. Invoices can now have line
items. In order to convert the existing invoices to the new format, you will
need to run a conversion script. This script must be run after upgrade_0.2-0.3.
(pgsql|mysql) has been applied and before any new invoice is created. The
script is named convert_invoices.php and located in the directory tools/. Open
the file with an editor and set the parameters in the first section according
to your configuration. Then run the script from the shell.

Upgrading from 0.2rc1 to 0.2

Configuration settings are now defined via web. You will need to replace your
old etc/config.php with the new one from the package, and later change the
settings from the Admin menu ("Sitewide settings").

Smarty and the R&OS pdf class are no longer bundled with phpaga. Refer to the
Requirements section to find instructions on where to find and how to install
these packages.

Upgrading phpaga from previous versions

PostgreSQL

Execute the proper upgrade*.sql script from sql/.

MySQL

From 0.1.1 to 0.2

The following instructions give you the necessary information to upgrade your
phpaga database under MySQL from phpaga 0.1.1 to phpaga 0.2.

Since phpaga 0.2 we use Pear::DB to abstract database access. Since MySQL does
not support sequences directly (it has the 'autoincrement' feature), Pear needs
a set of help tables that contain the sequence values.

  ● Apply sql/upgrade_0.1.1-0.2.mysql and sql/phpaga_sequences.mysql:

                    $ mysql -uroot -p phpaga < sql/upgrade_0.1.1-0.2.mysql
                    $ mysql -uroot -p phpaga < sql/phpaga_sequences.mysql


  ● The user passwords need to be migrated from MySQL password() to md5 hashes,
    in order to have a common way to manage encrypted passwords on different
    rdmbs. You can use md5sum to generate md5 hashes.

    Example (under Debian GNU/Linux):

                    $ md5sum.textutils --string oldpassword

                    d5b5fffc89f961903fb3c9a173f1b667  "oldpassword"

                    mysql> UPDATE users SET usr_passwd = 'd5b5fffc89f961903fb3c9a173f1b667'
                    WHERE usr_login = '@YOUR_LOGIN@';


    If you do not have md5sum.textutils you can create a small php script that
    contains the following lines:


                               <?php
                               echo md5('@PASSWORD@');
                               ?>



    and either parse it via the command line php or via a php-enabled webserver
    and the output string will be the correct md5 value for your password.

From 0.2-rc1 to 0.2

In order to upgrade from phpaga 0.2-rc1 to 0.2 release simply apply sql/
upgrade_0.2_rc1-0.2.mysql:


                     $ mysql -uroot -p phpaga < sql/upgrade_0.2_rc1-0.2.mysql



Migrating phpaga from MySql to PostgreSQL

Starting with version 0.2-rc1 phpaga features database abstraction through
Pear::DB. As of version 0.2 the following rdbms are supported:

  ● PostgreSQL

  ● MySQL

If you want to migrate your phpaga data from MySQL to PostgreSQL you might find
the following instructions of help.

 1. Create a mysqldump of phpaga containing just the data:

                % mysqldump -uphpaga -pyourdbpasswd -c -t phpaga > phpaga_data.sql


 2. Connect to the PostgreSQL phpaga database with pgsql using the phpaga db
    user:

                  % psql phpaga phpaga
                  phpaga=> \i phpaga_data.sql


    Check the output for errors.

 3. Set the sequences to the correct values:

                phpaga=> \i /path/to/phpaga/sql/phpaga_setseqvals.pgsql



This should be it. Please report any problems via our mailing lists or support
forums.

Appendix A. Appendix

Table of Contents

Bugs
Contact

Bugs

Use the tools on the project site or feel free to drop a message to the
phpaga-users mailing list to report bugs.

Contact

Comments, questions and praise are welcome on the mailing lists.

