Public Repository

Last pushed: 2 years ago
Short Description
Short description is empty for this repo.
Full Description

#Magnet Message
Version number:
1.0.2

June 12, 2015


##Table of Content

###Deployment Commands Highlights


#Deployment Commands Highlights

  1. Install Docker (1.6.x for Mac and Windows, the latest for Linux)
  2. To deploy on Linux (the user may be prompted for the password as it uses sudo)

    curl -sSL https://cdn.magnet.com/msd/linux/deploy.sh | sudo bash
    
  3. To deploy on Mac and Windows

    curl -sSL https://cdn.magnet.com/msd/vb/deploy.sh | bash
    
  4. To cleanup on Linux (the user may be prompted for the password as it uses sudo)

    curl -sSL https://cdn.magnet.com/msd/cleanup.sh | sudo bash
    
  1. To cleanup on Mac and Windows

    curl -sSL https://cdn.magnet.com/msd/cleanup.sh | bash
    

##What is Magnet Message?
Magnet Message is full-featured, open source mobile messaging software that allows developers to easily add messaging functionality to their mobile applications. Magnet Message is delivered as a ready-to-run server and native mobile SDKs for iOS and Android. Magnet Message is deployable in the cloud or on-premise and easily integrates with any app, existing system, or environment. For ease of administration, Magnet Message uses a web interface for configuration and management of the messaging server and reporting of in-app message and push notification delivery status.

Highlights:

  • Push and In-App Messaging: Support for push notifications and two way, in-app messaging in your iOS or Android app via push notifications, in-app messages, or bi-directional chat. Rich client side SDKs and server side APIs let you target users, devices, topics, or tags.
  • Rich Message Payloads: Send rich content, including documents, HTML, images, strings, JSON, and deep-links as the message payload.
  • Confirmed Delivery: Verify message receipts and open/read status to improve operations and compliance.
  • Secure Messaging: Protect sensitive content by securing client-server connections (via TLS) and controlling the messaging infrastructure.
  • Open Source: Freedom to use, customize, and integrate.


##What is in the Docker Image

Magnet Message standalone distribution (mmx-standalone-dist.zip).


