How to Install Cloud Foundry Locally by Using Vagrant

by Gastón RamosJune 28, 2013

Find the detailed instructions and examples to deploy a simple Ruby / Sinatra web app on a local Cloud Foundry instance in under 30 mins.

Table of Contents

Why local deployment?

By default, Cloud Foundry is a highly distributed multi-tenant platform that is usually deployed at scale (>40 nodes) on top of existing virtualized infrastructure (e.g., VMware’s vSphere or vCloud, Amazon AWS, or OpenStack). For a novice Cloud Foundry developer, a full scale PaaS deployment isn’t always an affordable choice for testing or development. Two options exist to address this issue.

First, the Cloud Foundry team released Micro Cloud Foundry as a virtual machine image that could be run on a laptop. Micro Cloud Foundry behaves more like a production cloud and provides developers with a sandbox to play with. Second, an alternative to using Micro Cloud Foundry on a virtual machine, is to install Cloud Foundry natively on a development toolbox such as Vagrant.

To simplify a start, we prepared an article, “Installing Cloud Foundry on Vagrant,” for the Pivotal blog. The tutorial describes how to install the tool, start / stop Cloud Foundry components, work with custom configuration files, etc. Here’s its updated version.

Cloud Foundry Vagrant Installer

Vagrant is actually a developer’s VM toolbox, as it provides an easy way to create and configure lightweight, reproducible, and portable development environments. It sits on top of a virtualization layer such as Virtualbox, VMware Fusion or VMware Workstation. The VM definition and configuration file (Vagrantfile) is part of the versioned source code repository.

To ease the deployment process for DevOps engineers, Altoros has released Cloud Foundry Vagrant Installer.

The Cloud Foundry deployment on Vagrant is a self-contained partial Cloud Foundry v2 installation which runs inside a Vagrant-managed VM with Ubuntu 12.04.2 LTS. To get started, you need to download and install Vagrant. After that, just follow the step by step directions for deploying the Cloud Foundry Vagrant Installer on GitHub.

You should be able to set up and configure everything in under 30 minutes, and easily push a simple Ruby Sinatra web application on the local Cloud Foundry PaaS.

Installation

Vagrant allows you to run Chef recipes after booting up the VM (these are located under the chef directory). Every time you bring up a VM (vagrant up), it will check the Chef folder and determine if any recipes should be run. The first time the Vagrant image is started, it will take some time to install all of the required packages.

The number of Chef recipes may be limited, so be sure to use Berkshelf to manage your cookbooks or their dependencies. Berkshelf maintains proven and stable recipes downloaded from OpsCode. Big thanks to Scott Frederick who provided the contribution of Berkshelf support!

Starting and stopping Cloud Foundry components

There are two main ways to start or stop the Cloud Foundry components. Most operators prefer to use start.sh and stop.sh, which are bash scripts that launch upstart commands to run the components.

$ cd /vagrant
$ ./start.sh
cf-ng start/running

# Verify  running processes
$ ps ax
11733 ?        S      0:00 /bin/bash ./bin/file_server
11734 ?        S      0:00 /bin/bash ./bin/dea_ng
11739 ?        Sl     0:00 ruby spec/bin/file_server.rb
11745 ?        S      0:00 /bin/bash ./bin/dir_server
11750 ?        Sl     0:00 ruby /home/vagrant/.rbenv/versions/1.9.3-p392/bin/nats-server
11752 ?        Sl     0:01 ruby bin/dea config/dea.yml
11759 ?        S      0:00 /bin/bash ./bin/warden
11766 ?        Sl     0:00 ruby /home/vagrant/.rbenv/versions/1.9.3-p392/bin/rake dir_server:run
11793 ?        S      0:00 bash /home/vagrant/.rbenv/plugins/rbenv-sudo/bin/rbenv-sudo bundle exec rake warden:start[config/test_vm.yml]
11842 ?        S      0:00 /bin/bash ./bin/health_manager
11852 ?        S      0:00 /bin/bash ./bin/gorouter
11861 ?        S      0:00 /bin/bash ./bin/cloud_controller
11865 ?        Sl     0:00 ruby ./bin/health_manager
11866 ?        S      0:00 sudo env PATH=/home/vagrant/.rbenv/shims:/home/vagrant/.rbenv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin bundle exec rake warden:start[config/test_vm.yml]
11877 ?        S      0:00 sudo ./bin/router -c=config/gorouter.yml
11878 ?        Sl     0:00 ruby /home/vagrant/.rbenv/versions/1.9.3/bin/rake warden:start[config/test_vm.yml]
11896 ?        Sl     0:00 ./bin/router -c=config/gorouter.yml
11946 ?        S      0:00 /bin/bash ./bin/uaa
11951 ?        Sl     0:29 /usr/lib/jvm/default-java/bin/java -classpath /usr/share/maven/boot/plexus-classworlds-2.x.jar -Dclassworlds.conf=/usr/share/maven/bin/m2.conf -Dmaven.home=/usr/share/maven org
12012 ?        Sl     0:00 go/bin/runner -conf config/dea.yml
12103 ?        Sl     0:02 ruby bin/cloud_controller -m

An alternate method is to use Foreman to declare the processes required to run your application in a single file: Procfile. Foreman is a useful Ruby gem that allows you to run several processes with only one command (foreman start). Foreman will start and the display the stdout and stderr of each process—this is useful because you can see all the logs in one terminal with different colors for each process. The scripts below were generated using Foreman (via foreman export).

Our Procfile:

nats: nats-server
warden: ./bin/warden
uaa: ./bin/uaa
dir_server: ./bin/dir_server
file_server: ./bin/file_server
dea_ng: ./bin/dea_ng
gorouter: ./bin/gorouter
cc_ng: ./bin/cloud_controller
health_manager: ./bin/health_manager

Foreman output (colored):

Custom config files

Vagrant uses the Cloud Foundry source code, downloaded directly from the corresponding GitHub repository for each module (CCNG, Router, NATS, DEA, etc.). The .gitmodules file contains configuration details that can be customized or adapted for local installation onto Vagrant. The following are a few examples of different customizations for local Cloud Foundry deployments.

To add logging and increase the verbosity of the logging stream:

logging:
  file: /vagrant/logs/cloud_controller.log
  level: debug2

To make a database persistent after VM shutdown, configure it in the corresponding custom_config_files/cloud_controller_ng/cloud_controller.yml file.

db:
  database: "sqlite:///vagrant/db/cloud_controller.db"

To set vcap.me as a default domain, which is pointed to localhost, describe it in cloud_controller.yml:

system_domain_organization: vcap.me
system_domain: vcap.me
external_domain:
  - api2.vcap.me
app_domains:
  - vcap.me

There are more examples and detailed changes recommended to the configuration files in Vagrant Installer’s documentation.

Building a virtual machine

We won’t duplicate the instructions to build the Cloud Foundry virtual machine in this blog post. Just follow the step-by-step instructions provided and you’ll have a Cloud Foundry v2 instance in a matter of minutes.

Cloud Foundry on Vagrant is a great tool for learning about the inner workings of the platform and its various components. Feel free to leave us feedback on your experience deploying Cloud Foundry on Vagrant and be sure to check back frequently for updates and improvements on the GitHub project.