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 Mambo.IO platform supports MongoDB versions greater than or equal to version 3.2
- Server Addresses: make a note of the address of each of the servers in the replica set
- Port: use the default MongoDB installation port of 27017
- Mongod.conf: Note: t 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 8.
- 64 Bit: for optimal performance the 64-bit JRE/JDK must be installed.
- Oracle JRE/JDK: the officially supported version of the JVM is the one provided by Oracle.
The latest JRE/JDK 8 can be download from Oracle here:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
The installation guides for Linux, Windows and Mac can be found here:
https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html
There are also specific installation guides available for Ubuntu:
http://tipsonubuntu.com/2016/07/31/install-oracle-java-8-9-ubuntu-16-04-linux-mint-18/
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 |
|
|
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 |
|
|
Windows Service |
https://tomcat.apache.org/tomcat-8.0-doc/windows-service-howto.html |
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 -XX:+UseConcMarkSweepGC"
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
If you wish to run Tomcat on Port 80, you must install Nginx.
Nginx: http://nginx.org/
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:
To configure the integration between Nginx and Tomcat, the following guide provides a very good starting point:
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.
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 7 can write the log files into the folder. If you run Tomcat7 with it's own user and group, then the permissions command might look something like this:
sudo chown tomcat7:tomcat7 /var/log/mambo
Once this is done, you are ready for the next step!
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.
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.
The up-to-date list of supported software can be found here.
0 Comments