How-To: Installing ProcessMaker on a CPanel server

Who This Tutorial Is For

This tutorial is intended for server administrators and web developers with the need to get a ProcessMaker site up and running.

What You Will Gain

After reading this tutorial, you will know how to setup a fully functioning and operational ProcessMaker installation on a CPanel server.

What You Will Need

In this tutorial you are going to need the following:

  • An internet connection.
  • If installing ProcessMaker on a remote server, access to the remote server via SSH.
  • Root access.
  • An SSH Client. If on Windows you can use Putty. If on any Unix based system via a Terminal.
  • Access to CPanel with the permissions to: create 3 databases and 1 database user and the rights to create a sub domain.
  • WHM Access. If you cannot gain WHM Access, you will need your server administrator to help you complete the installation.
  • Fulfill all the configuration requirements for installing ProcessMaker. The requirements can be found here.

Why I Wrote This Tutorial

How many of you have a CPanel server? How many of you were unable to install ProcessMaker on it because of the silly way that CPanel forces you to do things?

CPanel is nice. It does makes life easy for you. It keeps your users all clean, tidy and separate. But how do you get a web application with a very specific set of custom Apache configurations and PHPÂ settings and a specific MySQL arrangement to all play nicely with CPanel, who, likes to do things HIS way (to put it mildly).
Well here’s the good news, I have done this many times before. I have worked out all the problems and how to overcome them. I will show you how to easily setup ProcessMaker on a CPanel server.

Let’s give it a whirl then, shall we?

Before We Get Started

Now, before we get the ball rolling here, I just wanted to point out that there are indeed many ways to skin a cat.

Just because I do something a certain way, doesn’t mean that you have to do it that way too. I do things in certain ways just because time and experience has taught me so. I have found that if you plan for something in advance, however remote the possibility of it actually happening, then not only will your application be more robust and function better, but it also sometimes protects you from things you hadn’t even realized.

So, one of the fantastic things about CPanel, is the way it handles users for you. From the user management perspective to the backup and packaging of accounts either for external storage or transferring servers.

Setting Up The User Account

Therefore, the first step is to create a user in CPanel that will act as the user for the ProcessMaker application.

To do this, we need to login to the WHM side of things. You may not have access to this, so in that case you will need to contact your server administrator. Access to the WHM is pretty much the equivalent of root access via SSH. The only difference is, you are using the WHM interface. This makes things easy and simple for you.
Assuming you have access to the WHM side of things, in the search box on the top left, right above the list of navigational links, go ahead and type Create a New Account.
Fill in all your typical values that you would for an account. Keep in mind this account will be servicing one application. ProcessMaker.
I find that as a rule of thumb, it is best to always leave things as default unless a) you know exactly what it is you are changing b) you have a very good reason to change it.
Now your user account is setup.
Next, check that the IP (Internet Protocol) address is correct, otherwise you will need to change it to the correct address.
If you do need to change the IP address, type in the search box on the top left corner, right above the navigational menu: Change Sites IP Address.

Then, select the User Account that we just created and choose the right IP from the list of available IPs.

Installing ProcessMaker

Now that we have our User Account all setup, it is time to download the tar ball and install ProcessMaker.

