Installation

System Requirements

Follow the links below to download and install the required software components.

  • Java 7.0+ SE

  • Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files

    Note: Some distributions of Java, like OpenJDK, already have JCE installed. However, for Oracle's JRE/JDK, you will need to install JCE manually.

    Per the README.txt file, copy local_policy.jar and US_export_policy.jar to /lib/security if you are running the Java runtime, /jre/lib/security for the JDK.

  • MongoDB 2.6+

    MongoDB's documentation site provides excellent installation instructions. Out of the box, MongoDB does not authenticate clients. For production installations, it is recommended that you enable one of MongoDB's supported authentication mechanisms.

Standalone Installation

Steps 2-5 are optional for a development installation.

  1. Download Monarch and extract to the desired location in your filesystem.

  2. To set MongoDB authentication credentials, open conf/monarch-cluster.properties and update the mongoDb.* settings accordingly. You can also target multiple MongoDB servers (replica sets).

    mongoDb.serverAddresses=mongodb01:27017,mongodb02:27017,mongodb03:27017
    mongoDb.systemDatabase=monarch
    mongoDb.authMechanism=SCRAM-SHA-1
    mongoDb.authDatabase=admin
    mongoDb.username=username
    mongoDb.password=AUTOENC(password)
    mongoDb.credentials=${mongoDb.authMechanism}:${mongoDb.username}:${mongoDb.authDatabase}:${mongoDb.password}
    

    Note: Any sensitive values, such as passwords, can be enclosed by AUTOENC(), for example AUTOENC(password), and the system will automatically encrypt them on startup.

  3. Change the node/server's name in open conf/monarch-node.properties. Below is the default configuration:

    global.serverName=Bravo
    
  4. The default configuration will only listen for HTTP on port 8000. To change listening ports or enable SSL or AJP (for use with mod_jk or mod_proxy), then open conf/standalone.properties.

    For setting up SSL, the Tomcat SSL How-To provides good instructions for creating your keystore. Then set server.https.enabled=true and server.keyStore.path and server.keyStore.password accordingly.

  5. For LDAP authentication, configure the following properties in conf/monarch-cluster.properties.

    auth.ldap.url=ldap://ldap.company.com:389
    auth.ldap.authMethod=DIGEST-MD5
    auth.ldap.userDN={0}
    auth.ldap.uidAttribute=sAMAccountName
    auth.ldap.baseDN=OU=Users,DC=company,DC=com
    auth.ldap.useSSL=false
    auth.ldap.firstNameAttribute=givenname
    auth.ldap.lastNameAttribute=sn
    auth.ldap.idAttribute=objectGUID
    auth.ldap.idIsBinary=true
    auth.ldap.userGroups=CN=Monarch Users,CN=Users,DC=company,DC=com
    auth.ldap.adminGroups=CN=Monarch Administrators,CN=Users,DC=company,DC=com
    

    Then comment out mongoDbAuthenticationService and uncomment ldapAuthenticationService in conf/context-services.xml.

  6. Run bin/startup (Linux or MacOSX) or bin\startup.bat (Windows). On the very first startup, two configuration items will be initialized automatically:

    1. A file called .pbekey will be created in the conf directory. This contains the encryption key the system uses for encrypting and protecting passwords in property files, such as monarch.properties. This file will be hidden and on Unix/Linux, it will be locked down to the user that is running Monarch. On Windows, the ACL should be changed to limit read/write access to only administrators and the account running Monarch. For now, this must he done manually on Windows.

    2. A value for encrpytion.base64Key will be created. This is used as the master encryption key for protecting sensitive data in the database, such as API keys and shared secrets.

  7. Point your browser to http://localhost:8000. If you are using default authentication, Monarch will create an administrator account during the first launch. un=admin, pw=admin.

  8. Create an initial environment. If you have MongoDB credentials enabled, you'll need to create the database and grant permissions beforehand.

Application Server Installation

In order to run Monarch from an application server (such as Tomcat, JBoss/WildFly, WebLogic, or WebSphere), you must follow the steps 1 - 3 above followed by these steps.

  1. Run bin/make-war (Linux or MacOSX) or bin\make-war.bat (Windows) to generate api-manager.war.

  2. Configure the following system properties in the application server:

    • monarch.home - (Required) Points to the extracted Monarch directory.

    • monarch.conf - (Optional) Location for all configuration files. Defaults to ${monarch.home}/conf but can be overridden by this value. Under Unix, instead of overriding this value, you might consider creating /etc/monarch and a symbolic link from ${monarch.home}/conf.

    • monarch.logs - (Optional) Location for all log files. Defaults to ${monarch.home}/logs but can be overridden by this value. Under Unix, instead of overriding this value, you might consider creating /var/log/messages and a symbolic link from ${monarch.home}/logs.

    Setting system properties is different with each application server. Here are a few suggestions on how to do it.

    • Tomcat - Add a -D value to CATALINA_OPTS in either bin/catalina.sh/bat or creating bin/setenv.sh (recommended for non RPM installs).

      export CATALINA_OPTS="$CATALINA_OPTS -Dmonarch.home=???"
      
    • JBoss/WildFly - Properties can be added in domain.xml, host.xml, and standalone.xml, depending on your needs. See the WildFly Admin Guide for system properties.

    • WebLogic - You can set system properties in the admin console or add them by hand to the startWeblogic script.

    • WebSphere - You can set system properties using the admin console and following these steps.

  3. Deploy the generated api-manager.war to your application server.

Cluster Installation

Important: When setting up additional Monarch nodes, make sure that .pbekey and monarch-cluster.properties are copied to the new node's conf directory. You might consider a distributed filesystem to share these settings between servers.

On Unix-based systems, you can use tools like rsync and lsyncd to keep all files in the conf directory, excluding monarch-node.properties, synchronized between servers.

Load Balancing

If running standalone or in Tomcat, Monarch supports the AJP protocol (apache mod_jk or mod_proxy). If you do not use the AJP protocol from your load balancer, make sure the X-Forwarded-For and X-Forwarded-Proto request headers are being passed along.

Here is an example of an Apache SSL configuration with mod_proxy using HTTP. Notice that X-Forwarded-Proto is not passed by mod_proxy, thus it must be set manually.

<VirtualHost *:443>
    RequestHeader set X-Forwarded-Proto "https"
    ProxyPreserveHost On
    ServerName api-manager.company.com

    SSLEngine On
    SSLCertificateFile /etc/apache2/ssl/server.crt
    SSLCertificateKeyFile /etc/apache2/ssl/server.key

    <Location/>
        SSLRequireSSL
    </Location>

    ProxyPass / http://127.0.0.1:8000/
    ProxyPassReverse / http://127.0.0.1:8000/
</VirtualHost>

For AJP, simply change the ProxyPass and ProxyPassReverse settings accordingly.

    ProxyPass / ajp://127.0.0.1:8009/
    ProxyPassReverse / ajp://127.0.0.1:8009/