Please rate how useful you found this document: 
Average: 2.7 (3 votes)

Overview

Follow these instructions to install ProcessMaker 2.0 - 2.5 on top of a LAMP (Linux, Apache, MySQL, PHP) stack in Ubuntu (Edgy Eft) 6.10 and later. If installing ProcessMaker 2.8 or later, see these instructions.

Before installing, it is recommended to first check the Installation Requirements. After installing, see Additional Server Configuration.

Step 1: Install Apache, MySQL and PHP

If the LAMP stack isn't already installed, open a shell by going to "Applications > Accessories > Terminal".

If using Ubuntu 9.10 (Karmic) and earlier (or Mint 8 (Helena) and earlier), enter the following command:

sudo apt-get install mysql-server php5 apache2 php5-mysql php5-gd php5-ldap php5-curl php5-cli \
php5-mcrypt php5-soap php5-xml

If using Ubuntu 10.04 (Lucid) and later (or Mint 9 (Isadora) and later), enter the following command:

sudo apt-get install mysql-server php5 apache2 php5-mysql php5-gd php5-ldap php5-curl php5-cli php5-mcrypt

Note: If wishing to run ProcessMaker with PHP 5.3, which is the version tested by the ProcessMaker Quality Control team, see Downgrading to PHP 5.3 below.

When apt-get installs MySQL, a dialog box will appear asking for a new root password for MySQL.

Enter a password and select the option OK. Then enter the same password a second time in the next screen to confirm it.

Install SSH Server and PhpMyAdmin

OpenSSH Server can be installed to allow the ProcessMaker server to be remotely accessed from the command line, which is very useful when executing the processmaker and gulliver commands or conducting administrative tasks. In addition, phpMyAdmin can be installed to easily view the MySQL databases used by ProcessMaker inside a web browser.

First, verify that the "universe" repository is in your /etc/apt/sources.list file. If not, edit the file:

sudo nano /etc/apt/sources.list

Add a line similar to the following:

deb http://us.archive.ubuntu.com/ubuntu/ trusty universe

Change trusty to your version of Ubuntu. Then, update the list of available packages from the repositories:

sudo apt-get update

Then, install OpenSSH Server and phpMyAdmin:

sudo apt-get install openssh-server phpmyadmin

If asked which web server PhpMyAdmin should use, press the space bar to select "apache2":

When asked for a password to create the MySQL databases, enter the MySQL root password:

Then, enter a password which can be used to access the PhpMyAdmin web application:

Reconfirm that password by entering it a second time:

Step 2: Configuring PHP Settings

If using PHP 5.3 and later, then no configuration of PHP is required. If using PHP 5.2 which is used in Ubuntu 9.10 (Karmic) and earlier, then PHP's configuration file php.ini needs to be edited to increase the memory limit for each session.

Edit PHP's configuration file php.ini:

sudo nano /etc/php5/apache2/php.ini

Each ProcessMaker session needs a minimum of 128MB RAM to run properly, so set the memory_limit to 128M or greater:

memory_limit = 128M

Note: The value set for the memory_limit in php.ini should be the same value set in the System interface (or in the env.ini file).

If the php.ini file has been modified, make sure that file_uploads and short_open_tag have been enabled:

file_uploads = On
short_open_tag = On

If planning on uploading large files, as Input Documents while running cases, the max_post_size and upload_max_filesize should be increased to more than the default 2MB. For instance, if planning on uploading files as large as 24MB, then:

post_max_size = 24M
upload_max_filesize = 24M

Step 3: Download & Extract ProcessMaker

Go to http://sourceforge.net/projects/processmaker/files and download the latest version of ProcessMaker. The versions are numbered according to the pattern MAJOR.MINOR.REVISION, such as 2.0.45.

After the download has finished, decompress the tarball in the directory where ProcessMaker will be installed. ProcessMaker can be installed in any directory which is not publicly accessible to the internet (so do NOT install it in /var/www), but it is generally installed in /opt, since it is not an optional program which doesn't come from the standard repositories:

sudo  tar -C /opt -xzvf processmaker-2.X.X.tar.gz  

Verify that ProcessMaker was correctly decompressed:

ls /opt/processmaker

The processmaker directory should contain the following contents:

gulliver     processmaker      rbac        shared
LICENSE.txt  processmaker.bat  README.txt  workflow

Set file permissions

