We're very pleased that you want to get in touch with us. Please fill in the form below:

or   Close this form  
Some content

Peter Pilgrim :: Java Champion :: Digital Developer Architect

I design Java EE and Scala software solutions for the blue-chip clients and private sector

Hey all! Thanks for visiting. I provide fringe benefits to interested readers: checkout consultancy, training or mentorship Please make enquiries by email or call +44 (0)7397 067 658.

Due to the Off-Payroll Working plan for the UK government, I am enforcing stricter measures on contracts. All potential public sector GOV.UK contracts engagements must be approved by QDOS and/or SJD Accounting. Please enquire for further information.

How to deploy BOSH-Lite and Cloud Foundry locally on Mac Book Pro (2018)

19 January 2018 Comments off

11 minutes


This is a rough note on how I deployed BOSH Lite and Cloud Foundry on my MacBook Pro machine in January 2018. First, I have a word of warning that you will need a very good Internet connection preferable fast Fibre is the best and second, it will take a long time to achieve. (It took me two days to achieve with help from a colleague experienced in BOSH).

What are these little markers? #0

What is BOSH?

BOSH is a recursive acronym and it is the release engineering that helps system administrators control and manage another product called Cloud Foundry. BOSH stands for BOSH outer shell. The naming is not an cruel trick, but a computer science tradition (See GNU #1).

BOSH is designed to work in a cloud-native environment and not on your local workstation, MacBook Pro machine. BOSH has a little brother called BOSH Lite, which this article is concerned with.

What is a Cloud Foundry

Cloud Foundry is a PaaS, which stands for Platform as a Service #2. Cloud Foundry is a distributed computing platform that leverages and sits on top of an existing elastic computing infrastructure. In other words, Cloud Foundry provides an abstract layer over a PAYG Platform as a Service #3 cloud provider like Amazon Web Service and Azure.


You will need the following pieces of software:

If you really want to follow along with me, then I recommend installing Homebrew or just Brew on your MBP, if you haven’t already. If you do then you following along with the following commands:

$ brew upgrade
$ brew install git
$ brew install atom
$ brew install sublime

The dollar ($) is the terminal prompt.

To stop Brew upgrading everytime you issue an command on the terminal, please use the following stanza:


Installing BOSH

Only if you installed the old BOSH, by accident or deliberately, remove the old BOSH CLI v1.0 client with the following command:

$ gem uninstall bosh_cli

It is a Ruby Gem, and the new BOSH CLI v2.0 doesn’t require Ruby anymore.

Download BOSH CLI from the web page, which take you to a download link. I use WGET to retrieve the executable file.

wget https://s3.amazonaws.com/bosh-cli-artifacts/bosh-cli-2.0.48-darwin-amd64

Yes. The name Darwin means a native executable for the Mac OS X system. You might have to upgrade your version of Open SSL, and so I used Brew to do this:

$ HOMEBREW_NO_AUTO_UPDATE=1  brew install openssl

Check your version of Virtual Box is greater or equal to 5.1

$ VBoxManage --version

Now create a workspace for your training purposes and clone the BOSH deployment from the repository:

$ mkdir -p ~/Documents/IdeaProjects/training/pcf
$ cd ~/Documents/IdeaProjects/training/pcf
$ git clone https://github.com/cloudfoundry/bosh-deployment

Whilst, still inside this folder "pcf" on my machine, I created a workspace for the deployment for the Virtual Box Image (vis-a-vis the VM).

$ mkdir -p deployments/vbox

Execute the BOSH command to create the BOSH Director.

$ bosh create-env $HOME/Documents/IdeaProjects/training/pcf/bosh-deployment/bosh.yml \
					--state ./state.json \ 
					-o $HOME/Documents/IdeaProjects/training/pcf/bosh-deployment/virtualbox/cpi.yml  \
					-o $HOME/Documents/IdeaProjects/training/pcf/bosh-deployment/virtualbox/outbound-network.yml  \
					-o $HOME/Documents/IdeaProjects/training/pcf/bosh-deployment/bosh-lite.yml \
					-o $HOME/Documents/IdeaProjects/training/pcf/bosh-deployment/bosh-lite-runc.yml \
					-o $HOME/Documents/IdeaProjects/training/pcf/bosh-deployment/jumpbox-user.yml \
					--vars-store ./creds.yml   -v director_name="Bosh Lite Director" \
					-v internal_ip=  \
					-v internal_gw=  \ 
					-v internal_cidr=  \
					-v outbound_network_name=NatNetwork

This command will start to install the BOSH Lite Director. On your MBP, it will create a VirtualBox VM with the internal IP of, it will have internal gateway of and your CIDR ("cider") will be a subnet of

Time as a cloud-native platform software engineerseems to be so short these days, however let me please explain a few items #4.

  1. BOSH Director (LITE) is the process that orchestrate the release management of Cloud Foundry. We have to install the BOSH Director in order for it to manage a collection of Virtual Machines (VMs)/li>
  2. A Virtual Machine in a Cloud Foundry parlance is either a job, a release or a stem cell.
  3. A Stem Cell is an abstract around an operating system distribution, be it Ubuntu Linux, Red Hat Linux or CentOS Linux


Be warned this command take a long time, it might fail several times, but keep running the bosh create-env until you are successful. You should be able to see the VMs running with the BOSH Director #5.

Authenticate with Bosh Director

Once the BOSH Lite Director is installed successfully by the CLI command, then you need to authenticate yourself. Normally, in a professional cloud, you will sign digital cryptographic certificate with a key store.

$ cd deployments/vbox
$ bosh alias-env vbox -e --ca-cert <(bosh int ./creds.yml --path /director_ssl/ca)
$ export BOSH_CLIENT=admin
$ export BOSH_CLIENT_SECRET=`bosh int ./creds.yml --path /admin_password`

The bosh alias-env assigns the BOSH Director by IP and its self-signed certifcate. It is helpful to examine the environment variables with the following:

$ env | grep BOSH 

You should be now logged in and authenticated as the "admin" user. So try the next command, which list the VMs.

$ bosh vms

The output will be like this:

Using environment '' as client 'admin'

Task 66. Done

Deployment 'cf'

Instance                                                  Process State  AZ  IPs           VM CID                                VM Type        Active  
adapter/71474877-440d-4015-84f8-5729c041e654              running        z1  72df1e7c-6c6e-49ab-629f-cdb4eab2e3c9  minimal        false  
api/88befba3-6653-4e61-b28b-cc493a54b544                  running        z1  a1a13cb5-63d0-4ae2-5949-df310e151bd5  small          false  
cc-worker/dd7a404b-cc8b-4793-b2e4-9993c89f5ddf            running        z1  fc0f8460-db65-411d-60c0-fa70d22ae085  minimal        false  
consul/5c274527-ea35-42ee-a7b6-db8ba4b17673               running        z1  b1d61e86-6c6b-45b0-5e48-aa94db98ff43  minimal        false  
database/6ba09210-f60e-4e7a-8053-5f4b0939fee7             running        z1  4c58bc63-dd56-4aa0-7dee-3748c2917b32  small          false  
diego-api/13abb413-d539-44b5-ae1a-d6b219197e57            running        z1  4e10a4f8-8ffb-4192-7f40-ba41d0a5b790  small          false  
diego-cell/a5fb54df-f3ca-4654-a6b7-e1faba9f309a           running        z2  93a90378-5506-47e2-7972-3e04179993a7  small-highmem  false  
diego-cell/e47c98c9-50ae-4b0e-a900-822d302f1983           running        z1  02185d59-05a0-4359-489e-91d9b4274e3a  small-highmem  false  
doppler/f5d3fda3-7361-4cf1-b55c-4bbcebb59149              running        z1  e75f8958-7913-4c32-74e5-317461de3400  minimal        false  
log-api/6ca9570d-1428-405f-be43-d06a68f7f9f3              running        z1  2cf5728b-d878-40c1-64dd-757dfc96c986  minimal        false  
nats/a4525ab6-df31-44fe-87ad-2a19ac613f76                 running        z1  c043961c-829a-4dc4-5dba-37514c17a8f5  minimal        false  
router/f1903842-078e-49a8-81d5-bc710f1914f0               running        z1   cf1f5e14-adf7-4bc1-4690-fd27301652e3  minimal        false  
scheduler/8c01354b-6a93-48d4-873f-abfe83f90ccc            running        z1  6380fbdb-2fb4-4a6b-52c8-26690be2d6ae  minimal        false  
singleton-blobstore/56f7d29f-d296-4bc5-aeb2-387acde53fb7  running        z1  8c234dc2-bd73-4425-430c-a9e9f1f5a90b  small          false  
tcp-router/09a779ad-0f4a-466c-8f47-748a8cedfb39           running        z1  a9c87538-889a-457d-6fe3-93a1fcf707ec  minimal        false  
uaa/e7d38bfd-40f9-4add-9f60-83ab03054d2b                  running        z1  8f65b7f7-d25c-4459-4b2b-83debd7bd038  minimal        false  

16 vms


Ensure that you can see diego-cell in your output. If you can filter for this term, then you will be able to deploy cloud foundry next, otherwise something went wrong.

Update the Cloud Configuration

Update the cloud configuration for your local MBP with the following. Clone the Cloud Foundry repo

$ cd ~/Documents/IdeaProjects/training/pcf
$ git clone https://github.com/cloudfoundry/cf-deployment.git
$ cd cf-deployment
$ bosh -e vbox update-cloud-config iaas-support/bosh-lite/cloud-config.yml --ca-cert ../deployments/vbox/ca.crt 

You might have to work around a buggette.

$ export BOSH_CA_CERT=$HOME/Documents/IdeaProjects/training/pcf/deployments/vbox/ca.crt 
$ export BOSH_ENVIRONMENT=vbox
$ bosh -e vbox update-cloud-config iaas-support/bosh-lite/cloud-config.yml

You need to download a Stem Cell from the usual place and with a working BOSH Director install it #6.

$ bosh upload-stemcell ~/Downloads/bosh-stemcell-3468.17-warden-boshlite-ubuntu-trusty-go_agent.tgz 

At this point, my colleague stepped into help me remove old BOSH v1.0 configuration and add new internal networking route. Essentially, we grok the contents of this file: add-route script.

$ old_ips=""
$ ips=""
$ gw=""
$ sudo route delete -net $old_ips $gw
$ sudo route delete -net $old_ips $gw
$ sudo route delete -net $ips     $gw

Here, we have to remove the old route configuration, BOSH version 1, which relies on the Vagrant solution. Now, we set up the new BOSH Lite director and configure a local route on our MBP at

$ gw=""
$ sudo route add -net $ips $gw
$ curl https://api.bosh-lite.com -k
$ host api.bosh-lite.com

At this point, you should be able to point your most favourite web browser to the local URL: api.bosh-lite.com, which will be a RESTful endpoint. BOSH Director LITE is being served on your Oracle Virtual Box, which in it instance is managing 16 other VMS. Howe cool is that? Congratulations, you have Cloud Foundry running on MacBook Pro.

Deploying the Spring Music application

So the next steps are fairly easy. Download the Cloud Foundry CLI on make it executable on your MBP. You now need to point the CF CLI to your Bosh Director instance.

$ cf login -a https://api.bosh-lite.com --skip-ssl-validation

Create a Cloud Foundry called "system" under the default organisation "system"

$ cf create-space system

Now target the organisation and the space in the your default foundation. (You only have one.)

$ cf target -o system
$ cf target -s system
$ cf status

Swith to Spring Music example directory, and then compile and build the example Java application.

$ cd ../spring-music
$ ./gradlew clean assemble

Now you already logged into Cloud Foundry and you can push to your foundation on your MBP.

$ cf push
$ cf logs spring-music --recent

Pay attention to the output, because you will see a dynamic referential URL link such as http://spring-music-bright-duiker.bosh-lite.com. Open browser at this URL and you are done for the day!

Thoughts, likes, shares and feeback are alway welcomed, so don't be shy.


NB: This article is still work in progress, any errors I will correct over the next few days or so... Thanks for your understanding.

January 2018




  1. Thomas Mitchell blog article, Deploying Cloud Foundry Locally with Bosh Lite (Late 2015)
  2. Official BOSH Lite documentation
  3. Cloud Foundry CLI
  4. Official Cloud Foundry Deployment Guide
  5. Cloud Foundry - Diego Design Notes
  6. BOSH Lite V2.0 for Virtual Box
  7. Spring Music Spring Boot example application by Scott Federick GitHub repository
  8. Cloud Foundry official stem cells
  9. Kris Hicks's YAML Patch source GitHub repository



No Comments

No comments yet.

RSS feed for comments on this post.

Sorry, the comment form is closed at this time.

Contents of this blog entry are under copyright © 2017 by Peter Pilgrim and associates. For enquiries after republishing, please contact us for permission. All requests for syndicated content will be ignored /dev/null, consider yourself warned!

I help to design, create and build JVM components and services that are behind popular e-commerce websites.

My Blurb

Please get in touch , directly, to establish hire availability, contract & consulting opportunities.

Speaking at Your Conference

Contact by invitation

What Peter Does