Contents
- Overview
- Installing MongoDB
- Installing Java
- Installing Tomcat
- Installing the Mambo Platform
- Appendix: Supported Software
The installation guide provides the necessary steps required in order to setup the Mambo.IO platform. The guide will cover the installation of:
- MongoDB: references will be provided to the relevant guides on the MongoDB site
- Tomcat: references will be provided to the relevant guides on the Tomcat site
- Mambo.IO Platform: all the relevant setup and configuration steps will be explained in this guide
The guide focuses on the installation for Linux environments, but can easily be ported to both Windows and Mac environments. Links to the Windows / Mac environments may be provided where appropriate.
Note: all environments should be 64bit for optimum performance.
The Appendices contain additional information which may be helpful.
The Mambo.IO platform runs on the MongoDB database (http://mongodb.org). In order to achieve the best performance in a production environment, it is necessary to setup a MongoDB replica set with 3 servers.
Notes on the installation process:
- MongoDB Version: the recommended version of MongoDB is 8.0. Mambo.IO platform supports MongoDB versions ≥6.0.
- Server Addresses: make a note of the IP address of each of the servers in the replica set
- Port: use the default MongoDB installation port of 27017
- Note: the mongod.conf file should be edited and bind_ip option should be set to 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 the database will allow connections from all internet hosts.
If you are setting up a cloud environment on Amazon Web Services you can use MongoDB's Cloud service which will reduce the time to install enormously. Their service also works for private clouds. Here is a link to the product:
https://www.mongodb.com/cloud/
The installation guides for Linux based OS, Mac OS and Windows OS can be found here:
http://docs.mongodb.org/manual/installation/
In order to optimise MongoDB's performance, the production optimisation notes should be read. The production optimisation notes can be found here:
http://docs.mongodb.org/manual/administration/production-notes/
In case Amazon Web Services is being used for hosting, then the following blog post explains how to maximise performance by using Provisioned IOPS:
This article also provides useful information for settings up MongoDB on AWS:
https://scalegrid.io/blog/best-practices-for-deploying-mongodb-on-ec2/
Setting up the production environment requires a replica set to be configured (local testing environments do not require replica sets to be setup). The guide to configure the Replica Sets can be found here:
http://docs.mongodb.org/manual/tutorial/deploy-replica-set/
MongoDB provides a number of guides focused on specific cloud vendors and platforms. The guides for Amazon Web Services, Google Compute Engine, Rackspace, Joyent, etc can be found here:
http://docs.mongodb.org/ecosystem/platforms/
Remember to take into account the size of the oplog, see below:
https://docs.mongodb.com/v3.0/core/replica-set-oplog/
https://docs.mongodb.com/manual/tutorial/change-oplog-size/
The Mambo.IO platform is built using Java and requires the Java Runtime Environment or Java Development Kit to be installed in order for the platform to run.
Notes on the installation process:
- Java Version: the Mambo.IO platform supports the latest version of Java 17 LTS.
- 64 Bit: for optimal performance the 64-bit JRE/JDK must be installed.
- JRE/JDK disribution: the officially supported OpenJDK distribution is Eclipse Temurin by Adoptium. Additionally, the Mambo platform is also regularly tested against the Amazon Corretto OpenJDK distribution.
The latest Eclipse Temurin OpenJDK 17 distribution can be download from the Adoptium project here.
The installation guides for Linux, Windows and Mac can be found here.
The Mambo.IO platform runs on the Tomcat Web Application Server. The platform comes bundled as a WAR file which is deployed to Tomcat (see the next section).
Notes on the installation process:
- Tomcat Version: the Mambo.IO platform supports Tomcat version 10.x. Tomcat versions <=9.x and >=11.x are not compatible.
- 64 Bit: the 64 Bit version of Tomcat must be installed for optimum performance.
- APR (Apache Portable Runtime): please configure Tomcat using the APR connector in order to future proof your deployment for upgrades. APR will also provide the best performance out of all the Tomcat connectors.
The latest Tomcat 10.1 can be downloaded from Apache here. For installation instructions, refer to the official Tomcat documentation.
Tomcat can use the Apache Portable Runtime to provide an OpenSSL based TLS implementation for the HTTP connectors. For more information, refer to the official documentation.
To ensure Tomcat has adequate memory for proper operation and to avoid PermGen memory errors, allocate sufficient memory by modifying the Java options. First, locate the Tomcat installation directory by running the following command:
sudo find / -name "catalina.sh"
Next, create or edit the setenv.sh file in the Tomcat installation folder and add the following line:
export JAVA_OPTS="-Xms3G -Xmx3G"
This configuration allocates 3GB of memory for both the initial and maximum heap sizes. If you continue to experience OutOfMemoryError exceptions, consider further increasing the memory allocation to meet the needs of your platform.
4.1 Running on Port 80 with Nginx
The recommended way to serve the Mambo application over the network is through an Nginx proxy on port 80 or 443 with SSL.
While Apache 2.0 is widely recognized, for optimal performance, we only support Nginx as the web server in front of Tomcat. Nginx's event-driven architecture enables it to handle traffic efficiently, consuming significantly less memory compared to Apache 2.0. In high-traffic production environments, Apache 2.0 has been known to struggle and even crash when managing large volumes of events.
Although Tomcat can be configured to run on port 80, this setup is not recommended for optimal performance, particularly when SSL is enabled. Nginx provides better scalability and resource utilization when used in conjunction with Tomcat.
In order to install Nginx, please see the official guide.
To configure the integration between Nginx and Tomcat, the official Nginx documentation provides good guidance here.
Nginx Proxy Configuration
# 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
This configuration is added to the server.xml file:
...
<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>
5. Installing the Mambo Platform
The Mambo.IO platform comes packaged as a WAR file which can then be unpacked into the relevant Tomcat deployment directory. Once the WAR file is unpacked, the platform's configuration properties need to be updated with the relevant properties and finally the installation wizard will run.
In order to deploy the Mambo.IO application as the root application on Tomcat (i.e. http://localhost:8080/), the WAR file must be unpacked into the Tomcat webapps directory. Follow these steps in order to deploy the WAR file:
- Find the $CATALINA_HOME/webapps directory (where Tomcat is installed)
- Remove any existing ROOT directory from the webapps directory
- Copy the Mambo WAR file into the webapps directory and rename the WAR file to ROOT.war
- Unzip / unpack the Mambo WAR file
- In windows you can open the WAR file using an application such as Winzip or 7-zip
- In Linux you can unzip the WAR file using unzip command (unzip -d ROOT.war)
- In Mac you can unzip the WAR file using the jar command (jar -xvf ROOT.war)
- Ensure that a ROOT directory is now present in the webapps folder
Once the Mambo.IO WAR file has been unpacked into the ROOT directory, we must configure the mambo.properties file. The properties file contains a number of configuration properties which must be updated prior to launching the application.
In order to edit the properties navigate to the following directory:
$CATALINA_HOME/webapps/ROOT/WEB-INF/classes
In this directory you will find the "mambo.properties" file. Open this in your favourite text editor. Each property in the file is clearly explained, please refer to the descriptions in the file.
In addition to the mambo configuration, the folder structure where the Mambo logs will be saved must be created and appropriate permissions configured. The default location for the Mambo logs is:
/var/log/mambo
If you wish to change the location of the Mambo logs (for example if you are running on Windows server) then you must deploy the WAR file and then navigate to "/WEB-INF/classes" directory above and edit the logback.xml file. In the file you will find a reference to the default location which can be updated.
The permissions must be set so that Tomcat can write the log files into the folder. If you run Tomcat with it's own user and group, then the permissions command might look something like this:
sudo chown tomcat:tomcat /var/log/mambo
Pleaso note that depending on your distribution the user and group under which Tomcat is run migh differ from the example above.
Note: To configure the clustered cache, the following properties need to be updated in the mambo.properties file:
- Uncomment the clustered cache.type line:
- cache.type=ClusterCacheManager
- Comment out all other cache.type properties (i.e. NoOp and Local)
- #cache.type=NoOpCacheManager
- #cache.type=LocalCacheManager
- Uncomment the JGroups UDP lines:
- 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.
The next step is to enable UDP communication between the servers so that the caches can discover each other. In Linux you will need to enable UDP at the firewall level, this can be done with the following commands:
- firewall-cmd --zone=public --add-port=46655/udp --permanent
- firewall-cmd –reload
Note: the file contains settings which must be configured appropriately to run your system. This configuration step must not be skipped.
Once the Mambo.IO WAR file has been deployed and configured, we can navigate to our servers URL in the browser (e.g. http://localhost:8080). The first time the server is run, this should bring up the Mambo installation wizard. The Wizard allows you to setup the Master account for the server. This includes your company name as well as the details of the Primary Administrator.
Once the wizard has been completed, the Administration Panel will load.
5.4 TLS/SSL on database connections
The connection between your Mambo instance and the MongoDB database can be encrypted using TLS/SSL. This requires two steps:
- Configuring the MongoDB server so that it presents a certificate to connecting clients
- Configuring your Mambo application to enable TLS/SSL for connections to MongoDB
Configuring the MongoDB server
In order to configure TLS/SSL in the MongoDB server please refer to the MongoDB documentation directly.
Configuring your Mambo application
In order to configure Mambo to use TLS/SSL when connecting to MongoDB, you have to edit the mambo.properties file and set the mongo.uri configuration property to the following value (replacing username, password, db_hostname and port with the correct values):
# 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 the mongo.uri, the following configuration properties are no longer necessary and can be commented out in mambo.properties:
mongo.replicaA.host
mongo.replicaB.host
mongo.replicaC.host
mongo.port
mongo.username
mongo.password
mongo.mechanis
Please ensure that the mongo.dbname property is not commented out and is set to the correct value.
If your deployment is a ReplicaSet or you use a separate authentication database please refer to the relevant pages in 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, you will have to add the certificate to the JVM trust store of the machines running Mambo.
In order to do this, you can use the following command:
keytool -import -file certificate.crt -keystore $JAVA_HOME/lib/security/cacerts -storepass changeit
The up-to-date list of supported software can be found here.
0 Comments