Then, issue the following commands so that ProcessMaker can access the necessary files when run by the Apache server:

sudo chown -R www-data:www-data /opt/processmaker
cd /opt/processmaker
sudo chmod -R 770 shared workflow/public_html
cd workflow/engine
sudo chmod -R 770 config content/languages plugins xmlform js/labels

If installing ProcessMaker 2.5.0 or later, also give write permissions to generate Output Documents:

cd /opt/processmaker/gulliver
chmod -R 770 js thirdparty/html2ps_pdf/cache

Step 4: MySQL Configuration

The MySQL "root" user should already have all the necessary privileges to setup the ProcessMaker databases. If planning on using a MySQL user other than "root" to set up the ProcessMaker databases, then follow the instructions below to grant a MySQL user superuser privileges to create and update databases.

Login to MySQL:

mysql -u root -p

Enter the root password for MySQL.

Once in MySQL, give the user which will be running ProcessMaker superuser privileges to create create and modify MySQL databases:

mysql> grant all on *.* to 'USER'@'localhost' identified by 'PASSWORD' with grant option;

Replace USER with the name of your MySQL user and PASSWORD with the password for that user. (If that user doesn't already exist, he/she will be automatically created with the above grant command. If you are running ProcessMaker on a different server than your MySQL server, then replace localhost with the domain name or IP address of the server where ProcessMaker is located.

Exit MySQL:

mysql> exit;

MySQL Configuration Issues

Setting the root Password

If MySQL doesn't have a root password, set one for better security:

mysqladmin -u root password PASSWORD

If you have forgotten the root password, see these instructions to reset it.

Starting as a Service

When logging into MySQL, if the following error message appears:

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)

Then, MySQL needs to be started as a service:

service mysql start

If MySQL was installed from its Ubuntu package, it should automatically start as a service on bootup. If not, then use use update-rc.d to add it as a service:

update-rc.d mysql defaults

Step 5: Apache Configuration

Edit the ProcessMaker configuration file to fit your environment:

sudo nano /opt/processmaker/etc/pmos.conf

Replace your_ip_address and your_processmaker_domain with the IP address and domain name used by your ProcessMaker server:

# Please change the ip address with your server ip address and
  # the ServerName with you own subdomains.
  NameVirtualHost your_ip_address
  #processmaker virtual host
  <VirtualHost your_ip_address >
    ServerName "your_processmaker_domain"
    DocumentRoot /opt/processmaker/workflow/public_html
    DirectoryIndex index.html index.php
    <Directory  "/opt/processmaker/workflow/public_html">
       AddDefaultCharset UTF-8
       AllowOverRide none
       Options FollowSymlinks
       Order allow,deny
       Allow from all
       RewriteEngine on
       RewriteRule ^.*/(.*)$ sysGeneric.php [NC,L]
       ExpiresActive On
       ExpiresDefault "access plus 1 day"
       ExpiresByType image/gif "access plus 1 day"
       ExpiresByType image/png "access plus 1 day"
       ExpiresByType image/jpg "access plus 1 day"
       ExpiresByType text/css "access plus 1 day"
       ExpiresByType text/javascript "access plus 1 day"
       AddOutputFilterByType DEFLATE text/html
    </Directory>
  </VirtualHost>
Note: If using Apache 2.4 (which is found in Ubuntu 13.10 Saucy and later), then change the following line from:
   Order allow,deny
   Allow from all
To:
   Require all granted

Replace your_ip_address with the IP number or domain name of the server running ProcessMaker. If only planning on running and accessing ProcessMaker on your local machine, then use the IP address "127.0.0.1". If using ProcessMaker on a machine whose IP address might change (such as a machine whose IP address is assigned with DHCP), then use "*", which represents any IP address. If not using the standard port 80, then it is necessary to also specify the port number.

If your DNS or /etc/hosts has a defined domain for ProcessMaker, then use that domain for your_processmaker_domain. Otherwise, use the same IP address for your_processmaker_domain as was used for your_ip_address.

For example, if running ProcessMaker on a server at address 192.168.1.100 with a DNS at 123.456.7.89:

NameVirtualHost 192.168.1.100
  #processmaker virtual host
  <VirtualHost 192.168.1.100 >
    ServerName "123.456.7.89"
    DocumentRoot /opt/processmaker/workflow/public_html
    DirectoryIndex index.html index.php
    <Directory  "/opt/processmaker/workflow/public_html">
    ...