For the sake of simplicity, we will refer to the User Account name as pmuser for the remainder of the tutorial.
Download the latest ProcessMaker tar ball (can be found here) to /home/pmuser.
cd /home/pmuser
Once the file has finished downloading, type in the following command:
$tar -C public_html -xzvf tarball_name.tar.gz
Just a quick explanation of the tar command used:
tar is a compression program for linux, -C is shorthand for –directory command, which specifies where to unzip the file to, the “xzvf part:
v : Verbose. Output the name of each file preceded by the function letter. With the t function, v provides additional information about the tarfile entries. The listing is similar to the format produced by the -l option of the ls command.
f : File. Use the tarfile argument as the name of the tarfile. If f is specified, /etc/default/tar is not searched. If f is omitted, tar will use the device indicated by the TAPE environment variable, if set; otherwise, it will use the default values defined in /etc/default/tar. If the name of the tarfile is ‘-‘, tar writes to the standard output or reads from the standard input, whichever is appropriate. tar can be used as the head or tail of a pipeline.
x: Extract or restore. The named file s are extracted from the tarfile and written to the directory specified in the tarfile, relative to the current directory. Use the relative path names of files and directories to be extracted. If a named file matches a directory whose contents has been writ ten to the tarfile, this directory is recursively extracted. The owner, modification time, and mode are restored (if possible); otherwise, to restore owner, you must be the super-user. Character special and block-special devices (created by mknod(1M)) can only be extracted by the super user. If no file argument is given, the entire content of the tarfile is extracted. If the tar- file contains several files with the same name, each file is written to the appropriate directory, overwriting the previous one.
For a look at all the functions and features of the tar command, vist this webpage
z: tar will use the compress program when reading or writing the archive. This allows you to directly act on archives while saving space.
Finally, we specify the file that we are unzipping, which in our case is the ProcessMaker tar ball that we just downloaded.
When the tar ball is decompressed, you can go ahead and delete the tar ball. You don’t have to, I just like keeping things neat and tidy.
Next, type the following commands:
cd /home/pmuser/public_html/processmaker/workflow/engine
chmod 777 config content/languages plugins xmlform js/labels
What we are doing here is changing directory to the engine of ProcessMaker, which is the heart of the application. Then, we change the permissions for specific directories to allow them to be readable & writeable so that ProcessMaker can install itself and run subsequently.
If your CPanel server uses SuPHP then do the following commands:
chmod 755 ../public_html/sysGeneric.php
chmod 755 ../public_html
chmod 755 ../../workflow
chmod 755 ../../../processmaker
The above commands are needed because when using SuPHP, the system is very strict when it comes to permissions. If the permissions are too flimsy and unsecure it will give an Internal Server Error Code 500. (Believe me, I have grown enough white hairs figuring this out the hard way)
Next, we need to assign the files to the apache user. If the User Account itself is setup to run apache, then you can type this command:
chown -R pmuser:pmuser /home/pmuser/public_html/processmaker
This command is needed so that the server can run the application, since we installed the application with root user, it is defaulted to the root user.
If you have a different user running apache, for example, nobody, then I would suggest instead doing the following:
chown -R pmuser:nobody /home/pmuser/public_html/processmaker
After we have assigned the Apache user to the files, we then need to setup the specific Apache configurations for ProcessMaker.
Create a file named .htaccess and place it in /home/pmuser/public_html/processmaker/workflow/public_html and place the following code inside it:
AddDefaultCharset UTF-8
Options FollowSymlinks
RewriteEngine onRewriteRule ^.*/(.*)$ 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
If running ProcessMaker on the main domain
You will need to modify your RootDirectory. You can find detailed instructions here
If running ProcessMaker on a sub domain
Log into the pmuser CPanel interface. Locate the search box on the left side of the page and type in the search box ‘Subdomains’.
Then, type in the sub domain you will be using and make sure that the Document Root is public_html/processmaker/workflow/public_html. This can change depending on how you are structuring your website and users.
After you have finished setting up your domains and Document Roots, go back to the main page of your CPanel account. In the search box type: MySQL Databases.
Now, create the ProcessMaker 3 databases. It isn’t really important what you call them, however, it is important that you be able to identify them. I would suggest just to make sure that at least the end of the databases are each wf, rb and rp, corresponding respectively to the Workflow, RBac and Reporting database. It is not within the scope of this tutorial to explain the differences between the three databases. So for the purpose of this tutorial we will call them database_wf, database_rb and database_rp.
Next, we create the database user. Again, you can call it what you like of course, but for the purposes of this tutorial we will call it database_user. Assign database_user to each of the 3 databases, and assign all the rights for each one. Don’t worry, only the application will have access to this user, and will not be visible to anyone accessing the system, unless you decide to give it out.
Now we will visit the actual website in a browser. If everything went as planned, you should get the ProcessMaker Installation Screen.
The database configuration section will be highlighted red. Don’t worry. Funny enough, this is actually a good sign 🙂
You can leave the host as localhost unless you require otherwise. Type in the username you created for the databases e.g. database_user. Then type in the password that you assigned to the user.
Then select the advanced options from the dropdown above the database section. If you followed the naming convention I used, then type in the following: Workflow database – database_wf Rbac database – database_rb Reporting database – database_rp
If you did not follow my naming convention, then you understand now why I insisted on at least leaving the last 2 letters according to the convention.
At the top press on the button labeled ‘test’. Now everything should light up green, including the previously red database section.
Now press ‘Install’ on the top.
If your server configuration met the requirements, then you should see a quick ProcessMaker script run and say completed. Then click on the button on the top to go to the application.
By default ProcessMaker makes only 1 user, called admin, and the password is also admin. I would advise changing the password for it immediately.
If you have any problems with the above tutorial, or have some advice/tips to share, please leave a comment 🙂

Leave a Comment