ProcessMaker Ubuntu Installation

From ProcessMaker

Jump to: navigation, search

Follow these instructions to install ProcessMaker on top of a LAMP (Linux, Apache, MySQL, PHP) stack in any version of Ubuntu between 6.10 (Edgy Eft) and 9.10 (Karmic Koala). If using Ubuntu 10.04 (Lucid Lynx) or later, an older version of PHP will need to be installed. See the Ubuntu 10.04 and later section.

Contents

Requirements

Server:

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

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

  • PHP 5.1.6 or greater (but not PHP 5.3.X due to this bug)

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.

Ubuntu 6.10 - 9.10

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, enter: 

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

When apt-get installs MySQL, a dialog box will appear asking for a new root password for MySQL.

Image:EnterMySQLRootPassword.png

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

deb http://us.archive.ubuntu.com/ubuntu/ karmic universe

If not using Ubuntu 9.10 (Karmic Koala), replace karmic with your version of Ubuntu. Then, update the list of available packages from the repositories: 

sudo apt-get update

Now, install phpMyAdmin: 

apt-get install phpmyadmin

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

Image:PhpMyAdminWhichWebServerDialog.png

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

Image:PhpMyAdminRootPasswordDialog.png

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

Image:PhpMyAdminApplicationPasswordDialog.png

Reconfirm that password by entering it a second time:

Image:PhpMyAdminApplicationPasswordReconfirmDialog.png

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: 

sudo 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 the shared and compiled directories don't exist (which is the case with older versions of ProcessMaker), then manually create them: 

cd /opt/processmaker
sudo mkdir shared compiled

Set file permissions

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

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

Configure MySQL

Create a user in MySQL with superuser privileges to create and update the tables needed by ProcessMaker to store date.

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: 

sudo /etc/init.d/mysql start

(If MySQL was installed from its Ubuntu 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 modifiy MySQL tables: 

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 you haven't created any additional MySQL users, 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;

Configure PHP

PHP needs to be configured for ProcessMaker to function correctly. Edit the php.ini configuration file. In Ubuntu 9.10 (Karmic Koala) and earlier: 

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

In Ubuntu 10.04 (Lucid Lynx) and later: 

sudo nano /etc/php5/cgi/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

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 and short tags: 

asp_tags = On
short_open_tag = 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: 

sudo /etc/init.d/apache2 reload

Configure Apache

Edit the ProcessMaker configuration file to fit your environment: 

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

If your DNS 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_adress. If only planning on running and accessing ProcessMaker on your local machine, then use the IP address "127.0.0.1".

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 apache2.conf.

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

sudo cp /opt/processmaker/etc/pmos.conf /etc/apache2/sites-available/
sudo 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: 

sudo a2enmod expires
sudo a2enmod rewrite 
sudo a2enmod deflate
sudo a2enmod vhost_alias

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

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

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

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: 

sudo a2dissite default
sudo /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.

Image:InstallPMConfigErrors.png

In the configuration page, enter in the username and password to access MySQL. Click on the Test button to verify that ProcessMaker is configured properly. Green checkmarks will indicate that the settings work correctly:

Image:InstallPMConfigGood.png

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.

Image:InstallPMSucess.png

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.

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

Ubuntu 10.04 and later

ProcessMaker currently does not function correctly with PHP 5.3.X, which creates problems with Ubuntu 10.04 (Lucid Lynx) and later versions of Ubuntu. To use ProcessMaker, install the PHP 5.2.10 packages from Ubuntu 9.10 (Karmic Koala).

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

sudo apt-get install mysql-server openssh-server

If Apache or PHP is already installed from the Lucid repository, then they will have to be completely removed: 

sudo apt-get --purge remove apache2 php5 php5-mysql php5-gd php5-ldap php5-curl php5-cli phpmyadmin
sudo apt-get --purge autoremove

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

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

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

apt-get --purge remove X

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

sudo nano /etc/apt/sources.list

Comment out all the existing repositories by adding # in front of all the repositories. Then, use the Karmic Koala repository by adding the following lines: 

deb http://us.archive.ubuntu.com/ubuntu/ karmic main
deb http://us.archive.ubuntu.com/ubuntu/ karmic universe

Refresh the list of available packages: 

sudo apt-get update

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

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

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

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

From there, follow the rest of the instructions above to configure Apache and MySQL and install 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
Retrieved from "http://wiki.processmaker.com/index.php/ProcessMaker_Ubuntu_Installation"
Personal tools
translations