Indeed, it seems worthwhile to write down the few steps necessary to install BOSH Lite, to deploy Cloud Foundry (cf), and to push a web console for Cloud Foundry to your local space.
As a software developer you might be interested in a complete and working installation. As a computer geek as myself you might be more kin to know the ingredients of this recipe and the way they combine with each other. In this article I have tried to serve both clients.
In this mixture a few generally available components have found their usage, by the time of writing they were:
$ sw_vers
ProductName: Mac OS X
ProductVersion: 10.14.2
BuildVersion: 18C54
$ xcode-select --version
xcode-select version 2354.
$ brew --version
Homebrew 1.8.6
Homebrew/homebrew-core (git revision 0482; last commit 2018-12-23)
Homebrew/homebrew-cask (git revision 8734b; last commit 2018-12-22)
$ vboxmanage --version
5.2.22r126460
$ vboxmanage list extpacks | grep Version -B1
Pack no. 0: Oracle VM VirtualBox Extension Pack
Version: 5.2.22
$ bosh --version
version 5.4.0-891ff634-2018-11-14T00:21:14Z
$ credhub --version
CLI Version: 2.2.0
Server Version: 2.0.2
$ cf --version
cf version 6.41.0+dd4c76cdd.2018-11-28
Not all of these components need to be versioned at these exact levels. However, as your mileage may vary, it is a good idea to get as close as possible to these versions. So let's start.
1. macOS Mojave
The latest, the greatest.
open -a Safari https://itunes.apple.com/us/app/macos-mojave/id1398502828
2. Xcode Command Line Tools for macOS
It might be necessary to automatically compile and install curl and git with support for TLS 1.2.
xcode-select --install
3. Homebrew
The missing package manager for macOS.
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"4. VirtualBox and its Extension Pack
VirtualBox is a general-purpose full virtualizer for x86 hardware, targeted at server, desktop and embedded use.
brew cask install virtualbox
sudo vboxmanage extpack install Oracle_VM_VirtualBox_Extension_Pack-5.2.22.vbox-extpackThe bosh CLI is the command line interface for interacting with what BOSH does, from deployment operations to software release management. BOSH is purposefully used to deploy Cloud Foundry at large, whereas, BOSH Lite is used for local instances of Cloud Foundry, like the one in this article.
brew install cloudfoundry/tap/bosh-cli
CredHub provides a CLI and API to manage credentials (usernames, passwords, certificates, keys and other arbitrary values) in a secure fashion. The API exposed by the CredHub server for BOSH are also accessed by the credhub CLI.
brew install cloudfoundry/tap/credhub-cli
7. Cloud Foundry CLI for macOS
Cloud Foundry CLI, aka cf, is the official command line client for Cloud Foundry.
brew install cloudfoundry/tap/cf-cli
Following docs and tutorials of BOSH, we begin by cloning (i.e. downloading) the bosh-deployment repository.
mkdir -p bosh-cf-webui
cd bosh-cf-webui
git clone https://github.com/cloudfoundry/bosh-deployment
cd bosh-deploymentIf you feel like you may need some more power (cpus, memory or ephemeral_disk) for your Cloud Foundry deployment, then double these cloud_properties to get a little boost in performance. Below you can see the difference between the default values found within the virtualbox/cpi.yml file at the line # Configure sizes, and the supposedly better settings:
# Configure sizes
- type: replace
path: /resource_pools/name=vms/cloud_properties?
value:- cpus: 2
+ cpus: 4
- memory: 4096
+ memory: 8192
- ephemeral_disk: 16_384
+ ephemeral_disk: 32_768Note: The property paravirtprovider is not explicitly assigned, which leads to its default minimal value. That opens the case to further experimenting. As the standard stemcell (see below) hosting the BOSH Director virtual machine is a Linux Ubuntu one, there is a good chance that appending the property and value paravirtprovider: kvm might bring some performance boost. By the way, feel free to fork this article and experiment further.
By now, let's just perform these three steps:
- Create the BOSH Director virtual machine
bosh create-env bosh.yml --state state.json -o virtualbox/cpi.yml -o virtualbox/outbound-network.yml -o bosh-lite.yml -o bosh-lite-runc.yml -o uaa.yml -o credhub.yml -o jumpbox-user.yml --vars-store creds.yml -v director_name=bosh-lite -v internal_ip=192.168.50.6 -v internal_gw=192.168.50.1 -v internal_cidr=192.168.50.0/24 -v outbound_network_name=NatNetwork
Note: Non-wrapping in the command is intended. This step will take some time.
- Set a route and environment variables
sudo route add -net 10.244.0.0/16 192.168.50.6
export BOSH_CA_CERT=`bosh int creds.yml --path /director_ssl/ca`
export BOSH_ENVIRONMENT=vbox
export BOSH_CLIENT=admin
export BOSH_CLIENT_SECRET=`bosh int creds.yml --path /admin_password`
export CREDHUB_SERVER=https://192.168.50.6:8844
export CREDHUB_CLIENT=credhub-admin
export CREDHUB_SECRET=`bosh int creds.yml --path=/credhub_admin_client_secret`
export CREDHUB_CA_CERT="$(bosh int creds.yml --path=/credhub_tls/ca)"$'\n'"$(bosh int creds.yml --path=/uaa_ssl/ca)"- Set alias and then login
bosh alias-env vbox -e 192.168.50.6
bosh env # Just to test your success #
bosh loginNote: As all necessary environment variables are pre-set on the previous step, bosh login may not be needed.
Now, it is Cloud Foundry deployment time. Let's give it a run in few steps:
- Download and update Cloud Foundry
cd ..
git clone https://github.com/cloudfoundry/cf-deployment.git
cd cf-deployment
bosh update-cloud-config iaas-support/bosh-lite/cloud-config.yml
bosh update-runtime-config ../bosh-deployment/runtime-configs/dns.yml --name dns- Upload a stemcell
Before BOSH can deploy your Cloud Foundry Application Runtime, it needs a base VM image to start with. In the BOSH ecosystem, these images are called stemcells.
export STEMCELL_VERSION=$(bosh int cf-deployment.yml --path=/stemcells/alias=default/version)
bosh upload-stemcell https://bosh.io/d/stemcells/bosh-warden-boshlite-ubuntu-xenial-go_agent?v=${STEMCELL_VERSION}- Deploy Cloud Foundry on BOSH
export BOSH_DEPLOYMENT=cf
# export SYSTEM_DOMAIN=bosh-lite.com # No need #
bosh deploy cf-deployment.yml -o operations/bosh-lite.yml -v system_domain=bosh-lite.com
cd ..Note: deploy may take a while. If compilation time is a concern, then add this option -o operations/use-compiled-releases.yml.
- Login with
cf loginand create your own local space
export CF_ADMIN_PASSWORD=`credhub get -n /bosh-lite/cf/cf_admin_password -q`
cf api https://api.bosh-lite.com --skip-ssl-validation
cf login -u admin -p $CF_ADMIN_PASSWORD -o system
cf create-space local && cf target -s localWell done. Congratulations! You're in. 😄
$ cf target
api endpoint: https://api.bosh-lite.com
api version: 2.128.0
user: admin
org: system
space: local
Where do we go from here? Well, let's install a sample app, for instance the CF WebUI. As its authors at ICCLab would put it:
CF WebUI is a modern single-page web front-end for Cloud Foundry based on AngularJS and Bootstrap.
So let's push it.
- Getting started
git clone https://github.com/icclab/cf-webui.git
cd cf-webui- Change manifest.yml accordingly
applications:
- name: cf-webui
memory: 128M
host: console
path: ./build
buildpack: https://github.com/cloudfoundry/staticfile-buildpack
API_ENDPOINT: https://api.bosh-lite.com
# Use Google DNS by default
NGINX_RESOLVER: 8.8.8.8
#Enforce https is used (using x_forwarded_proto check). Default: enabled
FORCE_HTTPS: 1Note: host and API_ENDPOINT need to reflect your deploymnet. In this case they are set to console and https://api.bosh-lite.com, respectively.
- Install
npmpackages
brew install npm
npm install
- Build the app with
grunt
brew install grunt
grunt build
- Push the app
cf push
cd ..
- Enjoy using CF WebUI!
Fire up your favourite browser and go to https://console.bosh-lite.com.
The username is admin, whereas the password is the output of echo $CF_ADMIN_PASSWORD.
And now what? Well, there are many ways to enjoy your local Cloud Foundry meal 🍲. One of those is obviously to push your apps. As a developer you have for sure a couple of ideas in mind by now. If instead you just would like to try something out, then have a look at these links:
- Cloud Foundry Sample Applications
- Deploy a Sample Ruby on Rails Application
- Example Service Brokers
- Getting Started Deploying Spring Apps
Besides, there are several areas of research that could be tackled further. For instance:
- Find out how to configure BOSH Lite to accept direct access from the Internet. If so, make sure that the involved DNS server resolves any name under *.<SYSTEM_DOMAIN> (*.bosh-lite.com is taken) and points it at the IP of BOSH Director, which in our case is 192.168.50.6 on the outer side and 10.244.0.34 on the inner one - the router instance.
- Install and configure
bosh-bootloaderin order to gain access to other IaaS resources rather than the local instance. This will allow running BOSH Lite on AWS, GCP or Azure, and in so doing it will make use of remote infrastructure rather than your Mac or PC. That comes at some costs though.
It is a good practice to get acquainted with your newly installed system. For your convenience here follows a table of the most common List commands for the bosh CLI:
Run these commands just for getting to know your system:
bosh vms
bosh instances
bosh deployments
#bosh configs
#bosh disks --orphaned
#bosh environments
#bosh errands
#bosh run-errand smoke-tests
#bosh events
#bosh inspect-release diego/2.24.0 # (inspect-release requires args `NAME/VERSION` #
#bosh inspect-release cf-cli/1.11.0
#bosh locks
#bosh networks --orphaned
#bosh orphaned-vms
#bosh releases
#bosh snapshots
#bosh stemcells
#bosh tasks
#bosh variablesA side note from the provider:
In case VirtualBox VM shuts down or reboots, you will have to re-run
create-envcommand from above with--recreateflag. The containers will be lost after a VM restart, but you can restore your deployment withbosh cckcommand. Alternatively Pause the VM from the VirtualBox UI before shutting down VirtualBox host, or making your computer sleep.
To better get to know your Cloud Foundry, just have a look at the table below:
| Command | Description |
|---|---|
| apps | List all apps in the target space |
| tasks | List tasks of an app |
| stacks | List all stacks |
| marketplace | List available offerings in the marketplace |
| services | List all service instances in the target space |
| service-keys | List keys for a service instance |
| orgs | List all orgs |
| spaces | List all spaces in an org |
| domains | List domains in the target org |
| router-groups | List router groups |
| routes | List all routes in the current space or the current organization |
| network-policies | List direct network traffic policies |
| buildpacks | List all buildpacks |
| quotas | List available usage quotas |
| space-quotas | List available space resource quotas |
| service-auth-tokens | List service auth tokens |
| service-brokers | List service brokers |
| service-access | List service access settings |
| security-groups | List all security groups |
| staging-security-groups | List security groups in the staging set for applications |
| running-security-groups | List security groups in the set of security groups for running applications |
| isolation-segments | List all isolation segments |
| list-plugin-repos | List all the added plugin repositories |
| repo-plugins | List all available plugins in specified repository or in all added repositories |
| plugins | List commands of installed plugins |
| v3-apps | List all apps in the target space |
| v3-droplets | List droplets of an app |
| v3-packages | List packages of an app |
You can find out more of your cf-depoyment with some of these listing commands:
cf apps
cf stacks
cf orgs
cf spaces
cf domains
cf router-groups
cf routes
cf buildpacks
cf security-groups
cf isolation-segments
cf list-plugin-repos
cf repo-plugins
cf v3-apps
#cf marketplace
#cf services
#cf org-users system
#cf network-policies
#cf space-quotas
#cf service-auth-tokens
#cf service-brokers
#cf service-access
#cf pluginsSource:
- Cloud Foundry BOSH, VirtualBox (2018) https://bosh.io/docs/bosh-lite
- Deploying Cloud Foundry with
cf-deployment(2018) https://docs.cloudfoundry.org/deploying/cf-deployment - CF-WebUI (2015) https://icclab.github.io/cf-webui
References / Acknowledgments:
[1] Iryna Shustava, et al.: Deploying CF (2018)
https://github.com/cloudfoundry/cf-deployment/blob/master/deployment-guide.md
[2] Nic Williams & Jelle vd Kooij: Ultimate Guide to BOSH, bosh-lite on VirtualBox (2018) https://ultimateguidetobosh.com/tutorials/bosh-lite-virtualbox
[3] Lidia Fernández Garcés, et al.: Announcing CF WebUI – an open source web interface to Cloud Foundry (2015) https://blog.zhaw.ch/icclab/announcing-cf-webui-an-open-source-web-interface-to-cloud-foundry
[4] Peter Pilgrim: How to deploy BOSH-Lite and Cloud Foundry locally on Mac Book Pro (2018) http://www.xenonique.co.uk/blog/2018/01/19/how-to-deploy-bosh-lite-and-cloud-foundry-locally-on-mac-book-pro
About the author:
Della Porta is fascinated by computer sciences, distributed systems and cloud technologies.