For example, if ProcessMaker is installed in the /user/fred directory on your local machine at port 8080 with an dynamic IP assigned by DHCP:

NameVirtualHost *:8080
  #processmaker virtual host
  <VirtualHost *:8080 >
    ServerName "*"
    DocumentRoot /user/fred/processmaker/workflow/public_html
    DirectoryIndex index.html index.php
    <Directory  "/user/fred/processmaker/workflow/public_html">
    ...

Note: It is also possible to define the virtual host for ProcessMaker directly in the Apache configuration by inserting the above VirtualHost definition in the file /etc/apache2/apache2.conf.

After editing pmos.conf, add it to Apache's list of sites which are available for serving:

sudo cp /opt/processmaker/etc/pmos.conf /etc/apache2/sites-available/
sudo a2ensite pmos.conf

ProcessMaker needs to use the expires, rewrite, deflate and vhost_alias modules in the Apache 2 web server. Check to see whether these modules are enabled:

ls /etc/apache2/mods-enabled/

If you don't see them in the list, they can be enabled with the a2enmod command:

sudo a2enmod expires
sudo a2enmod rewrite
sudo a2enmod deflate
sudo a2enmod vhost_alias

Note: If using Apache 2.4 (which is found in Ubuntu 13.10 Saucy and later), either enable the filter module:

a2enmod filter

Or remove the following line from pmos.conf:

   AddOutputFilterByType DEFLATE text/html

After adding the web site pmos.conf and enabling modules, it is necessary to restart the Apache web server:

sudo /etc/init.d/apache2 restart

Apache Configuration Issues

No ServerName

If a similar warning message appears when restarting Apache:

apache2: Could not reliably determine the server's fully qualified domain name, using 127.0.1.1 for ServerName

Then, the ServerName needs to be set for Apache. Edit the Apache configuration file:

sudo nano /etc/apache2/apache2.conf

Add the line:

ServerName <IP-ADDRESS>

For instance, if running ProcessMaker from the local machine, then:

ServerName 127.0.0.1

Non-standard Port

If running ProcessMaker off a port other than the default port 80, then add the following line to the file /etc/apache2/ports.conf:

Listen <IP-ADDRESS>:<PORT>

For instance, if running ProcessMaker from the local machine at port 8080:

Listen 127.0.0.1:8080

Or simply:

Listen 8080

Note: If Apache is using the default port 80, then configure other programs (like Skype) to not use port 80. Check whether a program is currently listening on port 80 with the command:

netstat -tanp

To configure Skype to stop listening on port 80, press CTRL+O or go to Tools > Options. Under the Advanced section of the "Options" dialog box, go to the "Connection" section and enter an alternative port for Use port [ ] for incoming connections.

Disabling the default Apache site

If Apache is configured to display a default message like the following:
It works!
This is the default web page for this server.
The web server software is running but no content has been added, yet.

Then, disable Apache's default site:

sudo a2dissite default
sudo /etc/init.d/apache2 reload

No VirtualHosts Warning

If you see the following message when reloading or restarting Apache:

[warn] NameVirtualHost *:80 has no VirtualHosts

Then, comment out or delete the following line in the file /etc/apache2/ports.conf:

NameVirtualHost *:80

Step 6: Setting up ProcessMaker

Open a web browser and enter the IP address (and port number if not using the default port 80) where ProcessMaker is installed. For instance, if ProcessMaker is installed at the address 192.168.10.100, then go to: http://192.168.10.100
If using ProcessMaker which is installed locally on port 8080, go to: http://127.0.0.1:8080

Then in the web browser, use the installation wizard to complete the installation.

Step 7: Additional Configuration

Additional aspects of ProcessMaker may need to be configured. See Additional Server Configuration and the Configuration section of the wiki. Most installations of ProcessMaker need to configure the following:

Setting the Time Zone

In ProcessMaker version 2.0.29 and later, the default time zone for the ProcessMaker server is set in the env.ini configuration file. If using a previous version of ProcessMaker, see Default Time Zone.

Configuring Email

If planning on sending out email notifications or enabling users to recover forgotten passwords, then see Email - Settings to configure ProcessMaker to use an email server.

Execution of cron.php

If planning on using email notifications, events or the case scheduler, then the server running ProcessMaker has to be configured to periodically execute the cron.php file. See Executing cron.php.

