3.0 - 3.6 - Changing the ProcessMaker Configuration

Overview

ProcessMaker sets its configuration settings at installation and does not provide a easy way to alter those settings from the graphical interface. Nonetheless, the IP address, port number, installation directory and MySQL databases can be altered after installation by editing the configuration files on the system. Use a bare text editor, such as Notepad or Notepad++ in Windows, vim or gedit in Linux/UNIX, to edit the configuration files and always make a backup of the files before editing them.

Changing the installation directory

If moving the ProcessMaker code to a new location on the server, configuration files will need to be changed for Apache and in the ProcessMaker code.

First, move the ProcessMaker code to a new location on the server. For instance, if moving the code from/opt/processmaker to /usr/bin/processmaker in Linux/UNIX:

mv /opt/processmaker /usr/bin/processmaker

Then, open the file <install-directory>/workflow/engine/config/paths_installed.php with a bare text editor. For example:

vim /usr/bin/processmaker/workflow/engine/config/paths_installed.php

Under the ***System Directories & Paths*** section, change the paths to the new location. For example, change from:

define( 'PATH_HOME', '/opt/processmaker/trunk/workflow/' ); define( 'PATH_GULLIVER_HOME', '/opt/processmaker/trunk/gulliver' . PATH_SEP );

To:

define( 'PATH_HOME', '/usr/bin/processmaker/trunk/workflow/' ); define( 'PATH_GULLIVER_HOME', '/usr/bin/processmaker/trunk/gulliver' . PATH_SEP );

After changing the path, then delete the binary file <install-directory>/shared/srvConf.singleton which contains data pointing to the old path. For example:

rm /usr/bin/processmaker/shared/srvConf.singleton

The srvConf.singleton file will be automatically recreated at the next login to ProcessMaker.

Then delete ProcessMaker's compiled cache, which contains data also pointing to the old path. For example:

