Overview
Follow these instructions to install ProcessMaker 3.1, ProcessMaker 3.1.x or ProcessMaker 3.2 on CentOS or Red Hat Enterprise Linux.
ProcessMaker Version | Platform | Notes |
ProcessMaker 3.1.x - 3.2 | CentOS/RHEL 6 | PHP needs to be upgraded to version 5.6. |
ProcessMaker 3.1.x - 3.2 | CentOS/RHEL 7 |
Note: If installing ProcessMaker 3.1, ProcessMaker 3.1.x orProcessMaker 3.2 onCentOS 7, please follow the instructions on the page about our supportedStack 205 to install Apache, MySQL and PHP. Then, continue withStep 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.rpmrpm -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 filephp.ini has been modified. Log in as the root user and edit PHP's configuration filephp.ini:
nano /etc/php.ini
Search for the following lines and edit them using the following configuration:
file_uploads = Onshort_open_tag = Onmemory_limit =512Merror_reporting =E_ALL & ~E_DEPRECATED & ~E_STRICTdisplay_errors =Offpost_max_size =24Mupload_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 namedprocessmaker-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/processmakerchmod -R 770 shared workflow/public_html gulliver/js gulliver/thirdparty/html2ps_pdf/cachecd 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 commandls -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 thissection.
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. Followthese
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 usechkconfig 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.
- If using RHEL/CentOS 6, then configure a VirtualHost in Apache 2.2.
- If using RHEL/CentOS 7, then configure a VirtualHost in Apache 2.4.
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 andyour_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.NameVirtualHostyour_ip_address#processmaker virtual host<VirtualHostyour_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 foryour_processmaker_domain. Otherwise, use the same IP address foryour_processmaker_domain
as was used for your_ip_address. For more information, see theApache Virtual Hosts Documentation.
Note:It is also possible to define the virtual host for ProcessMaker in the Apache configuration by inserting the aboveVirtualHost 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 *:8080Listen 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 domainswww.example.com and any variant ofX.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 andyour_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 foryour_processmaker_domain. Otherwise, use the same IP address foryour_processmaker_domain
as was used for your_ip_address. For more information, see theApache Virtual Hosts Documentation.
Note:It is also possible to define the virtual host for ProcessMaker in the Apache configuration by inserting the aboveVirtualHost 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 domainswww.example.com and any variant ofX.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 andvhost_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.soLoadModule rewrite_module modules/mod_rewrite.soLoadModule deflate_module modules/mod_deflate.soLoadModule vhost_alias_module modules/mod_vhost_alias.soLoadModule 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 thehttpd.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 thehttpd.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 asNo. 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 theshared 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 onTest 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 ofpassword dos and don’ts. Also consider using a strong password generator likethis 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 theUse the current user as the database owner option. To change the name of the database, mark theChange 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 theFinish 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 optionDelete 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 theconfiguration 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. TheGet Started screen will appear:
To avoid seeing the Get Started screen on every subsequent login, mark the optionDon'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 toclear 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 mainenv.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 toAdmin > Settings > System. Another way to set the time zone is to edit theenv.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 thecron.php file. SeeExecuting 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.