Errors during Installation

If an error occurs during the installation, check the installation log file:
/shared/log/install_log.log
It will generally be found at:
/opt/processmaker/shared/log/install_log.log

Depending on the errors found in the installation log file, check the following files:
The Apache configuration file:
/etc/apache2/apache2.conf
The ProcessMaker web site configuration file for Apache:
/etc/apache2/sites-available/pmos.conf
The PHP configuration file:
/etc/php5/apache2/php.ini
The MySQL configuration file:
/etc/mysql/my.cnf
The ProcessMaker configuration file where components are installed:
/workflow/engine/config/paths_installed.php
The ProcessMaker configuration file for database connections:
/shared/sites/workflow/db.php
The ProcessMaker redirection to login screen:
/processmaker/workflow/public_html/index.html

If the following error appears at the login screen:

This error indicates that the installer was unable to access the MySQL databases to install the translations. Make sure that the MySQL port (which is 3306 by default) isn't blocked by a firewall and MySQL is configured to accept connections from the server running processmaker. If that doesn't work, then ask for help on the forum.

Downgrading to PHP 5.3

Ubuntu 12.10 (Quantal) and later (or Mint 14 (Nadia) and later) use PHP 5.4. At this time, there are no known incompatibility problems using PHP 5.4 with ProcessMaker, but the Quality Control team has only tested ProcessMaker with PHP 5.3. If not wishing to run ProcessMaker on an untested version of PHP, it is recommended to downgrade PHP to version 5.3, which is found in Ubuntu 12.04 (Precise). Enter the following commands in a terminal to downgrade to PHP 5.3.

If PHP5 and/or Apache2 are already installed, then remove them and all their configuration files:

sudo apt-get purge php5* apache2*
sudo apt-get autoremove

Note: If needing to keep your Apache or PHP configuration files, use remove instead ofpurge in the above command.

Then, edit the /etc/apt/sources.list file to add the precise repository and comment out all current repositories by inserting # in front of them. In this example, the text in blue has been added, to enable the precise repositories and disable all the trusty repositories:

deb http://archive.ubuntu.com/ubuntu precise main restricted universe

#deb http://archive.ubuntu.com/ubuntu trusty main restricted
#deb-src http://archive.ubuntu.com/ubuntu trusty main restricted

#deb http://archive.ubuntu.com/ubuntu trusty universe
#deb-src http://archive.ubuntu.com/ubuntu trusty universe

#Comment out all other repositories as well.

Now update the list of packages:

sudo apt-get update

Then, install PHP and Apache:

sudo apt-get install apache2 php5 php5-mysql php5-gd php5-ldap php5-curl php5-cli php5-mcrypt

PHP 5.3.10 and Apache 2.2.22 should now be installed. Now edit the /etc/apt/sources.list file again and delete the # before the repositories, so that they can be used again:

deb http://archive.ubuntu.com/ubuntu precise main restricted universe

deb http://archive.ubuntu.com/ubuntu trusty main restricted
deb-src http://archive.ubuntu.com/ubuntu trusty main restricted

deb http://archive.ubuntu.com/ubuntu trusty universe
deb-src http://archive.ubuntu.com/ubuntu trusty universe

#Uncomment all other repositories as well...

In order to prevent Ubuntu/Mint from installing a later version of the PHP and Apache packages when upgrading in the future, it is a good idea to create a pinning file in /etc/apt/preferences.d/preferences:

sudo nano /etc/apt/preferences.d/preferences

Insert the following content in the file:

Package: php5*
Pin: release n=precise
Pin-Priority: 900

Package: apache2*
Pin: release n=precise
Pin-Priority: 900

Package: libapr*
Pin: release n=precise
Pin-Priority: 900

Package: libdb5.1
Pin: release n=precise
Pin-Priority: 900

Package: libmcrypt4
Pin: release n=precise
Pin-Priority: 900

Package: phpapi*
Pin: release n=precise
Pin-Priority: 900

Package: libapache2*
Pin: release n=precise
Pin-Priority: 900 libgd2*

Package: *
Pin: release n=trusty
Pin-Priority: 600

Change trusty to match your installation of Ubuntu or Mint. If using Mint, change precise to maya. Now, commands like apt-get upgrade will not overwrite the installed PHP and Apache packages.

Finally, update the list of packages:

sudo apt-get update