Instructions and tools to setup a Solace Messaging Dev Environment
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
cf-solace-messaging-deployment @ 08d950d
cli-tools
operations
resources
templates
workspace
.banner
.gitignore
.gitmodules
.profile
CONTRIBUTING.md
LICENSE
NOTICE
README.md

README.md

SOLACE-MESSAGING-CF-DEV

This project provides instructions and tools that support local development and testing of Solace Messaging for Cloud Foundry.

Table of Contents:

About

A Deployment Solace Messaging for Cloud Foundry has prerequisites for which this guide will provide steps to satisfy:

  • A deployment of BOSH or BOSH-lite: Hosting the VMRs
  • A deployment of Cloud Foundry: Hosting the Solace Service Broker and Test Applications.
  • A deployment of Cloud Foundry MySQL: Provides p-mysql service required by the Solace Service Broker
  • A Solace BOSH Deployment: Defines and produces the bosh manifests to deploy Solace Messaging for Cloud Foundry

Operating system

This project and its tools will support a deployment on Windows, Linux and Mac.

Any instructions given for Linux will work on Mac.

This guide will provide different steps for deploying on Windows than Linux ( Mac ).

The following issues have been noted and addressed in this guide:

Hardware Requirements

Each of the following requirements for tools and software products needs to be satisfied.

A key goal is to keep what is installed directly on your host computer to a minimum, while containing everything else inside VMs. With this approach we keep a high level of containment within VMs and isolation from the host system.

RAM is biggest requirement, 16GB is the minimum, and 32GB is preferred.

You will also need at least 40GB of free disk space.

Installation Requirements

While there may be no need for internet access once the setup is completed, it is certainly required during the setup. All the steps during the setup will access the internet to download and install correctly.

Directly on your computer, you must have or get the following:

  • Install latest Git (version 2.7.1+)
  • Install latest Virtual Box (version 5.2.6+)
  • Install latest Vagrant (version 2.0.1+)
  • Shell access, use your preferred shell.

If you are installing this in a VM you will need to ensure that:

  • Intel VT-x/EPT or AMD-RVI Virtualization is enabled.

Installation on Windows

Overview of Windows Deployment

Here is an overview of what this project will help you install if you are using a windows deployment:

This guide will help you install the following VMs:

  • cli-tools to provide a reliable environment to run the scripts of this project.
    • Tested with 512mb of ram, just enough to run some scripts.
    • You may wish to increase the ram if you want to test applications from this VM. The setting for ram is in config.yml.
  • PCF-Dev for hosting the solace service broker and your applications.
    • Tested with 4GB, but you may size to suite your needs for hosting for your apps.
  • BOSH-lite for hosting VMRs.
    • Size as recommended below to fit the VMRs.

Installation Steps on Windows

The goal of the installation steps is to start the required VMs on Windows.

The setup was last tested on Windows host with 32GB of RAM, using:

  • git version 2.16.2.windows.1
  • cf version 6.35.2+88a03e995.2018-03-15
  • Vagrant 2.0.3
  • VirtualBox Version 5.2.8r121009

Installation on Windows - Step 1 - Clone this project and start up its cli-tools vm

On your computer, clone this project and start up the cli-tools vm. We will come back to use it in later steps.

git clone https://github.com/SolaceLabs/solace-messaging-cf-dev.git
cd solace-messaging-cf-dev
git submodule init
git submodule update
cd cli-tools
vagrant up

Just an example on how to run commands in cli-tools vm, which you need to do later.

cd solace-messaging-cf-dev
cd cli-tools
vagrant ssh

echo "I am running inside cli-tools vm"
exit

The cli-tools VM will contains all the necessary tools to run the scripts of this project, including another clone of this project. The workspace folder visible on your computer is shared with the cli-tools VM.

Installation on Windows - Step 2 - PCF-Dev

PCF-Dev provides a local installation of cloud foundry in a box to help test applications.

Using PCF-Dev you can install and test applications, bind to services that are available in PCF-Dev.

You can also add services to PCF-Dev, such as solace-messaging and use solace-messaging with your applications.

Our goal is to to add solace-messaging as a service in PCF-Dev.

You need to install PCF-Dev. Please follow these instructions:

cf dev start -m 4096

At this point PCF-Dev is locally installed and ready to host applications and services.

Optionally, you may follow the full Getting started with pivotal cloud foundry introduction guide, as you would learn how to install a test application in PCF-Dev.

Installation on Windows - Step 3 - BOSH-lite

We will use BOSH-lite to deploy the Solace VMR(s).

But first you need to install BOSH-lite:

  • By now you have already installed Virtual Box and Vagrant.
  • Clone bosh-lite in the workspace of this project.
cd solace-messaging-cf-dev
cd workspace
git clone https://github.com/cloudfoundry/bosh-lite
cp ../bin/create_swap.sh bosh-lite
cd bosh-lite
  • Then start bosh-lite:
    • Use VM_MEMORY=5000 if you want to host a single VMR
    • Use VM_MEMORY=15000 if you want to host 3 VMRs that can form an HA Group
    • In general, use VM_MEMORY=5000 * [Number-of-VMRs]
    • Also note the additional swap space, use 2048 Mb per VMR.
