3.3 - Install ProcessMaker in Debian 9 (Stretch)

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.3.X on top of a LAMP (Linux, Apache, MySQL, PHP) stack in Debian 9 (Stretch).

ProcessMaker 3.3 is compatible with PHP 7.0 and Apache 2.4 found in the official Debian 9 repository, but it is recommended to install MySQL 5.6 from Oracle's repository for Debian. Note that MariaDB may also be used with ProcessMaker 3.3, but it not been tested by the QA team.

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

Step 1: Install MySQL

First login as root or use sudo -i to gain root access:

su or sudo -i

(All the rest of the commands in this document should be issued as the root user.)

Then, download and install the package to use Oracle's repository for MySQL.

wget http://repo.mysql.com/mysql-apt-config_0.8.9-1_all.deb dpkg -i mysql-apt-config_0.8.9-1_all.deb

When installing the MySQL repository, a configuration screen will appear in the terminal, asking packages should be included. Use the arrow keys to select the option "MySQL Server and Cluster" and press ENTER.

Then, in the next configuration screen that appears, select "mysql-5.6" and then press TAB to select OK and press ENTER.

When returning to the first screen, select "OK" and press ENTER to finish configuring the repository.

Then, update the list of available packages:

apt update

Then, install PHP 5.6:

apt install mysql-server

When MySQL is being installed, a dialog box will appear asking for a new root password for MySQL.

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

Then, verify that MySQL is correctly configured as a service:

systemctl status mysql

(Press q to quit.)

Then, configure MySQL to turn off MySQL STRICT mode, which is enabled by default in MySQL 5.6.6 and later. Also, make sure that ONLY_FULL_GROUP_BY mode is not enabled, which is the default in MySQL 5.7.5 and later.

First, login to MySQL and verify the current settings for sql_mode:

mysql -u root -p

Once inside MySQL, issue the following command:

mysql> SELECT @@SESSION.sql_mode, @@GLOBAL.sql_mode; +------------------------+------------------------+ | @@SESSION.sql_mode | @@GLOBAL.sql_mode | +------------------------+------------------------+ | NO_ENGINE_SUBSTITUTION | NO_ENGINE_SUBSTITUTION | +------------------------+------------------------+ 1 row in set (0,00 sec)

The sql_mode should not include NO_ENGINE_SUBSTITUTION, STRICT_ALL_TABLES, STRICT_TRANS_TABLES or ONLY_FULL_GROUP_BY settings. If any of those settings are included, then copy the current sql_mode settings, but exclude those four. Then, exit MySQL:

mysql> EXIT;

Then, edit the file /etc/mysql/conf.d/mysql.cnf to change the sql_mode:

nano /etc/mysql/conf.d/mysql.cnf

Under the [mysqld] section, add the sql_mode settings which don't include the above four settings which aren't allowed. In this example, there are none, so set:

[mysqld] sql_mode=""

Then, exit nano by pressing CTL and x simultaneously and press y to the question asking if the changes should be saved.

Then, restart the mysql service for new configuration to take effect:

systemctl restart mysql

Step 2: Install PHP and Apache

As the root user, install Apache 2.4 and PHP 7.0 from the Debian repository with the following command in the terminal:

apt install php7.0 apache2 php7.0-mysql php7.0-gd php7.0-ldap php7.0-curl php7.0-cli php7.0-mcrypt php7.0-soap php7.0-xml

Install PhpMyAdmin

Install PhpMyAdmin with the following command:

apt install phpmyadmin

When asked which web server PhpMyAdmin should use, press the space bar to select "apache2" and then press TAB to select OK and press ENTER to continue:

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

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

Reconfirm that password by entering it a second time.

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

Step 3: 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 7.0's configuration file php.ini:

nano /etc/php/7.0/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 editing the php.ini file, save the changes in Nano by pressing CTL+X and pressing y when asked whether to save the changes.

Step 4: Download & Extract ProcessMaker

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

If downloading from the command line, the wget command can be used to obtain the ProcessMaker code: wget https://razaoinfo.dl.sourceforge.net/project/processmaker/ProcessMaker/3.3.0/processmaker-3.3.0-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-3.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, change the ownership of the ProcessMaker files, so that they can be accessed by the Apache server:

chown -R www-data:www-data /opt/processmaker

Step 5: 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.

systemctl restart mysql

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:

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:

systemctl start mysql

If MySQL was installed from Oracle's MySQL repository, 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 6: Configure Apache

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

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

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

nano /etc/apache2/sites-available/pmos.conf In Apache 2.4, 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 /opt/processmaker with 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 1: 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.

Note 2: If using Apache's mod_proxy_fcgi and php-fpm, then add the following line to the virtualhost definition: SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1