##One Line Deployment
The followings are provided for quick and easy deployment. The deployment commands:

  1. Run the MySQL container.
  2. Run the Magnet Message container with ports mapping (between the container and the host (the VM in the case of Mac)). (If you would like to see the content of the files before executing, please feel free to execute the command without the piping | bash and curl will only pull down and display the content without the execution.)
  3. Link the 2 containers. The MySQL container is set to have a host name of mysql).
    After running the containers, the Mac users will see a browser opened with the Wizard (cloud instance users will need to open the Wizard at the url http://<ipaddress:3000> with a browser) and they may just click "Standand Install" to finish the one time configuration (the admin username/password: sysadmin@company.com/admin).

###For Mac and Windows
Docker uses VirtualBox on Mac and Windows; therefore port forwarding/mapping is required if you would like to use Magnet Message with physical devices (for using ) The following curl command will map the ports (49982 - 49990) between the VirtualBox VM and the host first. After that, it will do basically the same as for Linux.

Please note that the port numbers are currently preset. In case of port conflicts, please refer to the section, Manual Deployment. In addition, the MySQL datafiles will be mounted in the /magnet_message_mysql directory inside the Boot2Docker VM.

####Prerequisite

  1. Docker Installed (recommended: 1.6.2 or earlier, installer links: Mac, Windows. Please see Known Issues below.)
  2. Boot2Docker started.

For Windows, please execute the following command in the Unix shell that is opened when starting Boot2Docker. For Mac, you may execute it in any Terminal that has the Boot2Docker initialized ($(boot2docker shellinit)):

Command:

curl -sSL https://cdn.magnet.com/msd/vb/deploy.sh | bash

###For Linux

####Prerequisite
Docker Installed. Version 1.7

Please execute the following command:

curl -sSL https://cdn.magnet.com/msd/linux/deploy.sh | sudo bash

Note: please note that sudo is needed when docker requires sudo to execute. e.g., if docker version returns error while sudo docker version does not, then you need to run the above command with sudo.

Unlike Mac and Windows, the MySQL datafiles are mounted directly on the Linux file system and they locates in ~/magnet_message_mysql.


##Manual Deployment
If for some reasons you would like to deploy the containers manually instead of using the one-line deployment commands, please reference the following commands:

sudo docker run -d -h mysql --name mysql -v /magnet_message_mysql:/var/lib/mysql -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql/mysql-server:5.6
sudo docker run -d --name message-standalone-dist --link mysql:mysql\
 -p 9091:9091\
 -p 9090:9090\
 -p 6061:6061\
 -p 6060:6060\
 -p 5222:5222\
 -p 5221:5221\
 -p 5220:5220\
 -p 3000:3000\
 magnetsystems/message-standalone-dist:1.0.2

Note: please note that sudo is needed if docker requires sudo to execute. e.g., if docker version returns error while sudo docker version does not, then you need to run the above commands with sudo.

If you would like more info on docker run, please visit docs.docker.com. Please note that the -p exposes/maps the ports to the direct host. If it is being run on Mac/Windows, one more step is required to expose/map the ports from the VirtualBox VM to Mac/Windows. For VirtualBox port forwarding detail, please visit the virtualbox.org or here.


##Magnet Message Quickstart
Once you have the Magnet Message configured, you may want to try out the Quickstart app next (Getting Started on Android, Getting Started on iOS). After downloading the .properties for Android, please update host with the IP address of your cloud instance, Mac or Windows machine. For experienced Docker users on Mac and Windows, the Boot2Docker IP address will be another option.

For iOS, please update BaseURL in the downloaded .plist file with the IP address similarly.


##MySQL

###Backup/Export MySQL on Mac and Windows
The MySQL datafiles persist inside the VM on Mac and Windows transiently (read here for some info). Because of that and the best practice, we recommend that you back up the MySQL database regularly. It can be done easily by running the following command.

docker exec mysql /usr/bin/mysqldump magnetmessagedb > magnetmessagedb_bak.sql

###Use Other Kind of MySQL Setup
Feel free to use Amazon RDS for MySQL, Google Cloud SQL, local MySQL, etc. To do that simply run the Magnet Message container by executing:

docker run -d --name message-standalone-dist
 -p 49990:9091\
 -p 49989:9090\
 -p 49988:6061\
 -p 49987:6060\
 -p 49986:5223\
 -p 49985:5222\
 -p 49984:5221\
 -p 49983:5220\
 -p 49982:3000\
 magnetsystems/message-standalone-dist:1.0.2

(Please change the host ports as desired)

Once it starts, click Custom Install in the Wizard and provide the database information.


##To Restart the Containers
In case the containers are stopped (with the images still around. Quick check: docker images), you may restart them by doing the followings:

docker start mysql
docker start message-standalone-dist
docker exec message-standalone-dist rm /mmx-standalone-dist-1.0.2/messaging/mmx.pid
docker restart message-standalone-dist

##Ports Need to be Opened when using Cloud Instances

  • 5222 (for xmppPort)
  • 9090 (for httpPort)
  • 9091 (for httpPortSecure)
  • 6060 (for mmxAdminPort)
  • 6061 (for mmxAdminPortSecure)
  • 5220 (for mmxPublicPort)
  • 5221 (for mmxPublicPortSecure)
  • 3000 (for consolePort)

##Cleanup
There is also a one-line curl command:

For Mac and Windows

curl -sSL https://cdn.magnet.com/msd/cleanup.sh | bash

For Linux

curl -sSL https://cdn.magnet.com/msd/cleanup.sh | sudo bash

Note: please note that sudo is needed in the latter when docker requires sudo to execute. e.g., if docker version returns error while sudo docker version does not, then you need to run the above command with sudo.

##Known Issues

  1. If you see the following error message on Mac when executing a Docker command (e.g., docker info):

    An error occurred trying to connect: Get https://192.168.59.103:2376/v1.19/info: x509: certificate is valid for 127.0.0.1, 10.0.2.15, not 192.168.59.103
    

    we recommend you to downgrade Boot2Docker to 1.6.2. Reference: https://github.com/boot2docker/boot2docker/issues/824

  2. If you see:

     FATA[0019] Post http:///var/run/docker.sock/v1.18/auth: dial unix /var/run/docker.sock: no     such file or directory. Are you trying to connect to a TLS-enabled daemon without TLS?
    

    that means the Docker environment variables somehow are not set in the terminal. Simply execute this will fix it:

     $(boot2docker shellinit)
    
  3. Timeout during Magnet Message wizard configuration, step 4, on Windows.

    When configuring Message using the wizard, it may timeout on step 4. This is mostly due to the performance of the containers running on Windows. If you wait for a moment and click 'Continue', then the configuration will succeed.


For support and issues, please visit helpcenter.magnet.com.

###Testing

Docker Pull Command
Owner
magnetmessagedev