Magnet Max Server 3.0 Deployment Properties

===

The Magnet Max 3.0 server uses a set of property files, XML files and JSON files for internal and performance configuration. Some of the properties are deployment-related. A set of templates (with .tpl suffix) are derived from the original set of property files, XML files and JSON files to separate deployment-related properties from configuration properties. These templates contain the deployment variables ${DEPLOY_xxxx} which will be replaced with the values in a deployment file (e.g., production.props).

The Magnet Max server provides one set of properties out of the box in the server/conf/default directory. The files in this "default" environment are suitable for developers to run Magnet Max server from their desktops/laptops without any external components (i.e., load balancer, remote DBMS, remote file server, remote elastic search server, remote web app server, etc.). However, when deploying the Magnet Max server using remote servers or a cloud environment, developers or DevOps should use the templates to generate the final configurations. Developers or DevOps can modify either the templates or the final configurations to fine-tune Magnet Max server performance.

===

Setup

Clone the "default" directory to a new directory (e.g. "production").

===

Tune for Performance (Optional)

In the new "production" directory, adjust the values (e.g. number of working threads, cache sizes for entities, etc.) in the ".tpl" templates (if they exist), or the files (if their corresponding .tpl files do not exist).

===

Create Deployment Properties

Create a file with common deployment properties and one file per instance in a cluster. For example,

  • "production.props" contains common properties among all instances in a cluster.
  • "production-serv1.props" and "production-serv2.props" contain properties specific to each instance in a cluster.
    production.props
    ================
    # BoA common deployment properties, use with other instance property file.

    # Use datasource_${DEPLOY_DB_TYPE}.properties : h2, hsql, mysql, postgres
    DEPLOY_DB_TYPE=mysql

    # Database Connections information: credentials, MySQL host/Postgres host
    DEPLOY_DB_USER=prodrdsuser
    DEPLOY_DB_PASSWORD=fakepassword
    DEPLOY_RDS_MYSQL_HOST=ec2-mmx20rds-boa.magnet.com
    DEPLOY_RDS_PG_HOST=ec2-rdspg.cmuh3w2eymz4.us-west-2.rds.amazonaws.com

    # Enable/disable Hibernate Hazelcast unicast.  This property works with
    # DEPLOY_HZ_NODE_MEMBERS_IP.
    DEPLOY_HBHZ_ENABLE_UNICAST=true

    # Enable/disable Hiberatnate Hazelcast multicast and use this mcast group
    DEPLOY_HBHZ_ENABLE_MCAST=false
    DEPLOY_HBHZ_MCAST_IP=224.2.2.3
    DEPLOY_HBHZ_MCAST_PORT=54327

    # Enable/disable Openfire Hazelcast unicast.  This property works with
    # DEPLOY_HZ_NODE_MEMBERS_IP
    DEPLOY_OFHZ_ENABLE_UNICAST=true

    # Enable/disable Openfire Hazelcast multicast and use this mcast group
    DEPLOY_OFHZ_ENABLE_MCAST=false
    DEPLOY_OFHZ_MCAST_IP=224.2.2.3
    DEPLOY_OFHZ_MCAST_PORT=54328

    # Comma separated intenal IP addresses for all members in a Hazelcast cluster
    # if unicast is enabled.  Set it to 127.0.0.1 if non-cluster, or empty if unicast is disabled.
    DEPLOY_HZ_NODE_MEMBERS_IP=10.4.10.94,10.4.10.95

    # Enable SSL in server
    DEPLOY_SERVER_ENABLE_SSL=true

    # Elastic Search Server: if enable_local is true, remote_host can be empty
    DEPLOY_ES_ENABLE_LOCAL=false
    DEPLOY_ES_REMOTE_HOST=10.4.11.13

    # External MMX and MMS hostnames, MMX load-balancer external hostname, MMX
    # Admin password, MMX SSL security mode
    DEPLOY_MMX_HOST=boa-mmx.magnet.com
    DEPLOY_MMS_HOST=boa.magnet.com
    DEPLOY_MMX_HOST_ELB=ec2-mmx20-elb-boa-200486208.us-west-2.elb.amazonaws.com
    DEPLOY_MMX_ADMIN_PASSWORD=fakepassword
    # SSL mode: NONE, RELAXED, or STRICT
    DEPLOY_MMX_SECURITY_MODE=RELAXED

    # SMTP Mail Server
    DEPLOY_MAIL_HOST=email-smtp.us-west-2.amazonaws.com
    DEPLOY_MAIL_USER=AKIAIOBVO463SKSHBDVA
    DEPLOY_MAIL_PASSWORD=fakepassword

    # Host for developer registration: develop-www.magnet.com | develop-developer.magnet.com
    # This is for MAX Console only.
    DEPLOY_DEV_HOST=develop-developer.magnet.com

    # Use local storage (true) or AWS S3 (false) as MAX file storage
    DEPLOY_USE_LOCAL_STORAGE=false

    # If AWS S3 File Storage is enabled, S3 buckets for sample applications and attachments
    DEPLOY_SAMPLES_S3_BUCKET_NAME=max-message-samples-dev
    DEPLOY_SAMPLES_S3_VERSION=3.0.0-SNAPSHOT
    DEPLOY_SAMPLES_S3_ACCESS_KEY=fakekey
    DEPLOY_SAMPLES_S3_ACCESS_SECRET=fakesecret
    DEPLOY_SAMPLES_S3_REGION=us-west-2

    DEPLOY_RICH_MSGS_S3_BUCKET_NAME=max-message-storage-dev2
    DEPLOY_RICH_MSGS_S3_ACCESS_KEY=fakekey
    DEPLOY_RICH_MSGS_S3_ACCESS_SECRET=fakesecret
    DEPLOY_RICH_MSGS_S3_REGION=us-west-2

