Contents: [hide]

Overview

Follow these instructions to install ProcessMaker 3.1, ProcessMaker 3.1.x or ProcessMaker 3.2.x on CentOS or Red Hat Enterprise Linux.

ProcessMaker Version Platform Notes
ProcessMaker 3.1.x - 3.2.x CentOS/RHEL 6 PHP needs to be upgraded to version 5.6.
ProcessMaker 3.1.x - 3.2.x CentOS/RHEL 7 Stack 205

Note: If installing ProcessMaker 3.1, ProcessMaker 3.1.x or ProcessMaker 3.2.x on CentOS 7, please follow the instructions on the page about our supported Stack 205 to install Apache, MySQL and PHP. Then, continue with Step 2 and next steps in this guide.

Before installing ProcessMaker, check the Installation Requirements to see whether your server meets the necessary hardware and software requirements.

Step 1: Installing Apache, MySQL and PHP

Warning: ProcessMaker is not compatible with MySQL STRICT mode, which is enabled by default in MySQL 5.7. Read the Turning Off MySQL STRICT Mode section to learn how to disable it. Since MySQL 5.7 is NOT part of any official ProcessMaker stack, ProcessMaker has not been tested entirely in this version of MySQL. Therefore, ProcessMaker may not run correctly even if STRICT mode is disabled.

To install Apache, MySQL or PHP, first switch to the root user:

su Enter the root password

Then, add the following repositories:

rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm rpm -Uvh https://mirror.webtatic.com/yum/el6/latest.rpm

Use yum to install Apache, MySQL and PHP:

yum install httpd php56w mysql55w mysql55w-server

Next, install the PHP modules needed by ProcessMaker:

yum -y install php56w-mysqlnd php56w-gd php56w-soap php56w-ldap php56w-xml php56w-mbstring php56w-cli php56w-curl php56w-mcrypt php56w-devel php56w-pecl-apcu

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

rpm -qa |grep php

The outcome will be similar to the following:

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.

yum -y install phpmyadmin

Step 2: Configuring PHP Settings

The default configuration of PHP should be able to run on ProcessMaker; however, check the following settings to see if PHP's configuration file php.ini has been modified. Log in as the root user and edit PHP's configuration file php.ini:

nano /etc/php.ini

Search for the following lines and edit them using the following configuration:

file_uploads = On short_open_tag = On memory_limit = 512M error_reporting = E_ALL & ~E_DEPRECATED & ~E_STRICT display_errors = Off post_max_size = 24M upload_max_filesize = 24M

Step 3: Download & Extract ProcessMaker

Go to ProcessMaker's SourceForge page and download the most recent tarball of ProcessMaker, which should be named processmaker-X.X.X-community.tar.gz.

Or download the tar.gz file with wget.

wget 'https://sourceforge.net/projects/processmaker/files/ProcessMaker/3.1/processmaker-3.1-community.tar.gz/download'

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

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

Verify that ProcessMaker was correctly decompressed:

ls /opt/processmaker

The processmaker directory should contain the following content:

Set File Permissions

Issue the following commands as the root user so that ProcessMaker can access the necessary files when run by the Apache server:

cd /opt/processmaker chmod -R 770 shared workflow/public_html gulliver/js gulliver/thirdparty/html2ps_pdf/cache cd workflow/engine/ chmod -R 770 config content/languages plugins xmlform js/labels

In CentOS, the Apache service runs as the user apache by default. Therefore, the ownership of the ProcessMaker directory must belong to apache, so that Apache can read and write data. The -R makes the ownership changes recursive (apply to all files and directories within /opt/processmaker).

chown -R apache:apache /opt/processmaker

After these changes, verify the permissions and owner of the processmaker directory with the command ls -l.

Step 4: MySQL Configuration

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

mysql_secure_installation

Then follow the wizard's instructions to secure MySQL:

Here it is necessary to enter the root password:

Then it is possible to change the root password:

