Overview

Follow these instructions to install ProcessMaker 2.0 - 2.5 in Red Hat Enterprise Linux (RHEL)/CentOS 5 or later. If installing, ProcessMaker 2.8 or later, see these instructions. Before installing ProcessMaker, see the Installation Requirements. After installation, see Additional Server Configuration.

Step 1: Configure SELinux

If ProcessMaker is installed in the /opt directory, it is necessary to either configure SELinux to allow Apache to read/write to the directory where ProcessMaker is installed or simply disable SELinux.

Configuring SELinux

To configure SELinux, so that Apache can read/write to the /opt/processmaker directory. first login as "root" and issue the following commands from the terminal:

semanage fcontext -a -t httpd_sys_content_rw_t '/opt/processmaker(/.*)?'
restorecon -R -v /opt/processmaker

Then, configure Apache so it is able to send email:

setsebool -P httpd_can_sendmail 1

If needing to run ProcessMaker on any port other than the default ports of 80, 443, 488, 8008, 8009 and 8443, then SELinux needs to be configured to allow another port to be used. For example, if using port 8080:

semanage port -a -t http_port_t -p tcp 8080

Disabling SELinux

SELinux causes so many problems, that it often easier to simply disable it. To permanently disable SELinux, edit the SELinux configuration file:

vim /etc/selinux/config

In the config file, set the following parameter:

  SELINUX = disabled

Then, restart the server, so SELinux will be permanently disabled.

If needing to temporarily disable SELinux, in order to debug a problem, login as the "root" user and issue the command:

echo 0 > /selinux/enforce

To temporarily enable SELinux:

echo 1 > /selinux/enforce

Step 2: Installing Apache, MySQL and PHP

If Apache, MySQL or PHP are not already installed, then switch to the root user:

su
  Enter the root password

Then use yum to install Apache, MySQL and PHP:

yum install httpd php mysql-server mysql

Follow the instructions on the screen to install the Apache web server.

Next, install the PHP modules needed by ProcessMaker:

yum install php-gd php-mysql php-xml php-soap php-mbstring php-ldap php-cli php-curl

php-mcrypt is not in CentOS's standard repositories. However, it is in Fedora's EPEL repository.

Install the EPEL Repo:

For 32 bit:

rpm -Uvh http://download.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm

For 64 bit:

rpm -Uvh http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm

Then it is possible to execute:

yum install php-mcrypt

After changing the PHP configuration, restart the Apache service (or reboot the machine).

To check if all the PHP modules were installed, run the following command:

rpm -qa |grep php

In addition, phpMyAdmin can be installed to easily view the MySQL databases used by ProcessMaker inside a web browser. For some versions of RHEL/CentOS, phpMyAdmin will need to be manually installed.

Step 3: 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 Red Hat/CentOS 5.10 and earlier, then PHP's configuration file php.ini needs to be edited to increase the memory limit for each session.

Open the php.ini file with a plain text editor, which is located at:

/etc/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 processes, 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 4: Download & Extract ProcessMaker

Go to http://sourceforge.net/projects/processmaker/files and download a recent version of ProcessMaker. The versions are numbered according to the pattern MAJOR.MINOR.REVISION, such as 2.0.45. Download the processmaker-2.X.X.tar.gz file.

Note: Some older versions of ProcessMaker offered rpm files, but it is recommended to install from the tar.gz file if planning on installing in a directory other than /opt or doing an additional installation of ProcessMaker.

It is recommended to install ProcessMaker under the /opt directory, since it is an add-in application which doesn't come from the standard repositories. Nonetheless, ProcessMaker can be installed in any directory, except directories such as /var/www which are publicly accessible to the internet, since that would be a security hole.

Download the latest ProcessMaker tarball from http://sourceforge.net/projects/processmaker/files and save it to the server where ProcessMaker will be installed. Use the tar command to decompress the tar.gz file in the /opt directory (or where ever installing ProcessMaker):

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

This will create a new processmaker directory, containing all the ProcessMaker files and subdirectories.

Set File Permissions

After installing the ProcessMaker files either from the RPM package or from the tarball, make the following subdirectories writable for the "apache" user, so ProcessMaker can write to certain directories:

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

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 5: MySQL Configuration