The deployment properties for the local Magnet Max server "local.props" is:

    local.props
    ===========
    # Local server deployment properties.
    # Use datasource_${DEPLOY_DB_TYPE}.properties : h2, hsql, mysql, postgres
    DEPLOY_DB_TYPE=hsql

    # Database Connections
    DEPLOY_DB_USER=maxdbuser
    DEPLOY_DB_PASSWORD=fakepassword
    DEPLOY_RDS_MYSQL_HOST=localhost
    DEPLOY_RDS_PG_HOST=localhost

    # Enable SSL in server
    DEPLOY_SERVER_ENABLE_SSL=false

    # Enable/disable Hibernate Hazelcast unicast.  This property works with
    # DEPLOY_HZ_NODE_MEMBERS_IP
    DEPLOY_HBHZ_ENABLE_UNICAST=false

    # Enable/disable Hibernate Hazelcast Multicast and use this mcast group
    DEPLOY_HBHZ_ENABLE_MCAST=false
    DEPLOY_HBHZ_MCAST_IP=224.2.2.3
    DEPLOY_HBHZ_MCAST_PORT=54327

    # Enable/disable Openfire Hazelcast unicast.  This property works with
    # DEPLOY_HZ_NODE_MEMBERS_IP
    DEPLOY_OFHZ_ENABLE_UNICAST=false

    # Enable/disable Openfire Hazelcast Multicast and use this mcast group
    DEPLOY_OFHZ_ENABLE_MCAST=false
    DEPLOY_OFHZ_MCAST_IP=224.2.2.3
    DEPLOY_OFHZ_MCAST_PORT=54328

    # Hazelcast is disabled.  The members IP is ignored.
    DEPLOY_HZ_NODE_MEMBERS_IP=127.0.0.1

    # Elastic Search Server: if enable_local is true, remote_host can be empty
    DEPLOY_ES_ENABLE_LOCAL=true
    DEPLOY_ES_REMOTE_HOST=

    # MMS and MMX (same server with different ELB's), ${MY_IP} is a special macro for current host IP
    DEPLOY_MMX_HOST=${MY_IP}
    DEPLOY_MMS_HOST=${MY_IP}
    DEPLOY_MMX_HOST_ELB=localhost
    DEPLOY_MMX_ADMIN_PASSWORD=fakepassword
    # SSL mode: NONE, RELAXED, or STRICT
    DEPLOY_MMX_SECURITY_MODE=NONE

    # SMTP Mail Server
    DEPLOY_MAIL_HOST=email-smtp.us-west-2.amazonaws.com
    DEPLOY_MAIL_USER=AKIAIOBVO463SKSHBDVA
    DEPLOY_MAIL_PASSWORD=fakepassword

    # Host for developer registration: develop-developer.magnet.com
    DEPLOY_DEV_HOST=develop-developer.magnet.com

    # Use local storage (true) or AWS S3 (false) as MAX file storage
    DEPLOY_USE_LOCAL_STORAGE=true

    # If AWS S3 File Storage is enabled, S3 buckets for sample apps and attachments
    DEPLOY_SAMPLES_S3_BUCKET_NAME=max-message-samples-dev
    DEPLOY_SAMPLES_S3_VERSION=3.0.0-SNAPSHOT
    DEPLOY_SAMPLES_S3_ACCESS_KEY=fakekey
    DEPLOY_SAMPLES_S3_ACCESS_SECRET=fakesecret
    DEPLOY_SAMPLES_S3_REGION=us-west-2

    DEPLOY_RICH_MSGS_S3_BUCKET_NAME=max-message-storage-dev2
    DEPLOY_RICH_MSGS_S3_ACCESS_KEY=fakekey
    DEPLOY_RICH_MSGS_S3_ACCESS_SECRET=fakesecret
    DEPLOY_RICH_MSGS_S3_REGION=us-west-2

===

Generate Final Configurations

All deployment variables in the ".tpl" templates will be replaced with the values from the deployment property files. Deployment variables are mostly related to host names, host IP's, ports, security level and passwords. The final configuration file name has the ".tpl" suffix removed. For example, "hazelcast.xml.tpl" becomes "hazelcast.xml".

