Follow

Installation Guide

Contents

  1. Overview
  2. Installing MongoDB
  3. Installing Java
  4. Installing Tomcat
    1. Running on Port 80 with Nginx
  5. Installing the Mambo Platform
    1. Deploying the WAR File
    2. Configuring the Platform
    3. Installation Wizard
    4. TLS/SSL on database connections
  6. Appendix: Supported Software

1. Overview

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.

2. Installing MongoDB

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 5.0.24. Mambo.IO platform supports MongoDB versions ≥3.2 and <6.
  • 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:

http://www.mongodb.com/blog/post/provisioned-iops-aws-marketplace-significantly-boosts-mongodb-performance-ease-use

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/

 

3. Installing Java

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.

 

4. Installing Tomcat

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 versions greater than or equal to version 8.0.14. Version 9+ has not been officially tested for support, but initial experiments show that the platform operates normally.
  • 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 8 can be downloaded from Apache here:

https://tomcat.apache.org/download-80.cgi

In order to configure the APR connector, please read the Apache documentation:

https://tomcat.apache.org/tomcat-8.0-doc/apr.html

Additional help for the APR installation can be found in the guides below:

http://www.sheroz.com/installing-apache-tomcat-native-linux-ubuntu-1204
http://dino.ciuffetti.info/2011/09/how-to-install-the-apache-tomcat-native-module/
http://tomcat.apache.org/native-doc/

In order to performance tune the Tomcat Application Server, follow the tips offered in the following links:

SlideShare: http://www.slideshare.net/lovingprince58/tomcat-optimisation-performance-tuning
PDF: http://europe.springone.com/dl/springone-amsterdam-2009/slides/MarkThomas_PerformanceTuningForApacheTomcat.pdf

The official Tomcat installation guide is fairly generic, below you will find a compiled list of installation guides for different servers. Note: some guides below explain how to install the Open JDK which is not supported by Mambo.IO, please see the guides in the Installing Java section for the proper procedures. See the guides in the Installing Java section for more information.

Server

Guide

Generic

https://tomcat.apache.org/tomcat-8.0-doc/setup.html

Ubuntu 12.04

https://www.digitalocean.com/community/tutorials/how-to-install-apache-tomcat-8-on-ubuntu-16-04

Mac OS X

https://stackoverflow.com/questions/39386212/install-tomcat-on-mac-os-x

Windows

http://www.mulesoft.com/tcat/tomcat-windows

Windows Service

https://tomcat.apache.org/tomcat-8.0-doc/windows-service-howto.html

http://www.mulesoft.com/tcat/tomcat-service

Once the installation is complete you should be able to see the Tomcat default page on http://localhost:8080. Localhost can be replaced with the IP or CNAME given to the server.

If you're installing Tomcat behind an Amazon Load Balancer and would like SSL termination to take place at the Load Balancer, then ensure you configure your Tomcat server.xml as indicated in the following article:

https://willwarren.com/2014/01/27/running-apache-tomcat-with-ssl-behind-amazon-elb/

Remember that you need to give Tomcat enough memory to run otherwise you will experience PermGen out of memory issues. To do so, find the installation folder for Tomcat:

sudo find / -name "catalina.sh"

Create a new setenv.sh file with the following line:

export JAVA_OPTS="-Xms3G -Xmx3G"

This should give Tomcat sufficient memory to run the platform. However, if you were to experience OutOfMemoryErrors, the amount of memory can be increased.

 

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.

Some people are more familiar with Apache 2.0 but for performance reasons we only support Nginx as the web server placed in front of Tomcat. As Nginx works with an Event driven architecture it is incredibly performant and will not consume large amounts of memory like Apache 2.0 does. Apache 2.0 has been known to crash in production environments with large volumes of events being tracked.
Tomcat can also be configured to run on port 80, but this will not be optimal for performance, especially when using SSL.

In order to install Nginx, please see the following guides:

http://wiki.nginx.org/Install

To configure the integration between Nginx and Tomcat, the following guide provides a very good starting point:

http://www.componentix.com/blog/18/hosting-grails-web-applications-using-tomcat-and-nginx-our-configuration

Note: each configuration will be unique based on SSL requirements, caching requirements and proxy capabilities.

In almost all cases you will need to proxy information through to Tomcat. Both Nginx and Tomcat need to be configured in order for all the information to be proxied consistently. If this isn't done, you might get UnauthorizedExceptions when attempting to call the Mambo APIs.

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.

 

5.1 Deploying the WAR File

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:

  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 the WAR file to ROOT.war
  4. Unzip / unpack the Mambo WAR file
    1. In windows you can open the WAR file using an application such as Winzip or 7-zip
    2. In Linux you can unzip the WAR file using unzip command (unzip -d ROOT.war)
    3. In Mac you can unzip the WAR file using the jar command (jar -xvf ROOT.war)
  5. Ensure that a ROOT directory is now present in the webapps folder

5.2 Configuring the Platform

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=ClusterCacheManagerImpl
  • Comment out all other cache.type properties (i.e. NoOp and Local)
    • #cache.type=NoOpCacheManagerImpl
    • #cache.type=LocalCacheManagerImpl
  • 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.

 

5.3 Installation Wizard

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

6. Support Software

The up-to-date list of supported software can be found here.

0 Comments

Article is closed for comments.