Quinn wrote a guide on how to do exactly this over a year ago, and that can be found here:
https://blog.starkandwayne.com/2014/12/16/running-cloud-foundry-locally-with-bosh-lite/
Cloud Foundry’s process for getting started on bosh-lite evidently has not changed too much over the past year, because Quinn’s guide is still perfectly valid. However, over the past couple days I’ve been spending quite a bit of time learning the ins and outs of this process, and so here I am writing a guide from my perspective that takes a slightly different route getting Cloud Foundry set up than the one Quinn detailed. That said, I believe her way is the easier and quicker of the two. I’ve attempted to take the longer way around with the hopes of understanding – and, in turn, explaining here that understanding – the finer details of what the bosh-lite script that handles most of the deployment process actually does. After all, that script isn’t extremely helpful once you’re trying to take Cloud Foundry off of bosh-lite and… well… into the cloud!
In short, if you’re just looking to get up and going, her guide might be better suited to you. This is just a more "BOSH cli"-oriented method.
Installing Necessary Software
Like most software, what we’re using here has some additional dependencies we need to download for it to work. This section should help get some of those dependencies sorted out. The following three pieces of software can be installed by going to their respective websites and following the instructions found there.
Bosh Command-Line Interface
You’ll also want the Bosh command line interface ("BOSH cli"). This can be installed with the ruby package manager (gem install). However, because of certain dependencies which are required for bosh-lite (a gem called "nokogiri" and what it needs to install), it is important that you have installed the Apple developers tools if you’re running on a Mac. If you have not yet done so, download xcode from the app store, and then use the following command to get the command line dev tools:
$ xcode-select --install
The bosh command line interface should then install problem-free with:
$ gem install bosh_cli
Spinning up a Vagrant Box
After all of the installations are finished, it is time to Vagrant up and running. However, for reasons which will soon become apparent, it’s easier to install bosh-lite first. To install bosh-lite, first navigate to the directory you’d like bosh-lite to be stored in, and then clone it with:
$ git clone https://github.com/cloudfoundry/bosh-lite.git
Now let’s spin up a vm – we’re going to use VirtualBox as the base for a Vagrant vm, so we’ll specify Virtualbox as the provider for the command. Vagrant requires a file named "Vagrantfile" to know how to manipulate the Vagrant box. While we could technically make our own, the benefit to having already downloaded bosh-lite is that the repository already contains a correctly configured Vagrantfile for us.
A note on how Vagrant finds its Vagrantfiles: Vagrant will first search in the current working directory, and then it will move up a directory and look there, and keep recursively moving up until it cannot anymore – that is, when it hits the root directory. Therefore, you could throw it in the root of a project repository and access it from anywhere in the project. For this situation, though, it makes the most sense to just navigate to the directory with the Vagrantfile directly.
Let’s move to the bosh-lite directory that we pulled down and spin up this vagrant box with the "vagrant up" command.
$ cd /path/to/directory/bosh-lite
$ vagrant up --provider=virtualbox
Another note: The Vagrantfile that comes with bosh-lite can alternatively be created by running:
vagrant init cloudfoundry/bosh-lite
Connecting to the Bosh Director
With the bosh command line interface installed, the following bosh command can be used to have bosh target the bosh director. The director is a component of bosh which organizes the creation and deployment of vms, among other things. Long story short, without being able to contact it, you’re not doing much with Bosh:
$ bosh target 192.168.50.4
For reference, the current bosh target can be checked by running the target command without any arguments. If you set yours up correctly, you should see something like this:
$ bosh target
Current target is https://192.168.50.4:25555 (Bosh Lite Director)
bosh-lite actually comes with a utility to route the necessary ip addresses internally to bosh components even if your connection is reset. Because this involves changing the routing tables, you will need superuser privilege to do this. Make sure you are in the bosh-lite directory and execute:
$ sudo bin/add-route
Now we can log into the targeted Bosh Director with:
$ bosh login
You’ll then be prompted for a username and password, both of which are, by default, "admin". This admin account ceases to exist if a new account is created, so be careful not to create the first new account without administrative privileges should you need to make your own. The username and password can alternatively be passed into the login command with the following format, should you prefer it:
$ bosh login admin admin
Uploading a Bosh Stemcell
Now, let’s upload a stemcell to bosh. A stemcell is a preconfigured system image, OS and basic utilities included, that can be used to quickly get vms up and running with bosh. A list of recognized Bosh stemcells can be found at:
https://www.bosh.io/stemcells
For this tutorial, we’re going to use the ubuntu distribution with warden containers. Navigate to the first listing on the page titled Bosh Lite Warden and click on the version number to begin a download (at the time of this writing, the version number is 2776).
After the download is finished, feel free to move it from the Downloads folder to somewhere easier to access. When we go to upload it to bosh, bosh will expect it to be a zipped file (which I believe the initial download actually is, but if you download from the browser, Mac will do you a "favor" and unzip it automatically). If it is not a zipped file, we can zip it with gzip.
$ gzip <filename>
Then we want to upload the stemcell to bosh so that whenever we need to deploy an instance of it, bosh has all the information it needs. To do this, note the name of the zipped stemcell you downloaded and enter:
$ bosh upload stemcell <name-of-stemcell-file> --skip-if-exists
The list of all currently uploaded stemcells can be checked with:
$ bosh stemcells
Deploying Cloud Foundry
Now it is time to pull down the Cloud Foundry release. The git repository for Cloud Foundry can be cloned with:
$ git clone https://github.com/cloudfoundry/cf-release.git
Uploading the Cloud Foundry Release
Then it is time to upload the release to Bosh. The Cloud Foundry release has a folder with yaml files giving the details of each release version. We need to give bosh the release file associated with the version we’re going to want to deploy. At the moment, the newest version of Cloud Foundry is cf-221, so I’ll use that as an example. Let’s move into the cf-release directory that was pulled down and upload this release version:
$ cd /path/to/directory/cf-release
$ bosh upload release releases/cf-221.yml
Creating the Deployment Manifest
The deployment manifest tells Bosh all the information it needs to create an instance of you want it to deploy – in this case, Cloud Foundry. There is actually quite a lot in these manifests – luckily, Cloud Foundry has a utility script to make one for us. Before we can do that, however, we need to update and install all the dependencies required by Cloud Foundry. While in the cf-release directory, call the update script provided in the repository:
$ ./scripts/update
Then, we can create a deployment manifest with a utility in the scripts folder of the cf-release. The manifest will need a little extra information that the script cannot provide on its own, and so we need to supply it to the script in the form of a yaml file that it can merge into its output. So, while in the cf-release directory, create a new file called "local.yml". In that file, make a key called "director_uuid" with a value which is the uuid of your bosh director.
To determine your Bosh Director’s uuid, get some information from Bosh with the following command and look for the uuid row in the output.
$ bosh status
Config
/Users/tom/.bosh_config
Director
Name Bosh Lite Director
URL https://192.168.50.4:25555
Version 1.3074.0 (00000000)
User admin
UUID 9bca5701-66c0-43ee-a4d0-64813b4b5ece
CPI cpi
dns disabled
compiled_package_cache enabled (provider: local)
snapshots disabled
The "local.yml" file you make should look like the example below, except for if your uuid is different, then you’ll need to substitute the given uuid for your own:
---
director_uuid: 9bca5701-66c0-43ee-a4d0-64813b4b5ece
Now that that is saved, we’re going to use another script included with the cloud foundry release to actually create the deployment manifest. This script, however, is reliant on another piece of software called spiff to handle the joining of yaml files.
Installing Spiff
Spiff can be downloaded at:
https://github.com/cloudfoundry-incubator/spiff/releases
At that link, choose the download for your operating system ("Darwin", if you’re on a Mac). This will download the binary for spiff, but your shell needs to be able to find it. You can either move the binary into a folder that is already on your $PATH environment variable, or put it somewhere else and add it to your $PATH.
My method of doing this was to create a new directory in my home directory (/Users/YOUR_NAME_HERE/) called "bin" and move spiff there.
$ cd ~
$ mkdir bin
$ mv ~/Downloads/spiff ~/bin
After it is there, we need to notify the shell that this is a place it should be looking for programs. That means we need to modify the system’s $PATH variable, which if you don’t know, is the listing that the shell goes through when trying to find something. The $PATH, among other environment variables, is initialized when the shell starts up by reading from a few different files. One of the files that the Bash shell (which you’re probably using – if you aren’t, you can Google how to do this with your own shell) looks at is your ~/.profile. Navigate to your home directory and open up this file with your favorite text editor.
Filenames beginning with a period are considered to be hidden files by the Mac OS. Therefore, if you’re trying to find this with the GUI Finder, you might need to find a way to enable viewing of hidden files. For the command line, if you want to see the listing, just use ls -a
Add the following line somewhere in the file, then save and quit:
export PATH="$PATH:$HOME/bin"
After you’ve done that, restart your terminal session and the next time you open it, you should be good to go!
Actually Creating the Deployment Manifest
Once your shell can find spiff, we’re ready to run the script. By default, it just dumps the resulting manifest into standard-output, so for it to be actually useful to us, we can redirect it into a file which we’ll call "deploy.yml". The file could be named anything, but this is a name that makes sense (to me, anyway).
$ ./scripts/generate_deployment_manifest warden local.yml > deploy.yml
The upload command actually gives me a warning about the version of my command line interface, but when it asks if I want to continue anyway, I say yes and everything appears to be fine.
Time to Deploy
We need to tell BOSH where to find the deployment manifest that we made. If you called it deploy.yml and placed it in the cf-release directory as the guide has outlined, then while in the cf-release directory, enter:
$ bosh deployment deploy.yml
Now, everything should be set up appropriately, and you can finally enter:
$ bosh deploy
This command can take quite awhile and eat a considerable amount of battery, so if you’re on a laptop, this would be a good time to plug it in (and find something to read). After awhile of CPU churning, it should finish successfully and you can enter:
$ bosh vms
This will show you all of the vms running cloudfoundry components. In this case, the "vms" are actually warden containers, but BOSH will treat them the same.
And then, with very little fanfare, you’re all set up. Enjoy!
Spread the word