set VM_MEMORY=5000
vagrant up --provider=virtualbox
vagrant ssh -c "sudo /vagrant/create_swap.sh 2048 additionalSwapFile"
  • VERY IMPORTANT: enable routing so communication can work between your hosting computer and the VMs, one of these should work for you.
    • bosh-lite/bin/add-route
    • bosh-lite/bin/add-route.bat

Without enabled routing, the VMs will not be able to communicate. You will have re-run the add-route* scripts if you reboot your computer

You are now ready for a Solace Messaging Deployment

Installation on Linux

Overview of Linux Deployment

The goal of the installation is to prepare the required deployments.

This guide will help you install and deploy the following:

  • cli-tools to provide a reliable environment to run the scripts of this project.
    • Tested with 512mb of ram, just enough to run some scripts.
    • You may wish to increase the ram if you want to test applications from this VM. The setting for ram is in config.yml.
  • BOSH-lite for hosting CF, CF-MYSQL, Solace VMRs.
    • Size as recommended below to fit the VMRs.
  • A Deployment of CF and CF-MYSQL to BOSH-lite.

The setup was last tested on:

Linux host with 64GB of RAM, using:

  • git version 1.8.3.1
  • Vagrant 1.9.7
  • VirtualBox Version 5.1.22 r115126

Mac host with 16GB of RAM, using:

  • git version 2.15.1
  • Vagrant 2.0.1
  • VirtualBox Version 5.2.6

Installation Steps on Linux

These steps are also applicable on a Mac.

Installation on Linux - Step 1 - Clone this project and start up its cli-tools vm

On your computer, clone this project and start up the cli-tools vm. We will come back to use it in later steps.

git clone https://github.com/SolaceLabs/solace-messaging-cf-dev.git
cd solace-messaging-cf-dev
git submodule init
git submodule update

Startup the cli-tools vm.

cd cli-tools
vagrant up

Just an example on how to run commands in cli-tools vm, which you need to do later.

cd solace-messaging-cf-dev
cd cli-tools
vagrant ssh

echo "I am running inside cli-tools vm"
exit

The cli-tools VM will contains all the necessary tools to run the scripts of this project, including another clone of this project. The workspace folder visible on your computer is shared with the cli-tools VM.

Installation on Linux - Step 2 - BOSH-lite VM

A quick way to get started with BOSH is to use BUCC, it provides a convenient wrapper around a bosh-deployment.

To set BOSH-lite please use bin/bosh_lite_vm.sh -c, the '-c' create option will do the following:

  • Download and set up the bucc cli

  • Create the BOSH-lite VM

  • Create additional swap space on the BOSH-lite VM

  • Enable routing so that your hosting computer can communicate with the VMs hosting BOSH-lite

  • The following environment variable parameters are available to adjust the size of the BOSH-lite VM when creating it.

    • VM_MEMORY=8192 is the default: it is enough to support the deployment of CF, CF-MYSQL and a single VMR
    • VM_SWAP=8192 is the default: it is enough to support up to 4 VMRs before needing to add more.
    • VM_DISK_SIZE=65_536 is the default: it is enough to support up to 4 VMRs before needing more storage.
    • VM_EPHEMERAL_DISK_SIZE=32_768 is the default: it provides enough room to spare for multiple deployments and re-deployment. You should not need to adjust this.
    • In general under a BOSH-lite deployment you should add 4000 Mb to VM_MEMORY and 2000 Mb to VM_SWAP per additional VMR.
cd bin
./bosh_lite_vm.sh -c

Installation on Linux - Step 3 - Deploy CF and cf-mysql

To deploy CF and cf-mysql in BOSH-lite to host the Solace service broker and other applications:

cd bin
./cf_deploy.sh 
./cf_mysql_deploy.sh 

You are now ready for a Solace Messaging Deployment

Solace Messaging Deployment

The goal of the deployment steps is to install Solace Messaging into the running CF environment.

Deployment - Prerequisites

The Solace Pivotal Tile

Please download the Solace Pivotal Tile and keep it around for later use.

For my example I have downloaded version 1.4.0 and placed it in:

solace-messaging-cf-dev/workspace/solace-messaging-1.4.0.pivotal

Login to cli-tools VM

All deployment steps require you to be logged in to the cli-tools VM

cd solace-messaging-cf-dev
cd cli-tools
vagrant ssh

Deployment Step 1 - Extract the bosh releases from the Solace Pivotal Tile

The pivotal file is a zip file. We need to extract the relevant bosh releases needed for this deployment.

Do the following to extract the tile contents:

extract_tile.sh -t ~/workspace/solace-messaging-1.4.0.pivotal

You will find the relevant contents extracted to ~/workspace/releases

Deployment Step 2 - Upload the bosh releases to BOSH-lite

To upload the extracted bosh releases to BOSH-lite.

solace_upload_releases.sh

Deployment Step 3 - Deploy

