Overview

This installation guide provides the necessary steps to set up the Mambo platform. The guide covers the installation of:

• MongoDB: A NoSQL database that stores the platform data
• Java: The runtime environment required for the application
• Tomcat: The web application server that hosts the platform
• Mambo Platform: The core application deployment and configuration

This guide focuses on installation for Linux environments but can be adapted for Windows and Mac environments where appropriate. All environments should be 64-bit for optimum performance.

Prerequisites

Before beginning the installation process, ensure you have:

• Administrator/root access to your servers
• Internet connectivity for downloading packages
• Basic knowledge of command-line operations
• Sufficient disk space and memory for the platform

Installing MongoDB

The Mambo platform runs on the MongoDB database. MongoDB must be configured as a replica set in all environments, including production, testing, and development.

For optimal performance and high availability in a production environment, you should configure MongoDB as a replica set with three servers.

In non-production environments, you can use a single-node replica set. While this setup does not provide redundancy or failover capabilities, it still enables advanced MongoDB features — such as multi-document transactions — that Mambo relies on.

Installation notes

• MongoDB Version: The recommended version is 8.0. Mambo platform supports MongoDB versions ≥6.0.
• Server Addresses: Record the IP address of each server in the replica set.
• Port: Use the default MongoDB installation port of 27017.

important

Edit the mongod.conf file and set the bind_ip option to both 127.0.0.1 AND the local IP address of the server (VLAN address). If you simply comment out the bind_ip option, the MongoDB server will allow connections from all internet hosts.

If setting up in a cloud environment such as Amazon Web Services, you can use MongoDB's Cloud service to reduce installation time. This service also works for private clouds:

MongoDB Cloud

For installation guides across different operating systems, refer to the official MongoDB documentation:

MongoDB Installation Guides

Performance optimisation

To optimise MongoDB's performance, review the production optimisation notes:

MongoDB Production Notes

For AWS deployments, consider using Provisioned IOPS to maximise performance:

MongoDB Performance with AWS Provisioned IOPS This article provides additional insight for MongoDB deployment on AWS:

Best Practices for MongoDB on EC2

Setting up replica sets

For guidance on configuring replica sets:

MongoDB Replica Set Deployment Guide

MongoDB provides specific guides for various cloud platforms:

MongoDB Ecosystem Platforms

Remember to consider the size of the oplog:

Understanding the Replica Set Oplog

Changing the Oplog Size

Installing Java

The Mambo platform requires the Java Runtime Environment or Java Development Kit.

Installation notes

• Java Version: The platform supports the latest version of Java 17 LTS.
• Architecture: For optimal performance, install the 64-bit JRE/JDK.
• Distributions: The officially supported OpenJDK distribution is Eclipse Temurin by Adoptium. The platform is also regularly tested with Amazon Corretto OpenJDK.

The latest Eclipse Temurin OpenJDK 17 distribution can be downloaded from the Adoptium project.

Installing Tomcat

The Mambo platform runs on the Tomcat Web Application Server. The platform is distributed as a WAR file which is deployed to Tomcat.

Installation notes

• Tomcat Version: The platform supports Tomcat version 10.x. Versions ≤9.x and ≥11.x are not compatible.
• Architecture: Use the 64-bit version of Tomcat for optimum performance.
• APR (Apache Portable Runtime): Configure Tomcat with the APR connector for best performance and future compatibility.

The latest Tomcat 10.1 can be downloaded from the Apache website. For installation instructions, refer to the official Tomcat documentation.

Tomcat can use the Apache Portable Runtime to provide an OpenSSL-based TLS implementation for HTTP connectors. See the official documentation for more information.

Memory configuration

To ensure Tomcat has adequate memory and to avoid PermGen memory errors, allocate sufficient memory by modifying the Java options:

1. Locate the Tomcat installation directory:

Bash

sudo find / -name "catalina.sh"

2. Create or edit the setenv.sh file in the Tomcat installation folder and add:

Bash

export JAVA_OPTS="-Xms3G -Xmx3G"

This allocates 3GB for both initial and maximum heap sizes. If you continue to experience OutOfMemoryError exceptions, consider increasing the memory allocation further.

Running on Port 80 with Nginx

The recommended way to serve the Mambo application is through an Nginx proxy on port 80 or 443 with SSL.

While Apache 2.0 is widely used, we only support Nginx as the web server in front of Tomcat for optimal performance. Nginx's event-driven architecture handles traffic efficiently with significantly less memory consumption compared to Apache 2.0. In high-traffic production environments, Apache 2.0 has been known to struggle or crash when managing large volumes of events.

Although Tomcat can be configured to run on port 80, this setup is not recommended, particularly when SSL is enabled. Nginx provides better scalability and resource utilisation when used with Tomcat.

For Nginx installation, refer to the official guide.

For configuring the integration between Nginx and Tomcat, the official Nginx documentation provides guidance.

Nginx proxy configuration

Nginx

# Proxy the requests through to Tomcat
location / {
  proxy_pass http://localhost:8080;
  proxy_redirect default;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Forwarded-Server $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto https;
}

Tomcat proxy configuration

Add this configuration to the server.xml file:

XML

