ProcessMaker openSUSE Installation

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

ProcessMaker version 1.8 and lower is not compatible with PHP 5.3, which is found in openSUSE 11.2 and higher. Follow these instructions to downgrade PHP from version 5.3 to version 5.2, before installing ProcessMaker 1.8 and lower.

Requirements

ProcessMaker 1.6 or lower

Server:

• Apache 2.2.3 or greater with the following modules enabled:
  • deflate
  • expires
  • rewrite
  • vhost_alias
• MySQL 4.1.20 or greater

     (If using the Pentaho Reports plugin, MySQL 5.1.6 or greater is required.)

• PHP 5.1.6 or greater (but PHP 5.3.X)

Client:

• Mozilla Firefox (recommended) or Internet Explorer version 7 or higher

ProcessMaker 1.8 or higher

Server:

• Apache 2.2.3 or greater with the following modules:
  • Deflate
  • Expires
  • Rewrite
  • Vhost_alias
• MySQL 5.1.6 or greater
• PHP 5.1.6 or greater

Client:

• Mozilla Firefox (recommended) or Internet Explorer version 7 or higher

Note: Although ProcessMaker can connect to other databases such as Oracle, SQL Server and PosgreSQL, MySQL needs to be installed to store information about processes, user roles, and report tables.

Install Apache, MySQL, and PHP

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

sudo -i  or  su    
   Enter password

Install Apache, MySQL, PHP and all its necessary libraries:

yast2 –i apache2 php5 php5-mysql apache2-mod_php5 mysql mysql-client mysql-community-server \
   php5-soap php5-mbstring php5-gd php5-mcrypt php5-ldap php5-curl

Set MySQL to automatically start as a service at bootup and turn on the service:

chkconfig --add mysql
rcmysql start

Then, set up a secure installation of mysql, by setting a root password and removing the "test" database:

mysql_secure_installation

Set Apache to automatically start as a service at bootup and turn on the service:

chkconfig --add apache2 
rcapache2 start

Make sure that the apache2 and mysql services will start on bootup. They should be listed as "on" for the runlevel on which your installation of OpenSuSE runs, which is generally level 5:

# chkconfig -l | grep -E "apache2|mysql" 
apache2                   0:off  1:off  2:off  3:on   4:off  5:on   6:off
mysql                     0:off  1:off  2:on   3:on   4:off  5:on   6:off

Check that Apache and PHP are working correctly, by adding an index.php file:

vi /srv/www/htdocs/index.php

Put this code in the file and save it:

<?php phpinfo(); ?>

Then, open a web browser on the server and enter the address:

http://localhost

Information about PHP should appear in the browser window, indicating that PHP is working correctly:

Install PhpMyAdmin

In addition, phpMyAdmin can be installed to easily view the MySQL databases used by ProcessMaker inside a web browser.

Install ProcessMaker

Go to SourceForge and find the latest version of ProcessMaker. The versions are numbered according to the pattern MAJOR.MINOR-COMMIT, such as "1.2-2985". For the latest version of ProcessMaker, look for the highest numbers.

Download the file pmos-X.X-XXXX.tar.gz, which is available at: http://sourceforge.net/projects/processmaker/files

After the download has finished, decompress the file in the /opt directory with the command:

tar --directory /opt -xzvf pmos-X.X-XXXX.tar.gz

Verify that ProcessMaker was correctly decompressed:

ls /opt/processmaker

The processmaker directory should contain the following content:

compiled  etc  gulliver  LICENSE.txt  rbac  README.txt	shared	workflow

If using ProcessMaker version 1.2-2865 or older, manually create the shared and compiled directories:

cd /opt/processmaker
mkdir shared compiled

Set file permissions

Then, issue the following commands as the root user so that ProcessMaker can access the necessary files:

cd /opt/processmaker
chmod 777 shared compiled
cd /opt/processmaker/workflow/engine/
chmod 777 config content/languages plugins xmlform js/labels
chown wwwrun:www -R /opt/processmaker

Configure MySQL

The MySQL "root" user should already have all the necessary privileges to setup the ProcessMaker databases. If planning on using a different MySQL user to set up the ProcessMaker databases, then use the following instructions to grant superuser privileges to another MySQL user.

Login to MySQL:

mysql -u root -p 

Enter the root password for MySQL. (If you have forgotten the root password, see these instructions to reset it.)

Once in MySQL, give the user who 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 planning on 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 will be located.

Exit MySQL:

mysql> exit;

Increasing the thread stack size

According to the Mysql Manual [1] the default thread stack is 128 K, but sometimes it is necessary to execute long queries eg. long joins. To avoid the Thread stack overrun problem (MySQL ERROR 1436):

ERROR 1436 (HY000) at line 5992: Thread stack overrun: 8384 bytes used  of a 131072 byte stack,
and 128000 bytes needed. Use 'mysqld -O  thread_stack=#' to specify a bigger stack.

The size of the thread must be changed.

• Edit the MySql file configuration:

/etc/mysql/my.cnf

• Change the following line:

The stack size of each thread (default: 192K)
thread_stack = 512K

• Restart MySql Service

Configure PHP

PHP needs to be configured for ProcessMaker to function correctly. Edit the php.ini configuration file:

vi /etc/php5/apache2/php.ini

Each ProcessMaker session needs a minimum of 80MB RAM to run properly, so set the memory_limit to 80M or greater:

memory_limit = 80M

In order to upload Input Documents, upgrade ProcessMaker and add plugins and languages, file_uploads need to be enabled:

