3.0 - Install ProcessMaker in Ubuntu

Overview

Note: This platform is not officially supported by ProcessMaker and has NOT been tested by ProcessMaker QA department.

Follow these instructions to install ProcessMaker 3.0 or later on top of a LAMP (Linux, Apache, MySQL, PHP) stack in Ubuntu.

ProcessMaker Version	Platform	Notes
ProcessMaker 3.0 - 3.0.1.6	Ubuntu 10.04 LTS (Lucid) - 14.10 (utopic)
ProcessMaker 3.0.1.7	Ubuntu 12.10 (Quantal) - 14.10 (Utopic)	PHP needs to be upgraded to version 5.4.
ProcessMaker 3.0.1.8 - 3.0.4	Ubuntu 14.10 (Utopic) - 16.04 (Xenial Xerus)	PHP needs to be version 5.6.

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

Step 1: Install Apache, MySQL and PHP

Warning: ProcessMaker is not compatible with MySQL STRICT mode, which is enabled by default as of MySQL 5.6.6. Read the Turning Off MySQL STRICT Mode section to learn how to disable it.

If the LAMP stack isn't already installed, open a terminal by going to Applications > Accessories > Terminal.
At the command line, login with administrative powers (or as root if its password was set):

sudo -i Enter password

Then, follow the instructions according to your Ubuntu version:

• In Ubuntu 14.10 or earlier
• In Ubuntu 16.04

In Ubuntu 14.10 or earlier:

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

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.

In Ubuntu 16.04:

Ubuntu 16.04 comes with PHP 7 which is not supported by ProcessMaker. However, PHP 5.6 can be installed from an alternative repository:

add-apt-repository ppa:ondrej/php apt-get update

After adding the repository and updating apt-get, then install Apache 2.4, PHP 5.6 and MySQL 5.7 with the following command.

apt-get install apache2 mysql-server php5.6 php5.6-mbstring php5.6-mcrypt php5.6-mysql php5.6-xml php5.6-gd php5.6-ldap php5.6-curl php5.6-cli php5.6-soap

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:

Change vivid 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":

Select whether to configure the database with the dbconfig-common package. In most cases, it is easier to select :

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

The default configuration of PHP should be able to run ProcessMaker, however, check the following settings if PHP's configuration file php.ini has been modified.

Edit PHP's configuration file php.ini:

Ubuntu 14.10 or earlier:

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

Ubuntu 16.04:

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

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

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

It is also recommended to set the date.timezone to a your time zone, especially if using timer events in the Enterprise Edition. See this list of supported time zones.

date.timezone = America/New_York

Note: After installation, the same time zone should be set in the ProcessMaker interface by going to Admin > Settings > System and setting the Time Zone (or in the env.ini file).

After that, save the changes:

An rewrite php.ini:

Step 3: Download & Extract ProcessMaker

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

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 an optional program which doesn't come from the 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 contents:

Set file permissions

Then, 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 sudo chmod -R 770 shared workflow/public_html gulliver/js gulliver/thirdparty/html2ps_pdf/cache cd workflow/engine/ sudo chmod -R 770 config content/languages plugins xmlform js/labels sudo chown -R www-data:www-data /opt/processmaker

Step 4: MySQL Configuration

Set up a secure installation of MySQL, by removing the "test" database and the remote connections, with the following command:

mysql_secure_installation

Follow the wizard to secure MySQL:

Here it is necessary to enter root password:

In the next part, it is possible to change the root password if wanted.

Then, remove anonymous users by choosing "Y":

In this part, the prompt will ask about disabling root login. Answer Y to disable remote access.

Then, it is possible to remove the default "Test" database:

Finally, reload privileges tables:

Once done, restart the "mysql" service.

service mysql restart

Set a 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 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:

sudo 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:

sudo 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:

sudo update-rc.d mysql defaults

Step 5: Configure Apache

Copy the sample ProcessMaker configuration file (which is named pmos.conf.example) to Apache's list of available sites:

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

Then edit the pmos.conf file to fit your environment:

sudo nano /etc/apache2/sites-available/pmos.conf

To configure ProcessMaker in:

• Ubuntu 13.04 (raring) or earlier, see VirtualHost in Apache 2.2.
• Ubuntu 13.10 (saucy) or later, see 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 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 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 more information, see the Apache Virtual Hosts Documentation.

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.

Example 1:

Example 2:

Example 3:

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. And replace the /opt/processmaker by your installation directory:

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

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.

Example 1:

Example 2:

Example 3:

Then save and write the pmos.conf.

Enable site and modules

After editing the pmos.conf file, enable the ProcessMaker web site, as the "root" user:

sudo a2ensite pmos.conf

To activate the new configuration, reload the server.

service apache2 reload

ProcessMaker needs to use the following modules in the Apache 2 web server:

• ldap
• authnz_ldap
• deflate
• expires
• rewrite
• ssl
• vhost_alias

To check whether these modules are enabled, run the following command:

ls /etc/apache2/mods-enabled/

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

sudo a2enmod ldap sudo a2enmod authnz_ldap sudo a2enmod deflate sudo a2enmod expires sudo a2enmod rewrite sudo a2enmod ssl sudo a2enmod vhost_alias

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

sudo service apache2 reload

Apache Possible 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.

Disable the default Apache site

Then, disable the default site with the superuser permission:

Apache 2.2: a2dissite default /etc/init.d/apache2 reload

Apache 2.4: a2dissite 000-default.conf service apache2 reload

If the default page has not disabled, restart your ubuntu sesion. In another case if the default page is not displayed, skip this step.

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 follow the steps in the Installation Wizard in the web browser to complete the installation of ProcessMaker.

Step 7: Additional Configuration

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 to configure the following:

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 and setting the Time Zone. Another way to set the time zone is edit the env.ini configuration file.

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 or timer events, then the server running ProcessMaker has to be configured to periodically execute the cron.php file. See Executing Cron Scripts.

Configuring the mycrypt.ini

In case of having errors with the mycrypt extension, even if it was enabled, follow the steps below to fix the problem:

• Change the path of the mycrypt.so file location. Use the command line and write the locate command in order to find the path.

• Look for the mycrypt.ini file and open it.

• Copy the path of the mycrypt.so file in the mycrypt.ini file.

• Restart apache.

Errors during Installation

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

Depending on the errors found in the installation log file, check the following files:

The Apache configuration file:

The ProcessMaker web site configuration file for Apache:

The PHP configuration file:

The MySQL configuration file:

The ProcessMaker configuration file where components are installed:

The ProcessMaker configuration file for database connections:

The ProcessMaker redirection to login screen:

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 having other issues, please ask for help on our ProcessMaker forum.