In host ec2-mms20-05-boa under the installed directory (e.g. mms30), run:

    bin/replace_env.sh server/conf/production production.props production-serv1.props

In host ec2-mms20-06-boa under the installed directory (e.g. mms30), run:

    bin/replace_env.sh server/conf/production production.props production-serv2.props

Once an environment is customized for deployment, launch the Magnet Max server with a given environment:

    bin/max-server.sh -e production start

===

Configuration Files

===

Key Store

The key store password is "password".

The following command is used to create a keystore:

    keytool -keystore keystore -alias jetty -genkey -keyalg RSA

Use the following command to export the certificate:

    keytool -export -alias jetty -file jetty.crt -keystore server.keystore

===

datasource.properties (.tpl)

This property file is used by the Magnet Max server to determine which "datasource_xxx.properties" file to use for connecting to the DBMS. HSQL is the default data source. Each "datasource_xxx.properties" file must have the "database.product.name" property and a set of JPA properties (javax.*), Hibernate properties (hibernate.*) and Openfire properties (database.*).

More information about the Hibernate properties is available at:
https://www.mkyong.com/hibernate/how-to-configure-the-c3p0-connection-pool-in-hibernate/

More information about the Openfire properties is available at:
http://download.igniterealtime.org/openfire/docs/4.0.1/documentation/

  • datasource_h2.properties: This property file contains the settings for connecting to the H2 in-memory database. It is good for unit testing purposes. The support of H2 DB is OBSOLETE.

  • datasource_hsql.properties (.tpl): This property file contains the settings for connecting to the HSQL database. It has a small memory footprint, and it runs on all OS with JavaVM. It is good for desktop development.

  • datasource_mysql.properties (.tpl): This property file contains the settings for connecting to the MySQL database. It is good for development and production. MySQL must be installed separately. Only MySQL 5.6.x is currently supported. MySQL 5.7.x has an incompatibility issue.

  • datasource_postgres.properties (.tpl): This property file contains the settings for connecting to the Postgres database. It is good for development and production. Postgres must be installed separately.

===

elastic-search.properties (.tpl)

This property file contains the settings for local or remote Elasticsearch module. Elasticsearch is being used for user search. More documentation can be found at: https://www.elastic.co/guide/en/elasticsearch/reference/current/settings.html

===

hazelcast.xml (.tpl)

This property file contains the settings for a distributed caching system used by Hibernate for MAX server data entities. For local desktop or single instance deployment, Hazelcast is configured to use localhost unicast. More documentation can be found at: http://docs.hazelcast.org/docs/3.5/manual/html/configuringhazelcast.html

===

hazelcast-cache-config.xml (.tpl)

This property file contains the settings for a distributed caching system used by the Openfire Hazelcast Plugin for its data objects. Clustering is disabled by default and the default setting is just a place holder. Use hazelcast-cache.config.xml.tpl to customize the settings. DevOps must use the Openfire Admin Console (port: 9090; user: admin) to enable clustering. Go to Server -> Clustering, and click Enabled and Save Settings. More documentation can be found at: https://www.igniterealtime.org/projects/openfire/plugins/hazelcast/readme.html

===

jsconfig.json (.tpl)

This property file contains the settings used by the Web App connecting to the Messaging server for administrative tasks.

===

logback.xml

This property file controls the logging levels for every component in the Magent Max server. The default log level is "info". The log is also indexed by Elasticsearch, so do NOT set the log level to "verbose" for all components. It will significantly slow down the server. More documentation can be found at: http://logback.qos.ch/manual/configuration.html .

===

mail.properties (.tpl)

This property file contains the settings for the SMTP mail server.

===

mm-server-config.xml

This templatized XML file contains the configurable settings for the core services in the Magnet Max server. A variable ${keyname} will be replaced by the value stored in mm-server-config-values.properties.

===

mm-server-config-values.properties (.tpl)

This property file contains the values for mm-server-config.xml. The key name has a format of ${env}.{keyname} where the ${env} can be a wildcard '*' or one of the directory names under the "conf" (e.g., default, demo, dev, qa, production).

===

mobileconfig.properties (.tpl)

This property file contains settings for the Messaging client so it can connect to Magnet Max services and the Messaging service.

===

s3.properties (.tpl)

This property file contains the settings for connecting to AWS S3 File Server. S3 is used to store the attachments for the Magnet Max server.

===

server.properties (.tpl)

This property file contains the settings for the Magnet Max server. It includes the settings for developer registration, single-sign-on for developers, developer console, choice of AWS S3 or local file system for file storage (service.storage.local), and enable or disable domain filter in user search. WordPress should NOT be used anymore with the Magnet Max server.

NOTE: The following properties are only applicable to external developers who don't use the Magnet Max Console: admin.*, cache.*, db.*, message.*, service.*

===

setupservice.properties

This property file contains the latest version number of the DB schema. It is used for by the Magnet Max server for auto-upgrade.

===

saml2.properties

This property file contains the settings for SAML v2.

===

sample_apps.properties

This property file is OBSOLETE.