Warning: ProcessMaker does NOT support special characters (such as: @ # $ % ^ & ( /) in the root password. For more information, please read this section.

In the next part, it will ask the user if they want to remove anonymous users:

Then it will ask if the root login should be disabled:

The wizard will then ask if the test database should be removed:

Finally, reload privilege tables:

The MySQL installation is now secure.

Once done, restart the mysql service.

service mysql restart

Warning: When MySQL is installed, strict mode is enabled by default, which causes ProcessMaker to not work properly. Follow these instructions to disable strict mode in MySQL so that ProcessMaker works correctly.

MySQL Possible 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 RHEL/CentOS package, it should automatically start as a service on bootup. If not, then use chkconfig to add it as a service:

chkconfig --levels 345 mysqld on

MySQL Password with Special Characters

The following error is displayed during the ProcessMaker installation when the MySQL password contains a character that is not a letter or a number, like: @ # $ % ^ & ( /.

Warning: array_pop() expects parameter 1 to be array, boolean given in /srv/processmaker/processmaker/gulliver/thirdparty/creole/Creole.php on line 314

Please change/reset your MySQL password and try to install ProcessMaker again. This is a known issue that will be fixed in ProcessMaker 3.2.

Step 5: Apache Configuration

First, disable the Apache welcome page with the following command:

rm -f /etc/httpd/conf.d/welcome.conf

Then, copy the sample ProcessMaker configuration file to Apache's conf.d directory: cp /opt/processmaker/pmos.conf.example /etc/httpd/conf.d/pmos.conf

Edit the pmos.conf file to fit your environment:

nano /etc/httpd/conf.d/pmos.conf

The Apache configuration needed to run ProcessMaker depends on the version of Apache.

VirtualHost in Apache 2.2

If using Apache 2.2, then use the following VirtualHost configuration. In the pmos.conf file, 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 your own subdomains. NameVirtualHost your_ip_address #processmaker virtual host <VirtualHost your_ip_address > ServerName "your_processmaker_domain" DocumentRoot /opt/processmaker/workflow/public_html <Directory /opt/processmaker/workflow/public_html> AddDefaultCharset UTF-8 AllowOverRide All Options FollowSymlinks Order allow,deny Allow from all RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^(.*)$ /app.php [QSA,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" #Deflate filter is optional. It reduces download size, but adds slightly more CPU processing: AddOutputFilterByType DEFLATE text/html </Directory> </VirtualHost>

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 also necessary to 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 more information, see the Apache Virtual Hosts Documentation.

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

Example 1:

ProcessMaker is installed in the /opt/processmaker directory and is running on a server at the address 192.168.1.100:

NameVirtualHost 192.168.1.100 #processmaker virtual host <VirtualHost 192.168.1.100> ServerName "192.168.1.100" DocumentRoot /opt/processmaker/workflow/public_html ...

Example 2:

ProcessMaker is installed in the /user/fred directory on your local machine at port 8080 with a dynamic IP assigned by DHCP:

NameVirtualHost *:8080 Listen 8080 #processmaker virtual host <VirtualHost *:8080 > ServerName "*" DocumentRoot /user/fred/processmaker/workflow/public_html ...

Example 3:

ProcessMaker is installed in the /opt/pm3.1 directory at the IP address 123.45.67.89 and the domains www.example.com and any variant of X.example.com:

NameVirtualHost 123.45.67.89 #processmaker virtual host <VirtualHost 123.45.67.89 > ServerName "www.example.com" ServerAlias "*.example.com" DocumentRoot /opt/pm3.1/processmaker/workflow/public_html ...

Note that www.example.com and *.example.com need to be defined in the server's DNS or /etc/hosts file for this example to work correctly.

VirtualHost in Apache 2.4

If using Apache 2.4, then use the following VirtualHost configuration. In the pmos.conf file, replace your_ip_address and your_processmaker_domain with the IP address or domain name used by your ProcessMaker server:

#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> Options Indexes FollowSymLinks MultiViews AddDefaultCharset UTF-8 AllowOverride All Require all granted ExpiresActive On <IfModule mod_rewrite.c> RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^.*/(.*)$ app.php [QSA,L,NC] </IfModule> #Deflate filter is optional. It reduces download size, but adds slightly more CPU processing: AddOutputFilterByType DEFLATE text/html </Directory> </VirtualHost>

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. To use a port other than port 80, then it is also necessary to 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 more information, see the Apache Virtual Hosts Documentation.

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

Example 1:

ProcessMaker is installed in the /opt/processmaker directory and is running on a server at the address 192.168.1.100:

#processmaker virtual host <VirtualHost 192.168.1.100> ServerName "192.168.1.100" DocumentRoot /opt/processmaker/workflow/public_html ...

Example 2:

ProcessMaker is installed in the /user/fred directory on your local machine at port 8080 with a dynamic IP assigned by DHCP:

Listen 8080 #processmaker virtual host <VirtualHost *:8080 > #don't include ServerName DocumentRoot /user/fred/processmaker/workflow/public_html ...

Example 3:

ProcessMaker is installed in the /opt/pm3.1 directory at the IP address 123.45.67.89 and the domains www.example.com and any variant of X.example.com:

#processmaker virtual host <VirtualHost 123.45.67.89 > ServerName "www.example.com" ServerAlias "*.example.com" DocumentRoot /opt/pm3.1/processmaker/workflow/public_html ...

Note that www.example.com and *.example.com need to be defined in the server's DNS or /etc/hosts file for this example to work correctly.

Enable Apache Modules

ProcessMaker needs to use the expires, rewrite, deflate and vhost_alias modules on the Apache web server. Check to see whether these modules are enabled by opening the Apache configuration file found at /etc/httpd/conf/httpd.conf.

nano /etc/httpd/conf/httpd.conf

If working with CentOS 7, the file used to configure modules is found at:

nano /etc/httpd/conf.modules.d/00-base.conf

Uncomment the following modules (remove the semicolon ; at the beginning of each line):

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 LoadModule filter_module modules/mod_filter.so

After editing the pmos.conf and httpd.conf files, it is necessary to restart the Apache web server to use the new configuration: service httpd restart

Apache Possible Configuration Issues

Setting Apache as a 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 warning message similar to the one below 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 a local machine, then:

ServerName 127.0.0.1

Non-standard Port

If running ProcessMaker on a port other than the default port 80, add the following line to the httpd.conf file:

Listen ip-address:port

For instance, if running ProcessMaker from a 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 to not use port 80. Check whether a program is currently listening on port 80 with the command:

netstat -tanp

Step 6: 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 temporarily or permanently.

Configuring SELinux

To configure SELinux so Apache can read/write to the /opt/processmaker directory, first log in as the root user 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 emails:

setsebool -P httpd_can_sendmail 1

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

semanage port -a -t http_port_t -p tcp 8080

Finally, do NOT forget to restart the server.

Disabling SELinux

SELinux causes so many problems that it is often easier to simply disable it. Run the following commands to disable SELinux:

echo "SELINUX=disabled" > /etc/selinux/config echo "SELINUXTYPE=targeted" >> /etc/selinux/config

Finally, do NOT forget to restart the server to permanently disable SELinux.

Temporarily Disabling SELinux

To temporarily disable SELinux to debug a problem, log in as the root user and issue the command:

echo 0 > /selinux/enforce

To temporarily enable SELinux:

echo 1 > /selinux/enforce

Finally, do NOT forget to restart the server for the changes to take effect.

Step 7: Setting up ProcessMaker

Once all ProcessMaker configurations are 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 it 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 of ProcessMaker. The wizard should work on any type of computer that is capable of running Apache, PHP and MySQL.

Pre-Installation Check

The first step of the installation wizard checks whether the server meets the requirements to install ProcessMaker:

This step checks the versions of PHP, MySQL and cURL and ensures that the necessary PHP modules are enabled and the PHP memory_limit is at least 80MB. Requirements that are not met will be marked as No. Fix any missing requirements before continuing with the installation.

File Permissions

The second step of the installation wizard lists the paths of the directories where ProcessMaker stores its files and checks whether those directories have the correct file permissions:

If there is a problem accessing some files or directories, check to make sure the file permissions of the directories are set so the Apache user running ProcessMaker can access them.

It is possible to change the location of the shared directory, where files containing process and case data are stored. This directory is placed inside the ProcessMaker installation directory under shared by default, but it can be placed in another location or on a Network Address Translation (NAT) server. If the default location for the shared directory is not used, make sure that the chosen location has the proper file permissions so that it can be accessed by ProcessMaker, but is still restricted from normal users on the server who shouldn't have access to sensitive files. It is recommended to regularly backup the shared directory and MySQL files to prevent data loss.

ProcessMaker Open Source License

The third step of the installation wizard displays the ProcessMaker license.

Mark the option I agree and click on Next to continue the installation.

Database Configuration

The fourth step of the installation wizard configures the connection to the MySQL database. Enter the name and password of a MySQL user, such as the root user, who has permission to set up new databases in MySQL. Then click on Test Connection to see whether that user can log in to MySQL and set up the ProcessMaker databases.

If ProcessMaker can't connect to MySQL,cannot log in with the user's credentials, or if the database already exists, an error message will appear.

Edit the information in the database configuration and click on Test Connection again.

Workspace Configuration

The last step of the Installation Wizard configures the username and password of the Administrator user, which are both "admin" by default.

Important! The “admin” user will be able to access all the features and functionalities in the ProcessMaker installation, such as: system configuration, process creation and editing, user and group management, case management, and report and dashboard oversight, among others. Thus, it is strongly recommended to create a strong password for this account. Take a look at this list of password dos and don’ts. Also consider using a strong password generator like this one.

The ProcessMaker workspace and its database can also be configured in this step.

The name of the workspace can be changed from the default, which is "workflow". It may be useful to set up separate workspaces for each department or division in an organization, or for separate sets of processes.

By default, the installation wizard will create a new MySQL user who will be granted access to a new database named "wf_workflow" that will store ProcessMaker data. To use the existing MySQL user from Step 3 instead of creating a new user, mark the Use the current user as the database owner option. To change the name of the database, mark the Change database name option.

Then click on the Check workspace Configuration button to verify that the configuration is correct. The message "The configuration is correct." will be displayed and the Finish button will be enabled.

If there is an error in the configuration, the message "Not passed." will be displayed in the dialog.

For example, if a database of the same name already exists, an error message will be displayed in the bottom right corner.

In this case, mark the option Change database name and enter a different name for the database that will be created by ProcessMaker, or mark the option Delete Database if it exists:

When the configuration is correct, click on the Finish button to create the workspace database.

If there are no problems, the message "ProcessMaker was successfully installed" will be displayed.

If there was a problem creating the database an error message will be displayed. In this case, check the configuration of MySQL and its my.cnf file.

If there was a problem writing the ProcessMaker files, change the file permissions of the directories to give Apache access.

First Login

Once ProcessMaker has been successfully installed, the web browser will be redirected to the login page. The Get Started screen will appear:

To avoid seeing the Get Started screen on every subsequent login, mark the option Don't show me again.

Then, enter the username and password of the Administrator user, which is "admin" by default, but a different username could have been configured in Step 4 of the installation wizard. Enter the name of the workspace that was configured in Step 4, which is named "workflow" by default, then click on Login to enter ProcessMaker.

The login page can be customized. For more information see Login Settings.

Note: If a previous version of ProcessMaker was accessed by the web browser unintentionally, it is recommended to clear the browser cache after installing ProcessMaker to clear any stored pages from previous versions of ProcessMaker.

Step 8: env.ini Configuration

Once ProcessMaker is installed, some additional parameters must be set in the main env.ini configuration file.
To do this, edit the env.ini file located at <install-directory>/processmaker/workflow/engine/config/env.ini. For example:

nano /opt/processmaker/workflow/engine/config/env.ini

Add the following lines:

display_errors = Off memory_limit = 512M (the same value set in php.ini configuration step.)

Save changes and restart Apache.

Step 9: Additional Configurations

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

Setting the Time Zone

The default time zone for the ProcessMaker server can be set by logging into ProcessMaker with the "admin" user and going to Admin > Settings > System. Another way to set the time zone is to edit the env.ini configuration file.

Configuring Email

To send out email notifications or allow users to recover forgotten passwords via email, then see Email - Settings to configure ProcessMaker to use an email server.

Execution of cron.php

To use email notifications or timer events, then the server running ProcessMaker has to be configured to periodically execute the cron.php file. See Executing Cron Scripts.

Errors During Installation

If an error occurs during the installation, check the installation log file:

<install-directory>/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 website 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 the components are installed:

<install-directory>/workflow/engine/config/paths_installed.php

The ProcessMaker configuration file for database connections:

<install-directory>/shared/sites/workflow/db.php

The ProcessMaker redirection to login screen:

<install-directory>/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 there are other issues, please ask for help on our ProcessMaker forum.