Deployment Best Practices

Implementation Best Practices are guidelines for setting up your system effectively. By following these recommendations, you can streamline your deployment process, enhance system performance, and ensure a smoother user experience. These practices provide valuable insights into optimizing your Joget platform, ultimately leading to improved productivity and satisfaction for users.

Installation as a service

You may want to install the web application server, such as Apache Tomcat, as a service for production deployments. Please refer to the documentation on the relevant operating system to learn how to do so. A guide to installing Tomcat as a Windows service is available at Installing Joget as a Windows Service.

Java virtual machine configuration

An important configuration would be the JVM memory allocation. If it is too low, the system will run out of memory. However, if it is too high, garbage collection might have quite a large overhead. Getting an optimum setting might sometimes require a bit of trial and error, depending on the usage environment.

You may want to start with a 1GB max heap setting and increase it if needed. The steps below will guide you on how to set it:

1.  Stop Joget.
2.  Access your Joget installation directory.
3. Open joget-start.bat
4. On line 13 of the file, modify this text:
   

   set JAVA_OPTS=-XX:MaxPermSize=128m -Xmx512M -Dwflow.home=./wflow/ -javaagent:./wflow/aspectjweaver-1.8.5.jar

   To:
   

   set JAVA_OPTS=-XX:MaxPermSize=256m -Xmx1024M -Dwflow.home=./wflow/ -XX:+UseConcMarkSweepGC -javaagent:./wflow/aspectjweaver-1.8.5.jar

5. Save the file and start Joget.

The following is a list of common errors that can arise when modifying the JVM memory along with their solution:

For more information, see the Java Documentation guide.

Apache Tomcat configuration

Try setting the maxThreads Connector thread pool settings for Apache Tomcat based on the estimated request load. For example, to set the maximum number of threads to 1000, follow the steps below:

1. Access your Tomcat installation folder.
2. Edit the  tomcat_directory/conf/server.xml file.
3. Locate the following line:
   

   <Connector URIEncoding="UTF-8" port="8080" protocol="HTTP/1.1" 
                  connectionTimeout="20000" 
                  redirectPort="8443" />

4. Add maxThreads="1000

   <Connector URIEncoding="UTF-8" port="8080" protocol="HTTP/1.1" maxThreads="1000"
                  connectionTimeout="20000" 
                  redirectPort="8443" />

5. Restart Tomcat for the change to take effect.

Linux configuration

Linux / Unix systems have a limit on the number of files that a process can concurrently open. When the limit is reached, there will be an exception Too many open files. The default for most distributions is 1024, which is insufficient for high-traffic deployments. Increasing the ulimit is a workaround in Linux, but this is only valid for the session. 

Command to increase the limit:

ulimit -n 4096

Database indexing

Form data tables generated and managed by Joget are prefixed with app_fd. By default, primary and foreign keys are automatically generated for these tables where necessary. 

However, in more complex apps, there may be more complex database queries that utilize these tables. Therefore, it is recommended to manually add indexes to table columns when needed. Indexes help speed up database queries and searches, which can significantly improve your application's performance.

MySQL configuration

The following are tips and best practices when handling the MySQL configuration for Joget:

• Set an appropriate InnoDB Buffer Pool: This is important for large-scale performance when using InnoDB in MySQL. See more details in the official MySQL Buffer Pools documentation.
• Use the query cache: using this cache improves performance in environments with large data and queries. This can help speed up query performance tremendously. See more details in the official MySQL Query Cache Documentation.
• Increase the maximum connections allowed: You may need to do this if there are too many concurrent requests. See more details in the official MySQL Connections Documentation.
• Enable the slow query log: It is possible to identify slow queries in MySQL by enabling the slow query log. This helps to identify areas for possible indexing and optimization. See more details in the official MySQL Query log Documentation.

Microsoft SQL server configuration

In MSSQL, adaptive buffering is designed to retrieve large-value data without the overhead of server cursors. You can configure the JDBC URL to use SelectMethod=direct in the database property file .\wflow\app_datasource-mssql.properties (Rename the mssql according to your environment). For example, if the current string is:

workflowUrl=jdbc\:sqlserver\://localhost\:1433;SelectMethod\=cursor;DatabaseName\=jwdb

Change it to:

workflowUrl=jdbc\:sqlserver\://docker\:1433;SelectMethod\=direct;DatabaseName\=jwdb

Remember to perform full testing on the SelectMethod option in your development or staging servers before implementing it in the production server.

Clustering and Load Balancing

For large-scale and high-availability deployments, consider implementing clustering and load balancing using the Large Enterprise Edition. Here's an overview of the necessary configurations:

1. Web Application Server Configuration:

   • Primary configurations are made at the web application server level, specifically within Tomcat. Detailed guidance for setting up a Tomcat cluster is available in the Tomcat Cluster HOW-TO.
     
     

2. Load Balancer Setup:

   • A load balancer, which can be either hardware-based or software-based, is essential. The Apache web server can serve as a software load balancer using the mod_proxy_balancer module. This setup allows traffic to be distributed across multiple Tomcat nodes. You can configure the system for either load balancing or failover. For session persistence, sticky sessions are recommended.
     
     

3. Shared Resources:

   • Ensure that the database and wflow files (which include configuration and uploaded files) are accessible from a centralized server. This setup supports a unified operation across different nodes.

Logging and troubleshooting

When running Apache Tomcat, logs are stored in the tomcat_directory/logs Directory. In particular, the files joget.log, catalina.out, and localhost.yyyy-MM-dd.log capture information and errors that are generated.

Should you encounter any issues or errors, it is best that the following information is provided when reporting the issue to the Support team or the community forums:

• Steps to reproduce the issue
• Error messages (including any possible JavaScript errors) in the browser
• Copy of the log files mentioned above
• Screenshot(s) showing the problem
• Sample app that produces the issue

The more information provided, the faster an issue can be identified and resolved.

Backup and restore

It is essential to perform regular backups so you can restore it to the previous backup of your installation if needed.

• To Backup an installation
  • Backup all configuration files and uploaded data files stored in joget_directory/wflow.
  • Backup the database. For example, use tools like mysqldump for MySQL to back up your database.
• To restore data to an installation
  
  • Restore all configuration files and uploaded data files stored in joget_directory/wflow.
  • Restore the database