file_uploads = On

ProcessMaker needs to use PHP's short opening tags:

short_open_tag = On 

If planning on uploading large 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 16MB, then:

max_post_size = 16M 
upload_max_filesize = 16M

If using ProcessMaker 1-2.2552 or a previous version, enable ASP tags:

asp_tags = On

If using a version before ProcessMaker 1.0-1286, disable magic quotes:

magic_quotes_gpc = Off

Now, reload Apache for the settings to take effect:

rcapache2 reload

Configure Apache

Edit the ProcessMaker configuration file to fit your environment:

vi /opt/processmaker/etc/pmos.conf

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

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 example, if running ProcessMaker on a server at address 192.168.1.100 on port 8080 with a domain at processmaker.mycompany.com:

  NameVirtualHost 192.168.1.100:8080
  #processmaker virtual host
  <VirtualHost 192.168.1.100:8080 >
    ServerName "processmaker.mycompany.com"
    DocumentRoot /opt/processmaker/workflow/public_html
    DirectoryIndex index.html index.php
    <Directory  "/opt/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 file /etc/apache2/apache2.conf.

After editing pmos.conf, add it to Apache's list of sites which are available for serving:

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

ProcessMaker needs to use the expires, rewrite, deflate and vhost_alias modules in the Apache 2 web server. All these modules are included in openSUSE's apache2 package, but only expires is enabled by default.

To enable the other Apache modules from the graphical interface, open the YaST2 Control Center and go to ' System > /etc/sysconfig Editor > Network > WWW > Apache2 > APACHE_MODULES. Make sure that expires is in the list of modules and add: rewrite deflate vhost_alias

To enable the other Apache modules from the command line:

vi /etc/sysconfig/apache2

Search for the APACHE_MODULES variable and edit its list of modules to include expires, rewrite, deflate and vhost_alias. For example:

APACHE_MODULES="actions alias auth_basic authn_file authz_host authz_groupfile authz_default authz_user autoindex 
cgi dir env expires include log_config mime negotiation setenvif ssl userdir php5 deflate vhost_alias rewrite"

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

rcapache2 restart

If running ProcessMaker off a port other than the default port 80, then add the following line to the file /etc/apache2/listen.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.

If you see one of the following messages when reloading or restarting Apache:

[warn] NameVirtualHost 12.34.56.78:80 has no VirtualHosts
[warn] NameVirtualHost *:0 has no VirtualHosts
[warn] NameVirtualHost *:80 has no VirtualHosts

Then, comment out or delete the following lines in the file /etc/apache2/listen.conf:

NameVirtualHost 12.34.56.78:80
NameVirtualHost *:80
NameVirtualHost *

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 with port 8080, then go to: http://192.168.10.100:8080
If using ProcessMaker which is installed locally, go to: http://127.0.0.1

The installation configuration page should appear to setup ProcessMaker. If the default Apache page appears, then first disable it and try again.

In the configuration page, enter in the username and password to access MySQL. This should be a user such as "root" who has privileges to create new MySQL databases. Click on the Test button to verify that ProcessMaker is configured properly. Green checkmarks will indicate that the settings work correctly:

To change a setting after clicking Test, click on Reset. To change the default administrator username and password, select the option in the ProcessMaker Configuration section. Once all the settings are properly configured click on Install to install processmaker. The installation screen should indicate SUCCESS.

Click on Finish Installation, to redirect to the ProcessMaker login screen. Enter the username of "admin" and the password of "admin" and the workspace name, which by default is "workflow". Once logged in as the administrator, new users and processes can be created inside ProcessMaker. To login with a different workspace, language or skin, see the Login section.

If the ProcessMaker configuration screen appears the next time you try to login, press CTRL+F5 to clear Firefox's cache.

Note: It is a good idea to reset the administrator's password to something more secure in the future before using ProcessMaker in production.

Setting the Default Time Zone

Default Time Zone in version 2.0.8 and earlier

To set the default time zone for the ProcessMaker server, open the file <INSTALL-DIRECTORY>/workflow/engine/config/paths.php with your preferred plain text editor. Search for line 121 that defines the TIME_ZONE constant:

     define('TIME_ZONE', 'America/La_Paz');

Replace the default value 'America/La_Paz' with your time zone. A list of available timezones can be found at: http://php.net/manual/en/timezones.php

For example, to change the time zone to Vienna's time:

 ///************TimeZone Set***************//
   if(!defined('TIME_ZONE')) {
     define('TIME_ZONE', 'Europe/Vienna');
   }

Configuring ProcessMaker to use SSL

If your organization needs greater security to protect sensitive data being passed between web clients and the ProcessMaker server, it may be a good idea to set up a SSL connection which can be accessed through the https protocol (rather than the standard http protocol).

Follow the steps in this tutorial to set up an SSL-secured web server with openSUSE. After creating the certificates that will used by the ProcessMaker server, then configure ProcessMaker to use https in Apache.

Edit the file /etc/apache2/sites-available/pmos.conf and add the following lines in bold:

  # 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     
    #  Add this part for https
    SSLEngine on
    SSLCertificateFile /etc/apache2/apache.pem
    SSLOptions +FakeBasicAuth +ExportCertData +StrictRequire
    <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>

Then restart the Apache web server so the altered configuration will take effect:

rcapache2 restart

Now it possible to use ProcessMaker over SSL. Login to ProcessMaker by using the https protocol:

https://<IP-ADDRESS>/sys/en/green/login/login.html