Debian Installation

Follow these instructions to install ProcessMaker 1.X on top of a LAMP (Linux, Apache, MySQL, PHP) stack in Debian 4.0 (Etch) and later. In order to install ProcessMaker 1.8 or earlier in Debian 6.0 (Squeeze) or later, see the instructions in the section ProcessMaker 1.8 or earlier in Debian 6.0 to install the PHP packages from Lenny. To install ProcessMaker 2.0, see this page.

Requirements

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 ProcessMaker 1.8 or later or the Pentaho Reports plugin, MySQL 5.1.6 or later is required.)

• PHP 5.1.6 or greater (but not PHP 5.3.X if using ProcessMaker 1.8 or earlier])

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, users and reports.

Debian 4.0 and Later

Follow these instructions to install ProcessMaker in Debian (Etch) 4.0 and later.

Install MySQL, PHP, Apache

If the LAMP stack isn't already installed, open a shell by going to Applications > Accessories > Terminal. At the command line, switch to the "root" user and enter:

apt-get install mysql-server php5 apache2 php5-mysql php5-gd php5-ldap openssh-server 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.

Install PhpMyAdmin

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

apt-get install phpmyadmin

If asked which web server PhpMyAdmin should use, press the space bar to select "apache2":

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:

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 COMMIT number.

Download the file pmos-1.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-1.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 www-data:www-data -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 MySQL user other than "root" to set up the ProcessMaker databases, grant a MySQL user superuser privileges to create and update databases.

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

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:

/etc/init.d/mysql start

(If MySQL was installed from its Debian package, it should automatically start as a service on bootup. If not, then use update-rc.d to add it as a service.)

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. To avoid creating a new user, use 'root' as the user and the root's password.) 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;

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:

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

/etc/init.d/apache2 reload

Configure Apache

Edit the ProcessMaker configuration file to fit your environment:

nano /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 DNS at 123.456.7.89:

  NameVirtualHost 192.168.1.100:8080
  #processmaker virtual host
  <VirtualHost 192.168.1.100:8080 >
    ServerName "123.456.7.89"
    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/sites-available/
a2ensite pmos.conf

ProcessMaker needs to use the expires, rewrite, deflate and vhost_alias modules in the Apache 2 web server. Check to see whether these modules are enabled:

ls /etc/apache2/mods-enabled/

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

a2enmod expires
a2enmod rewrite 
a2enmod deflate
a2enmod vhost_alias

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

/etc/init.d/apache2 restart

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:

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

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.

If Apache is configured to display a default message like the following:

It works!

This is the default web page for this server.

The web server software is running but no content has been added, yet.

Then, disable Apache's default site:

a2dissite default
/etc/init.d/apache2 reload

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

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');
   }

ProcessMaker 1.8 or earlier in Debian 6.0

ProcessMaker 1.8 or earlier does not function correctly with PHP 5.3.X found in Debian 6.0 (Squeeze) and later versions of Debian. To use ProcessMaker 1.8 and earlier, first install the PHP 5.2.6 packages from Debian 5.0 (Lenny).

Note: ProcessMaker 1.9 and later is compatible with PHP 5.3.X, so these instructions aren't necessary if installing ProcessMaker 1.9 or later.

First install the packages which don't depend on PHP:

apt-get install mysql-server apache2 openssh-server

Then, edit the file /etc/apt/sources.list to change the repository for packages:

nano /etc/apt/sources.list

Comment out all the existing repositories by adding # in front of all the repositories. Then, use the Lenny repository by adding the following line:

http://ftp.us.debian.org/debian/ lenny main

Refresh the list of available packages:

apt-get update

After updating to draw packages from the Lenny repository, then install PHP and all the necessary libraries to run ProcessMaker:

apt-get install php5 php5-mysql php5-gd php5-ldap php5-curl php5-cli phpmyadmin

Then check if any Apache or PHP packages are still installed:

sudo dpkg --get-selections | grep -E "apache|php5|libapr"

If any packages appear, then manually remove them (replacing X with the package name):

apt-get --purge remove X

Then, reedit the list of repositories to return them to their original state and update the repositories again:

nano /etc/apt/sources.list
apt-get update

From there, follow the rest of the instructions above to install ProcessMaker, set file permissions, configure MySQL, configure PHP, configure Apache, and set up ProcessMaker.

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 link to set up an SSL-secured web server with Debian. 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:

/etc/init.d/apache2 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