Before using MySQL, use mysql_secure_installation to set up a secure database environment. Login as the "root" user and issue the following command:

mysql_secure_installation

Then follow the wizard to configure MySQL:

NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MySQL SERVERS IN PRODUCTION USE! PLEASE READ EACH STEP CAREFULLY!

In order to log into MySQL to secure it, we'll need the current password for the root user. If you've just installed MySQL, and you haven't set the root password yet, the password will be blank, so you should just press enter here.

Enter the MySQL root password:

 

Enter current password for root (enter for none): OK, successfully used password, moving on...

Then it is possible to change the MySQL root password:

 

Setting the root password ensures that nobody can log into the MySQL root user without the proper authorization.

You already have a root password set, so you can safely answer 'n'.

Change the root password? [Y/n] n ... skipping.

Then, it will ask about removing anonymous users:

 

By default, a MySQL installation has an anonymous user, allowing anyone to log into MySQL without having to have a user account created for them. This is intended only for testing, and to make the installation go a bit smoother. You should remove them before moving into a production environment.

Remove anonymous users? [Y/n] y ... Success!

Then it will ask about disabling root login:

 

Normally, root should only be allowed to connect from 'localhost'. This ensures that someone cannot guess at the root password from the network.

Disallow root login remotely? [Y/n] y ... Success!

Then, it is possible to change the MySQL database name:

 

By default, MySQL comes with a database named 'test' that anyone can access. This is also intended only for testing, and should be removed before moving into a production environment.

Remove test database and access to it? [Y/n] y - Dropping test database... ... Success! - Removing privileges on test database... ... Success!

Finally, reload privileges tables:

 

Reloading the privilege tables will ensure that all changes made so far will take effect immediately.

Reload privilege tables now? [Y/n] y ... Success!

Cleaning up...

All done! If you've completed all of the above steps, your MySQL installation should now be secure.

Thanks for using MySQL!

User other than root

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 steps 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 mysqld start

If MySQL was installed from its Red Hat/CentOS package, it should automatically start as a service on bootup. If not, then use use chkconfig to add it as a service:

 chkconfig --levels 345 mysqld on

Step 6: Apache Configuration

Copy ProcessMaker's sample configuration for Apache to conf.d directory:

cp /opt/processmaker/etc/pmos.conf /etc/httpd/conf.d/pmos.conf

Edit the ProcessMaker configuration file pmos.conf:

vim /etc/httpd/conf.d/pmos.conf

Modify the file to fit your environment:

# 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 Red Hat/CentOS 7.0), then change the following line from:

    Allow from all

To:

    Require all granted

Replace your_ip_adress 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 file 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 Apache configuration file found at /etc/httpd/conf/httpd.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, by opening the Apache configuration file found at /etc/httpd/conf/httpd.conf. The following 4 lines should be found in the list of Apache modules to load:

LoadModule expires_module modules/mod_expires.so
LoadModule rewrite_module modules/mod_rewrite.so
LoadModule deflate_module modules/mod_deflate.so
LoadModule vhost_alias_module modules/mod_vhost_alias.so

Note: If using Apache 2.4 (which is found in CentOS/Red Hat 7.0), either include the filter module:

LoadModule filter_module modules/mod_filter.so

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:

service httpd restart

Apache Configuration Issues

Setting Apache as Service

If Apache is not already running as a service, then configure it to automatically start as a service when booting up:

chkconfig --levels 345 httpd on

No ServerName Warning

If a similar warning message appears when restarting Apache:

httpd: 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 httpd.conf file and 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 httpd.conf file:

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.

If a firewall blocks traffic on non-standard ports, the port needs to be unblocked so it can be used by ProcessMaker. For example, if using an IPTables firewall, the following commands unblock the port 8080:

iptables -A INPUT -p tcp -m tcp --dport 8080 -j ACCEPT
iptables-save | tee /etc/sysconfig/iptables
service iptables restart

Step 7: Setting up ProcessMaker

Once all ProcessMaker configurations were set up, 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 at port 8080, go to: http://127.0.0.1:8080

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

Step 8: 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/httpd/conf/httpd.conf
The ProcessMaker web site configuration file for Apache:
/etc/httpd/conf.d/pmos.conf
The PHP configuration file:
/etc/php.ini
The MySQL configuration file:
/etc/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.