This will deploy the VMR(s) to BOSH-lite and run an bosh errand to deploy the Solace Service Broker and add solace-messaging as a service in Cloud Foundry.

If not sure what to pick just use the default with no parameters. Otherwise, please ensure that you have allocated enough memory to the BOSH-lite VM for the number and types of VMRs that you want to deploy.

If deploying on Windows, you must also provide a -w option to the solace_deploy.sh script.

Example: Deploy the default which is a single instance of a Shared-VMR using a self-signed server certificate and evaluation vmr edition.

solace_deploy.sh

The deployment variables file used as default can be found under templates, you can make a copy and edit it.

Example: Setting admin password to 'solace1' and setting a test server certificate and disabling the service broker's certificate validation.

solace_deploy.sh -s 6000 -p solace1 -t ~/solace-messaging-cf-dev/cf-solace-messaging-deployment/operations/example-vars-files/certs.yml -n

The current deployment can be updated by simply rerunning the deployment script.

Using the Deployment

At this stage, solace-messaging is a service in the CF Deployment, and the BOSH-lite VMR deployment will auto register with the service broker and become available for use in CF.

You can use 'cf' from cli-tools, or directly from your host computer, they both access the same CF instance

For example if you deployed the default Shared-VMR, a "shared" service plan will be available and you can do this:

cf m
cf create-service solace-messaging shared solace-messaging-demo-instance
cf services

Ideally you will bind the service you created to an application and use it. You can go ahead download and test the Solace Sample Apps, or create some of your own.

Other useful commands and tools

How to login and access CF

On Windows:

cf api https://api.local.pcfdev.io --skip-ssl-validation
cf auth admin admin

On Linux:

This can be executed in the cli-tools vm or locally. If it is ran locally it needs to run inside the solace-messaging-cf-dev/bin directory.

./cf_env.sh 

How to see what is offered in the marketplace

cf marketplace

Or better yet, in short form:

cf m

Service Broker

You can use your browser to examine the deployed service broker dashboard:

  • On Windows, having PCF-Dev deployed service broker

  • On Linux, having service broker deployed on CF-Deployment

  • For Linux and Windows, you will need a username and password, do the following to discover the generated solace_broker_user and solace_broker_password

solace_broker_user=$(bosh int $WORKSPACE/deployment-vars.yml --path /solace_broker_user)
solace_broker_password=$(bosh int $WORKSPACE/deployment-vars.yml --path /solace_broker_password)
echo "solace_broker_user: $solace_broker_user       solace_broker_password: $solace_broker_password"

You can also run a script that will fetch a variety of information from the service broker

getServiceBrokerInfo.sh

To use TCP Routing feature

TCP Routing feature is available only on the Linux deployment.

In the cli-tools vm you can run this script to set up the solace router uaa client and the tcp domain.

setup_tcp_routing.sh

How to suspend and resume VMs

The VMs we created can be suspended and resumed at a later time. This way you don't need to recreate them. Their state is saved to disk.

Suspending all VMS

  • On Windows:
cd solace-messaging-cf-dev

cd cli-tools
vagrant suspend

cd ../workspace/bosh-lite
vagrant suspend

cf dev suspend
  • On Linux:
cd solace-messaging-cf-dev

cd cli-tools
vagrant suspend

The bosh created VM in virtualbox cannot be successfully restarted. But they can be preserved by pausing and saving their state in virtualbox.

bosh_lite_vm.sh -s

Alternatively you can use the virtualbox GUI to 'pause' and 'close' > 'save state'.

Resuming all VMS

  • On Windows:
cd solace-messaging-cf-dev

cd cli-tools
vagrant resume

cd ../workspace/bosh-lite
vagrant resume

cf dev resume
  • On Linux:
cd solace-messaging-cf-dev

cd cli-tools
vagrant resume

The bosh created VM in virtualbox may be resumed if previously paused and saved by using bosh_lite_vm.sh -s

bosh_lite_vm.sh -r

Alternatively you can use the virtualbox GUI to the 'start' > 'headless start'.

Working with VMR in the BOSH deployment

Listing the VMs

From the cli-tools vm:

bosh vms

Access the VMR cli

Get the list of vms, to find the IP address of the VMR instance you want:

bosh vms

Now ssh to the VMR. The admin password is whatever you had set in the vars.yml and the SSH port on this BOSH-lite deployment is set to 3022.

ssh -p 3022 admin@10.244.0.150

How to cleanup

Deleting the Solace Messaging deployment

From the cli-tools vm:

solace_delete_deployment.sh

How to delete BOSH-lite VM

On your host computer (not cli-tools)

  • On Windows
cd solace-messaging-cf-dev
cd workspace
cd bosh-lite
vagrant destroy
  • On Linux, this will destroy the VM for BOSH-lite which also contains CF, and CF-MYSQL
bosh_lite_vm.sh -d

How to delete cli-tools VM

On your host computer (not cli-tools)

  • For both Windows and Linux
cd solace-messaging-cf-dev
cd cli-tools
vagrant destroy

How to delete PCF-Dev

  • On Windows to delete PCF-Dev

On your host computer (not cli-tools)

cf dev destroy