rm -rf /usr/bin/processmaker/compiled/*

The contents of the compiled directory will automatically be recreated the next time that DynaForms are displayed in ProcessMaker.

Editing the ProcessMaker configuration file for Apache

Finally, change the location of the ProcessMaker code in the Apache configuration file. Open the file pmos.conf (httpd-vhosts.conf or httpd-app.conf if using the Bitnami Installer), whose location depends upon your system:

• Red Hat/CentOS/Fedora:
      /etc/httpd/conf.d/pmos.conf
• Debian/Ubuntu:
      /etc/apache2/sites-available/pmos.conf
• Windows:
  • Bitnami Installer in version 3.0.1.8 and later:
        C:\Bitnami\processmaker-3.X.X\apps\processmaker\conf\httpd-vhosts.conf
    C:\Bitnami\processmaker-3.X.X\apps\processmaker\conf\httpd-app.conf
  • Windows Installer in version 3.0.1.7 and earlier in Windows XP/2003 Server:
        C:\Program Files\ProcessMaker-3._X_X\apache2\conf\pmos.conf
  • Windows Installer in version 3.0.1.7 and earlier in Windows Vista/7/8/10/Server 2008/2012:
        C:\Users\USERNAME\AppData\Roaming\ProcessMaker-3._X_X\apache2\conf\pmos.conf
        Note: The AppData directory is a hidden directory, but the File Explorer can be configured to show hidden files.

In the pmos.conf file, change the path to the ProcessMaker code. For example, change the lines from:

To:

Then, restart Apache for the changes to take effect.

Editing the Apache configuration file

If the location of the pmos.conf file has been changed on your system, then it is necessary to modify the Include directive in the Apache configuration file to point to the new location. Edit the httpd.conf file and change the following line:

Include "/pmos.conf"

Windows:

Red Hat/Cent OS/Fedora:

Debian/Ubuntu:

Restarting Apache

After saving the changes to the configuration files, then restart the Apache web server for the new ProcessMaker configuration to take effect.

Red Hat/CentOS/Fedora:

Debian:

Ubuntu:

SUSE/openSUSE:

FreeBSD:

Windows:

Once Apache has been restarted, then ProcessMaker can be used in the new location on the server.

Changing the IP Address or Port Number

To change the IP address or port number for an existing ProcessMaker installation, use a plain text editor to modify the pmos.conf, and db.php files on your system.

1. If Apache isn't already configured to use a new IP address for the server or to listen on a new port number, then edit the Apache configuration file. Its location depends upon your system:

• Red Hat/CentOS/Fedora:
      /etc/httpd/conf/httpd.conf
• Debian/Ubuntu:
      /etc/apache2/apache.conf
    /etc/apache2/ports.conf
• FreeBSD:
      /usr/local/etc/apache/httpd.conf
• Windows:
  • If Bitnami Installer in version 3.0.1.8 and later:
        C:\Bitnami\ProcessMaker-3.X.X\apps\processmaker\conf\httpd-app.conf
    C:\Bitnami\ProcessMaker-3.X.X\apps\processmaker\conf\httpd-vhosts.conf
  • If Windows Installer in version 3.0.1.7 and earlier in Windows XP/2003 Server:
        C:\Program Files\ProcessMaker-3_X_X\apache2\conf\httpd.conf
  • If Windows Installer in version 3.0.1.7 and earlier in Windows Vista/7/8/10/Server 2008/2012:
        C:\Users\USERNAME\AppData\Roaming\ProcessMaker-3_X_X\apache2\conf\httpd.conf
        Note: The AppData directory is a hidden directory, but the File Explorer can be configured to show hidden files.

Set the IP address for the ServerName directive. For example, if changing from the IP address 192.168.0.100 to the address 10.1.2.3, then change the line from:

To:

If your DNS or hosts file has defined a domain name for ProcessMaker, it can be used instead of an IP number. For example:

If changing ProcessMaker to a different port number, then change Listen in the Apache configuration file. For instance, if changing from port 85 to port 8080, then change from:

To:

The IP address doesn't have to be specified if you want Apache to listen on the same port for all incoming IP addresses:

2. Then, edit the pmos.conf file, which is the Apache configuration file for ProcessMaker. Replace the old IP address or port number with the new IP address or port number. The port number is defined after the IP address and is separated by ":" (a colon). If no port number is included in the address, ProcessMaker will use port 80 by default, which is the port generally used by the web.

For example, if changing from the address 192.168.0.100:85 (where 85 is the port number) to the address 10.1.2.3:8080 (where the 8080 is the port number), then change the lines from:

To:

3. Then, edit the db.php file, which indicates how to access ProcessMaker's databases in MySQL. It is located at:

• Linux/UNIX:
      /opt/processmaker/shared/sites/WORKSPACE/db.php
• Windows:
  • Bitnami Installer in version 3.0.1.8 and later:
        C:\Bitnami\processmaker-3.X.X\apps\processmaker\htdocs\shared\sites\WORKSPACE\db.php
  • Windows Installer in version 3.0.1.7 and earlier in Windows XP/2003 Server:
        C:\Program Files\Processmaker-3_X_X\processmaker\shared\WORKSPACE\db.php
  • Windows Installer in version 3.0.1.7 and earlier in Windows Vista/7/8/10/Server 2008/2012:
        C:\User\USERNAME\AppData\Roaming\Processmaker-3_X_X\processmaker\shared\WORKSPACE\db.php
        Note: The AppData directory is a hidden directory, but the File Explorer can be configured to show hidden files.

Replace the old IP address with the new one, but do not change the port number, since it is the port for the MySQL database, which in most cases will be the default port 3306. For example, if changing from IP address 192.168.0.100 to 10.1.2.3, then change the file from:

To:

The db.php file has to be edited for each ProcessMaker workspace, including the default "workflow" workspace.

4. Finally, restart the Apache web server for the new IP address or port number to take effect.

Editing the PHP configuration

The configuration of PHP controls a number of aspects of ProcessMaker's behavior, such as the maximum amount of memory per session and the maximum size of uploaded files. To change the configuration of PHP, edit the php.ini file, whose location depends on your system:

• Red Hat/CentOS/Fedora:
      /etc/php.ini
• Debian/Ubuntu/SUSE/openSUSE:
      /etc/php5/apache2/php.ini
• In Debian/Ubuntu systems with multiple web servers:
      /etc/php5/cgi/php.ini
• FreeBSD:
      /usr/local/etc/php.ini
• Windows:
  • Bitnami Installer in version 3.0.1.8 and later:
        C:\Bitnami\ProcessMaker-3.X.X\php\php.ini
  • Automatic Installer in version 3.0.1.7 and earlier in Windows XP/Server 2003:
        C:\Program Files\ProcessMaker-3_X_X\php\php.ini
  • Automatic Installer in version 3.0.1.7 and earlier in Windows Vista/7/8/10/Server 2008/2012:
        C:\Users\USERNAME\AppData\Roaming\ProcessMaker-3_X_X\php\php.ini
        Note: The AppData directory is a hidden directory, but the File Explorer can be configured to show hidden files.

After saving your changes, according to your web server installed, restart Apache or NGINX for the new PHP configuration to go into effect. If the PHP-FPM is installed, restart this service too.

Increase The Memory Limit

Usually there are scripts in ProcessMaker that need to increase the memory limit. In the php.ini, look for the memory_limit and set it according to your script needs.

; Maximum amount of memory a script may consume (128MB) ; http://php.net/memory-limit memory_limit = 256M

After saving your changes, according to your web server installed, restart Apache or NGINX for the new PHP configuration to go into effect. If the PHP-FPM is installed in your server, restart this service too.

Increase the maximum size of uploaded files

Since uploaded files are stored as files in the hard drive, their size can be as large as allowed by the operating system and harddrive format. Nonetheless, PHP by default is configured to allow the upload of files no larger than 2MB. To increase the maximum size of uploaded files, change the upload_max_filesize and post_max_size settings in the php.ini file.

Look for the "File Uploads" section and set file_uploads = On and increase the size of upload_max_filesize:

;;;;;;;;;;;;;;;; ; File Uploads ; ;;;;;;;;;;;;;;;; ; Whether to allow HTTP file uploads. file_uploads = On ; Temporary directory for HTTP uploaded files (will use system default if not specified). ;upload_tmp_dir = ; Maximum allowed size for uploaded files. upload_max_filesize = 2M

Uploaded files are passed to the ProcessMaker server as POST data, whose maximum size by default is 8MB. If larger files need to be uploaded, also increase the size of post_max_size:

; Maximum size of POST data that PHP will accept. post_max_size = 8M

Increase the maximum execution time

By default, the maximum time that a command can be executed in PHP is set to 30 seconds. If you see an error message such as:

Fatal Error: Maximum execution time of 30 seconds exceeded in /.php on line XXX.

Then increase the value of the max_execution_time in php.ini:

;;;;;;;;;;;;;;;;;;; ; Resource Limits ; ;;;;;;;;;;;;;;;;;;; max_execution_time = 30 ; Maximum execution time of each script, in seconds

Increase the maximum number of DynaForm fields

By default, a DynaForm can have a maximum of 1000 fields, which can be a problem for long grids that may have hundreds of rows. For example, a grid with 10 fields per row will be limited to 100 rows. To increase the total number of fields allowed in a DynaForm, change the max_input_vars, memory_limit, and post_max_size settings in the php.ini file: memory_limit = 256M post_max_size = 16M max_input_vars = 8000

Then restart Apache.

Increase the maximum memory per session

The memory for each session of ProcessMaker is generally set to 80MB, but this may not be enough memory to generate large Output Documents or do other memory-hogging actions. To change the memory_limit in version 2.0.29 and later, set it in the env.ini configuration file.

If more memory per session is needed before version 2.0.29, increase the value of the memory_limit setting in the php.ini file:

;;;;;;;;;;;;;;;;;;; ; Resource Limits ; ;;;;;;;;;;;;;;;;;;; max_execution_time = 30 ; Maximum execution time of each script, in seconds max_input_time = 60 ; Maximum amount of time each script may spend parsing request data ;max_input_nesting_level = 64 ; Maximum input variable nesting level memory_limit = 80M ; Maximum amount of memory a script may consume (16MB)

In addition, edit the sysGeneric.php file, which is generally located at:

• Linux/UNIX:
      /opt/processmaker/workflow/public_html/sysGeneric.php
• Windows:
  • Bitnami Installer in version 3.0.1.8 and later:
        C:\Bitnami\processmaker-3.X.X\apps\processmaker\htdocs\workflow\public_html\sysGeneric.php
  • Windows Installer in version 3.0.1.7 and earlier in Windows XP/2003 Server:
        C:\Program Files\ProcessMaker-3._X_X\processmaker\workflow\public_html\sysGeneric.php
  • Windows Installer in version 3.0.1.7 and earlier in Windows Vista/7/8/10/Server 2008/2012:
        C:\Users\USERNAME\AppData\Roaming\ProcessMaker-3._X_X\processmaker\workflow\public_html\sysGeneric.php
        Note: The AppData directory is a hidden directory, but the File Explorer can be configured to show hidden files.

In the sysGeneric.php file, edit line 7 to increase the value of '80M':

ini_set('memory_limit', '80M');

Moving the ProcessMaker databases

For large scale usage of ProcessMaker, it is recommended to store the ProcessMaker databases on a separate server, since it will reduce some of the load on the web server running ProcessMaker. Moving the ProcessMaker databases to a new location, is a two step process. First, transfer the databases to a different installation of MySQL, then configure ProcessMaker to use those databases in a new location.

Changing the MySQL configuration

The location of my.cnf on Linux-based systems or my.ini on Windows systems depends on the installation and operating system:

Red Hat/CentOS:

Debian/Ubuntu:

Windows:

Bitnami in Linux:

Bitnami in Windows:

After editing the my.cnf file on Linux or my.ini on Windows, restart MySQL or reboot the server for the new configuration to take effect. In Linux/UNIX, login as root or use (sudo before command to restart MySQL. The command depends on the system:

Red Hat/CentOS 6:

Red Hat/CentOS 7:

Debian/Ubuntu:

Bitnami in Linux:

Bitnami in Windows:

Transferring the MySQL databases

The best way to move the ProcessMaker databases from one installation of ProcessMaker to another is to use the processmaker workspace-backup and processmaker workspace-restore commands.

However, if needing to move the MySQL databases to a new location without changing the ProcessMaker installation (or moving an older version of ProcessMaker, which doesn't support workspace backup and restore), then use MySQL's utilities. Use the mysqldump command to make a copy of the ProcessMaker database, and then use the mysql command to restore the database in a different installation of MySQL.

Remember that each ProcessMaker workspace uses 1 MySQL database. This database can use any name that was specified during the installation, but it is generally named wf_<workspace>. For the default "workflow" workspace, it will be named wf_workflow.

To check the names of these databases on your system, open a command line terminal on the server where the ProcessMaker databases are currently located and log in to MySQL as the "root" user:

mysql -u root -p Enter the root password

Note: If using MS Windows, first add the directory where mysql.exe is installed to your PATH environment variable:

Once inside MySQL, issue the show databases command to see the list of databases. For instance, these would be the databases on a system with "workflow" and "sales" workspaces:

mysql> show databases; +--------------------+ | Database | +--------------------+ | information_schema | | mysql | | phpmyadmin | | rb_sales | | rb_workflow | | rp_sales | | rp_workflow | | wf_sales | | wf_workflow | +--------------------+ mysql> exit;

After verifying the database names, log out of MySQL and use the mysqldump command to make a backup of each database.

mysqldump --user=XXXXXXXX --password=XXXXXXX DB_NAME > DBNAME.SQL

For example, to make a backup of the default "workflow" and "sales" workspaces using the "root" user whose password is "P@sSw0rD":

mysqldump --user=root --password=P@sSw0rD wf_workflow > wf_workflow.sql mysqldump --user=root --password=P@sSw0rD wf_sales > wf_sales.sql

Then, go to the other server where the databases will be installed. In the command line terminal, use the mysql command to import each database:

mysql --verbose --user=XXXXXXXX --password=XXXXXXX DB_NAME < DBNAME.SQL

For example, if importing the "workflow" and "sales" workspaces with a "root" user whose password is "Dr0wSs@P":

mysql --verbose --user=root --password=Dr0wSs@P wf_workflow < wf_workflow.sql mysql --verbose --user=root --password=Dr0wSs@P wf_sales < wf_sales.sql

Then, log in to MySQL and configure a user to have full privileges to control the MySQL databases:

mysql -u root -p Enter the root password

Give the user that will be running ProcessMaker superuser privileges to create and modifiy MySQL tables:

mysql> grant all on *.* to 'USER'@'IP-ADDRESS' identified by 'PASSWORD' with grant option;

Replace USER with the name of your MySQL user and PASSWORD with the password for that user. If no additional MySQL users had been created, use 'root' as the user and the root's password. Also replace 'IP-ADDRESS' with the domain name or IP address of the web server where ProcessMaker is installed. For example, if ProcessMaker is installed at 192.168.1.101, then:

mysql> grant all on *.* to 'root'@'192.168.1.101' identified by 'Dr0wSs@P' with grant option;

Finally, exit MySQL:

mysql> exit;

Also make sure that no firewall is blocking the port used by MySQL, which by default is port 3306.

Configuring ProcessMaker for a Different Database Location

ProcessMaker 3 provides a way to change the database location and credentials inside the interface. See Changing the MySQL Location or its "root" user for more information.

Creating Users in Each Workspace

To create users in each workspace, edit <install-directory>/processmaker/shared/sites/workspace-name/db.php, which will have content similar to that shown below:

<?php // Processmaker configuration define ('DB_ADAPTER', 'mysql' ); define ('DB_HOST', 'localhost' ); define ('DB_NAME', 'wf_workflow' ); define ('DB_USER', 'wf_workflow' ); define ('DB_PASS', 'BTn14@m=jSYw*3!' ); define ('DB_RBAC_HOST', 'localhost' ); define ('DB_RBAC_NAME', 'wf_workflow' ); define ('DB_RBAC_USER', 'wf_workflow' ); define ('DB_RBAC_PASS', 'BTn14@m=jSYw*3!' ); define ('DB_REPORT_HOST', 'localhost' ); define ('DB_REPORT_NAME', 'wf_workflow' ); define ('DB_REPORT_USER', 'wf_workflow' ); define ('DB_REPORT_PASS', 'BTn14@m=jSYw*3!' );

Change 'localhost' to the IP or domain host where MySQL is installed.

Then, log in to MySQL:

mysql -u root -p Enter the root password

Now, create the root user and DB_USER with the neccessary permissions to access the new database from the ProcessMaker server. For example, if ProcessMaker is installed in the domain pm.example.com and the name of its database is "wf_workflow", its user is "wf_workflow" and the password of its user is "BTn14 @ m = jSYw * 3!"(as shown in the db.php file above), run the following commands:

mysql> GRANT USAGE ON *.* TO 'wf_workflow'@'pm.example.com' IDENTIFIED BY PASSWORD 'BTn14@m=jSYw*3!'; mysql> GRANT ALL PRIVILEGES ON `wf_workflow`.* TO 'wf_workflow'@'pm.example.com' WITH GRANT OPTION; mysql> GRANT USAGE ON *.* TO 'root'@'pm.example.com' IDENTIFIED BY PASSWORD 'p4sSw0rD'; mysql> GRANT ALL PRIVILEGES ON *.* TO 'root'@'pm.example.com' WITH GRANT OPTION;

Verify that the users are created and have the correct permissions:

mysql> SELECT User, Host from mysql.user; +------------------+-----------+ | User | Host | +------------------+-----------+ | root | localhost | | root | pm.example.com | | wf_workflow | pm.example.com | +------------------+-----------+ mysql> SHOW GRANTS FOR 'wf_workflow'@'pm.example.com'; +------------------------------------------------------------------------------------------------------------+ | Grants for wf_workflow@pm.example.com | +------------------------------------------------------------------------------------------------------------+ | GRANT USAGE ON *.* TO 'wf_workflow'@'pm.example.com' IDENTIFIED BY PASSWORD '*C0538E2649071005ABF19153F65CA40099DFF41D' | | GRANT ALL PRIVILEGES ON `wf_workflow`.* TO 'wf_workflow'@'pm.example.com' WITH GRANT OPTION | +-------------------------------------------------------------------------------------------------------------+ mysql> SHOW GRANTS FOR 'root'@'pm.example.com'; +-------------------------------------------------------------------------------------------------------------+ | Grants for root@pm.example.com | +-------------------------------------------------------------------------------------------------------------+ | GRANT USAGE ON *.* TO 'root'@'pm.example.com' IDENTIFIED BY PASSWORD '*C0538E2649071005ABF19153F65CA40099DFF41D' | | GRANT ALL PRIVILEGES ON *.* TO 'root'@'pm.example.com' WITH GRANT OPTION | +--------------------------------------------------------------------------------------------------------------+ mysql> EXIT;

Note: If using ProcessMaker 3.2 or later, make sure to note the name of MySQL user that is specified in the db.php file, because it is different from the name in the database. define ('DB_NAME', 'wf_workflow' ); define ('DB_USER', 'wf_593fea8bd4c8b' ); define ('DB_PASS', 'QSKnsbJe81V_m-3' );

Moving ProcessMaker to another server

ProcessMaker can be moved to another server along with all the existing processes, users and cases, either by using the new Backup and Restore utility or by manually transferring the database and the files in the shared directory.

It is extremely important to only transfer data between the same versions of ProcessMaker. Do NOT try to use data from one version of ProcessMaker in another version of ProcessMaker.

Using the Workspace Backup and Restore utility

Gulliver's workspace-backup command can be used to make a backup of the ProcessMaker workspaces in the old server:

./gulliver workspace-backup workspace

Then, go to the new server and follow the standard procedure to install the same version of ProcessMaker as is being used on the old server. After installing ProcessMaker in the new server, then copy the backups/workspace.tar file from the old server to the new server. For example, if using scp to transfer the "workflow" workspace from the old server at 192.168.1.100 to the new server at 1.2.3.4:

spc root@192.169.1.100:/opt/backups/workflow.tar root@1.2.3.4:/opt/backups/workflow.tar

Then, use Gulliver's workspace-restore command to import the workspace into the new server:

./gulliver workspace-restore backup.tar workspace

If importing a workspace which already exists on the new server, such as the default "workflow" workspace, then use the overwrite option when doing the restore:

./gulliver workspace-restore backup.tar workspace overwrite

Now all the data from the old ProcessMaker server should be available on the new server.

Manually Transferring to a New Server

Another way to transfer ProcessMaker to another server is to manually copy the ProcessMaker databases and the contents of the shared directory to the new server.

First, follow the standard procedure to install the same version of ProcessMaker on the new server as is being used on the old server.

Then, follow the instructions above to copy the ProcessMaker databases from the old server to the new server.

Finally, copy the contents of the shared directory from the old server to the new server. It can generally be found at:

Linux/UNIX:

/opt/processmaker/shared

Windows:

<install-directory>\shared

Now all the data from the old ProcessMaker server should be available on the new server.