Installing and Configuring Mashery Local for Docker
The following sections describe how to install and configure some basic environments complete with a master, one or more slaves, and load balancing.
Mashery Local for Docker includes a script that will download and install third-party software from third-party websites, including but not necessarily limited to CentOS and EPEL repositories located here:
● https://hub.docker.com/_/centos/
● http://vault.centos.org/
● https://dl.fedoraproject.org/pub/epel/
Such third-party software is subject to third-party software licenses that may be available on such thirdparty websites. For more information on CentOS repositories and EPEL, see:
● https://wiki.centos.org/AdditionalResources/Repositories
● https://fedoraproject.org/wiki/EPEL
Docker Images
Three images are needed to install Mashery Local for Docker:
1. On-premise database: ml_db
2. Memcache: ml_mem
3. TIBCO Mashery
®
Local Core - Traffic Manager plus Cluster Manager UI: ml_core
Installation
To install Mashery Local for Docker:
Procedure
1. Install Docker Engine and docker-compose on your operating system.
Refer to the Docker documentation for the operating system of your choice:
● https://docs.docker.com/engine/
● https://docs.docker.com/compose/
2. TIBCO Mashery Local
®
for Docker is available as a TIB_mash-local**.tar.gz file. Download this file from TIBCO
®
eDelivery and extract the contents.
3. Navigate to the root folder of the extracted contents and run the following command to build the
Mashery Local image set (comprising three images): a)
./build-docker.sh
b) Verify three images are created: ml_db.tar.gz, ml_mem.tar.gz, ml_core.tar.gz.
4. Navigate to the examples folder and copy the docker-compose.yml and the three image .gz s to the target Docker host machine.
The docker-compose.yml may need additional edits, depending on what ports need to be exposed or for other customization. Refer to the README.md for details.
8
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
In order for NTP to work, the following modification is necessary:
1. In the docker-compose.yml file, under the Services/ml_tm section, add: privileged:
true.
(use the same indent as container_name: ml_tm)
2. Under the Services/ml_tm/ports section, add: - "123:123"
(use the same indent as - "80:80")
Note: The indents and dash are important.
Run the following commands:
● docker load -i
<each of the three image files, one by one>
● docker-compose up -d
5. Verify that four Docker containers are up: docker ps
to make sure the four containers are running.
6. Repeat Steps 4 -7 for each Docker host that will run a Mashery Local instance.
7. Go to the instance in a browser: https://<docker host-IP>:5480.
8. Complete Master registration to TIBCO MOM (Mashery On-Prem Manager) or complete Slave registration to Master.
Additional Installation Tips
Docker Toolbox is a tool that lets you manage Docker engines on multiple virtual instances, and is used with Docker Machine. If you need to setup slaves for the cluster on different virtual instances, images
built in the previous set of instructions (Step 3 of Installation
) can be reused below.
Installation steps with Docker Toolbox
1. Install docker toolbox from https://www.docker.com/products/docker-toolbox .
2. Use docker-machine create command to create Docker engines on virtual instances.
Drivers are available for various cloud provider platforms. Refer to https:// docs.docker.com/machine/ for the latest information. Also refer to individual cloud provider documentation for more details on authentication details and other parameters you can use to customize your Docker Machine.
Some example commands are below: a. To create a Docker Machine on a VirtualBox setup on your machine (prerequisite: VirtualBox 5+ ideal): docker-machine create --driver virtualbox <docker machine name> b. To create a Docker Machine on a VMware Fusion setup on your machine: docker-machine create --driver vmwarefusion <docker machine name> c. To create a Docker Machine on AWS (prerequisite: AWS signup, create an IAM administrator user and a key pair: AWS access key, AWS secret key): docker-machine create --driver amazonec2 --amazonec2-access-key <your aws access key> --amazonec2-secret-key <your aws secret key> <name for your new
AWS instance> d. To create a Docker Machine on Microsoft Azure (prerequisite: Microsoft Azure signup): docker-machine create --driver azure --azure-subscription-id <your subscription id> <name for your new azure instance>
9
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
10
e. To create a Docker Machine on Google Cloud (prerequisite: Google Cloud signup, recommend installing and configuring gcloud tools locally to manage authentication. Refer to GCE documentation.): docker-machine create --driver google --google-project <google project id> google-zone "us-west1-a" <name for your new google instance>
3. List all your available machines and make sure the one you just created shows up: docker-machine ls
4. Set environment variables for the machine you would like to deploy Mashery Local images to: docker-machine env <docker machine name>
5. Connect your shell to the new machine: eval $(docker-machine env <docker machine name>) docker-machine ls
(confirm the machine you are connecting to has an * to it to show that it's active)
6. You can use the three images you created via running the build-docker.sh script above: a. Run: docker load -i <each of the three ml.....tar.gz files> b. Obtain the latest docker-compose.yml file.
c. Run: docker compose up -d d. Use the following commands to access logs, etc., within Mashery Local containers: docker exec -it ml_tm /bin/bash docker exec -it ml_cm /bin/bash e. Login to Cluster Manager UI to complete Master registration to MOM process (https://<docker host ip>:5480)
Installation Troubleshooting Tips
Use the following tips in this section to troubleshoot your installation.
Changing the Traffic Manager Port
To change the Traffic Manager port in Mashery Local for Docker, modify the docker-compose.yml file to change the
80:80
under services:/ml_tm:/ports: to
<host port>:<container port>
, where the container port is the port you configured for the proxy.
Note that the host port could be different from the container port. The host port is the port that would be used to access the proxy from outside. After changing the ports in the docker-compose.yml, you will need to do docker-compose down and up to take them into effect. If you know the ports you are planning to switch in the future, you can add them in advance. Then, later when you decide to switch the port, you can simply change it from the UI (under Instance Management > Instance Settings >
HTTP/HTTPS port).
There could be two scenarios for changing the proxy port:
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
11
Scenario 1
●
●
●
●
●
●
Add the new port mapping to docker-compose.yml
Execute the command below if the Mashery Local Docker instance is running: docker-compose down
Execute docker-compose up -d
Change port from UI
Check whether port is in effect: docker exec -it ml_tm netstat -nlp |grep LISTEN|grep tcp
If the new port is not being listened, execute the command: docker exec -it ml_tm nohup service javaproxy restart
Scenario 2
●
●
●
●
Change port from UI
Add the new port mapping to docker-compose.yml
Execute docker-compose down
Execute docker-compose up -d
How to Enable Additional Features That Require a New Port
To enable features, such as HTTPS, that requires a new port, the port must be mapped in the dockercompose.yml file. If not, add it to the .yml file. Normally, it would be associated with Traffic Manager.
So add it under the services:/ml_tm:/ports. Then, you access from outside through the Docker host IP address.
The example docker-compose.yml file already has most needed ports mapped. However, to change the ports to be used (for example HTTP/HTTPS ports), it would be better to make the changes in the docker-compose.yml file before starting the containers so that the mapping are in place. Then later, you can modify the UI to change the ports. However, if new port was not in effect after the UI change, try restarting the javaproxy. This can be done with command docker exec -it ml_tm nohup service javaproxy restart
.
How to Use NFS for Verbose Log
To use NFS for verbose log:
1. Mount the NFS to a host directory, for example,
/mnt/nfs
.
2. Add the volume mapping in the docker-compose.yml file under the services:/ml_tm:/volumes, for example:
- /mnt/nfs:/var/log/tm_verbose_log
Use the same indent as the existing entry
- mldata:/mnt
.
3. Execute docker-compose down
4. Execute docker-compose up -d
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
12
5. Modify the UI to set the Verbose Logs Location to
/var/log/tm_verbose_log
but leave the flag
Use NFS unchecked.
6. Enable the verbose log.
7. Execute docker exec -it ml_tm nohup service javaproxy restart
Managing Docker Containers
Use the following commands to manage the Docker containers:
Action
Pause
Unpause
Restart
Shut down
Complete Cleanup
(remove persistent data)
Command
docker-compose pause docker-compose unpause docker-compose restart docker-compose down docker volume rm $(docker volume ls -q)
This will clean up all the database content and configurations.
Then, you will need to redo and register the master and slave after rerunning Mashery Local for Docker.
This command removes all volumes for a docker host. If you have other volumes besides those used by Mashery Local for
Docker, you must remove the volumes for Mashery Local for
Docker individually.
Configuring the Mashery Local Cluster
Mashery Local may run configured in a cluster of one master and multiple slaves.
To configure the Mashery
®
Local cluster, you need to:
●
●
Configure a Mashery local master
Configure slave(s) to the local master
Configuring a Mashery Local Master
To configure a Mashery Local master:
Procedure
1. Browse to the Mashery Local Cluster Manager of the master by using the Docker Host IP address of the instance: https://<IP_address_of_instance>:5480
2. Login with username administrator and the password configured in set-user-variables.sh.
Click Master.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
13
The Configure Master window appears.
Enter an instance name (this name will eventually display in the Mashery Admin Dashboard) that is meaningful to your operation, the Mashery Cloud Key and shared secret provided by TIBCO
Mashery, and the NTP server address, if used.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
14
3. Click Commence Initiation Sequence.
After the Master initializes with the Mashery cloud service, a completion page appears.
4. Click Continue.
5. Navigate to the Cloud Sync page and perform manual syncs for API Settings and Developers by clicking the adjacent icons:
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
15
6. Test the instance as described in Testing a New Instance
.
7. See the instructions in Advanced Configuration for how to enable notifications, if desired.
Configuring Slaves to the Local Master
Mashery Local may run configured in a cluster of one master and multiple slaves.
To configure slaves to the master:
Procedure
1. Browse to the Mashery Local Cluster Manager of the slave by using the Docker Host IP address of the instance: https://<IP_address_of_instance>:5480
2. Login with username administrator and the password provided by TIBCO Mashery.
3. Click Slave.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
16
4. Enter an instance name (this name will eventually display in the Mashery Admin Dashboard) that is meaningful to your operation, the Mashery Cloud Key and shared secret provided by TIBCO
Mashery, and the NTP server address, if used.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
17
5. Click Register with Mashery and Master.
6. Click Continue.
7. Test the instances as described in Testing a New Instance
.
8. See the instructions in Advanced Configuration for how to enable notifications, and API and JMX
reporting access, if desired.
Configuring the Load Balancer
TIBCO Mashery recommends using a Load Balancer to best utilize the cluster, although this is not required because you may route your API traffic directly to each instance.
Each instance hosts a service called /mashping. Configure the Load Balancer to access the following address, without the host header: http://<IP_address_of_instance>/mashping
If the Load Balancer and the cluster is working correctly, /mashping returns the following response:
HTTP/1.1 200 OK
Server: Mashery Proxy
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
{"status":200,"time":1315510300,"message":"success"}
If /mashping returns any other response, then the load balancer should remove the instance from the cluster and either retry after a period of time or alert operations to investigate.
Mashery Local has two instance types: Master and Slave. Should the Load Balancer pull the Master out of the cluster pool, an Operations engineer should immediately investigate whether it can be recovered,
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
18
and, if not, promote a Slave to Master. If no Master exists in the pool, data synchronization with the
Mashery Cloud Service will not occur with the exception of API event activity. Access Tokens, Keys,
Applications, Classes and Services will not be synchronized.
Configuring the Instance
The Instance Management tab allows you to configure additional settings for that particular instance. You can edit the instance name, configure instance settings, and update software and custom adapters. Additional system-level parameters can be tuned here such as application memory allocation, configuration cache size, maximum concurrent connections, and connection pool size for the database.
To configure an instance:
Procedure
1. On the Mashery Cluster Manager tab, click Instance Management.
2. Click the Management Options for which you want to configure the settings.
A text box is displayed for the selected Management Options.
3. Enter the details for the following fields to configure the instance.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
19
Field
Use NTP
(recommended)
Description
NTP server address.
Memory Allocation Specify application memory size as a fraction of the available memory.
Concurrent
Connections
Sets the maximum number of concurrent connections to the service instance.
Database Connector Sets the maximum number of concurrent connections the instance will make to its database.
Configuration Cache Specify the memory (in MB) to use for configuration cache.
Disable IPv6 Select this option to disable IPv6 if IPv6 traffic should not be allowed to the backend. By default, Mashery Local supports both IPv4 and IPv6.
4. Select the appropriate HTTP Server Security Level:
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
20
●
Enable HTTP only: If selected, the default HTTP Port for HTTP Server Security Settings is
80
.
●
Enable HTTPS only: If selected, enter the details for the following fields:
Field
HTTPS Port
Description
Specify the HTTPS port. The default is
443
.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
Field
Certificate Common
Name (display only)
Description
Automatically displays the name of the selected certificate.
Certificate # (display only)
Automatically displays the number of the selected certificate.
New SSL Certificate
Select from:
●
Create new certificate: If selected, enter a Certificate Common name in the Create SSL Certificate window, then click Create.
21
●
Upload new certificate: If selected, in the Upload SSL Certificate window, browse to the SSL certificate using the Click here to
select file link, enter the Password for Certificate, then click
Upload.
Download SSL
Certificate
Select from:
●
●
Download certificate in PEM: downloads the current certificate in PEM format.
Download certificate in DER: downloads the current certificate in
DER format.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
22
●
Enable HTTP and HTTPS: If selected, enter the details for the following fields:
Field
HTTP Port
HTTPS Port
Certificate Common
Name (display only)
Description
Specify the HTTP port. The default is
80
Specify the HTTPS port. The default is
.
443
.
Displays the name of the selected certificate.
Certificate # (display only)
Displays the number of the selected certificate.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
Field Description
New SSL Certificate
Select from:
●
Create new certificate: If selected, enter a Certificate Common name in the Create SSL Certificate window, then click Create.
23
●
Upload new certificate: If selected, in the Upload SSL Certificate window, browse to the SSL certificate using the Click here to
select file link, enter the Password for Certificate, then click
Upload.
Download SSL
Certificate
Select from:
●
●
Download certificate in PEM: downloads the current certificate in PEM format.
Download certificate in DER: downloads the current certificate in
DER format.
5. Click Save.
You may be reminded that Mashery Local needs to restart proxy service.
The instance is configured for the specified settings.
TIBCO Mashery
®
Local Installation and Configuration Guide for Docker