<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
  ...
  <Valve className="org.apache.catalina.valves.RemoteIpValve"
      remoteIpHeader="x-forwarded-for"
      remoteIpProxiesHeader="x-forwarded-by"
      protocolHeader="x-forwarded-proto"
      requestAttributesEnabled="true"
      protocolHeaderHttpsValue="https"/>
  ...
</Host>

Installing the Mambo platform

The Mambo platform is packaged as a WAR file which is unpacked into the relevant Tomcat deployment directory. After unpacking, you'll need to update the configuration properties and run the installation wizard.

Deploying the WAR file

To deploy the Mambo application as the root application on Tomcat (i.e., http://localhost:8080/), follow these steps:

1. Find the $CATALINA_HOME/webapps directory (where Tomcat is installed)
2. Remove any existing ROOT directory from the webapps directory
3. Copy the Mambo WAR file into the webapps directory and rename it to ROOT.war
4. Unzip/unpack the Mambo WAR file:
   • In Windows: Open the WAR file using an application such as Winzip or 7-zip
   • In Linux: Use the unzip command (unzip -d ROOT.war)
   • In Mac: Use the jar command (jar -xvf ROOT.war)
5. Verify that a ROOT directory is now present in the webapps folder

Configuring the platform

Once the Mambo WAR file has been unpacked into the ROOT directory, you need to configure the mambo.properties file, which contains configuration properties that must be updated before launching the application.

To edit the properties:

1. Navigate to: $CATALINA_HOME/webapps/ROOT/WEB-INF/classes
2. Open the mambo.properties file in a text editor
3. Update the properties as needed according to the descriptions in the file

important

This configuration step must not be skipped. The file contains settings that must be configured appropriately to run your system.

Setting up log directories

You must create the folder structure for Mambo logs and configure appropriate permissions. The default location is:

Bash

/var/log/mambo

If you wish to change the log location (for example, on Windows server), navigate to the /WEB-INF/classes directory and edit the logback.xml file. Update the reference to the default location.

Set permissions so Tomcat can write log files to the folder:

Bash

sudo chown tomcat:tomcat /var/log/mambo

Note that the user and group under which Tomcat runs may differ depending on your distribution.

Configuring clustered cache

To configure the clustered cache, update these properties in the mambo.properties file:

1. Uncomment the clustered cache.type line:
2. Comment out all other cache.type properties:
3. Uncomment the JGroups UDP lines:

Properties

cache.type=ClusterCacheManager
#cache.type=NoOpCacheManager
#cache.type=LocalCacheManager
system.property.jgroups.udp.mcast_addr=228.6.7.8
system.property.jgroups.udp.mcast_port=12345
system.property.jgroups.udp.ip_ttl=2

The IP address and port number above are default values for UDP multicast.

Enable UDP communication between servers so caches can discover each other. In Linux, enable UDP at the firewall level:

Bash

firewall-cmd --zone=public --add-port=46655/udp --permanent
firewall-cmd --reload

Installation wizard

After deploying and configuring the Mambo WAR file, navigate to your server's URL in a browser (e.g., http://localhost:8080). When the server runs for the first time, it should display the Mambo installation wizard, which allows you to set up the Master account for the server, including your company name and Primary Administrator details.

After completing the wizard, the Administration Panel will load.

TLS/SSL on database connections

The connection between your Mambo instance and the MongoDB database can be encrypted using TLS/SSL. This requires:

1. Configuring the MongoDB server to present a certificate to connecting clients
2. Configuring your Mambo application to enable TLS/SSL for MongoDB connections

Configuring the MongoDB server

For TLS/SSL configuration in MongoDB, refer to the MongoDB documentation.

Configuring your Mambo application

To configure Mambo to use TLS/SSL when connecting to MongoDB, edit the mambo.properties file and set the mongo.uri configuration property:

Properties

# Mambo 7.0.0 or greater
mongo.uri=mongodb://<username>:<password>@<db_hostname>:<port>/?tls=true

# Mambo 6.x.x
mongo.uri=mongodb://<username>:<password>@<db_hostname>:<port>/?ssl=true

After configuring mongo.uri, the following properties are no longer necessary and can be commented out:

• mongo.replicaA.host
• mongo.replicaB.host
• mongo.replicaC.host
• mongo.port
• mongo.username
• mongo.password
• mongo.mechanis

Ensure that the mongo.dbname property remains uncommented and set to the correct value.

For ReplicaSet deployments or if you use a separate authentication database, refer to the MongoDB documentation to configure the connection string correctly.

Adding self-signed certificates to the Java trust store

If the SSL certificate used by the MongoDB server is self-signed or issued by an authority not trusted in the Java trust store, add the certificate to the JVM trust store of the machines running Mambo:

Bash

keytool -import -file certificate.crt -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit

Troubleshooting

Common issues

• MongoDB connection failures: Check network connectivity, firewall rules, and authentication credentials.
• Java memory errors: Increase the allocated memory in the setenv.sh file.
• Permission denied errors: Ensure proper permissions for log directories and application files.

Health checks

After installation, verify that all components are functioning correctly:

1. Check MongoDB connection: The application logs should show successful database connectivity.
2. Verify Tomcat startup: Review Tomcat logs for any errors during startup.
3. Test application access: Access the application URL from a browser and check for proper loading.

Support and resources

The up-to-date list of supported software can be found in the official documentation.