Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 311 lines (221 sloc) 10.033 kb
77abf5a @therubymug Fix README
therubymug authored
1 VMware's Cloud Application Platform
2 ===================================
3
4 Copyright (c) 2009-2011 VMware, Inc.
5
6 What is Cloud Foundry?
7 ----------------------
8
9 Cloud Foundry is an open platform-as-a-service (PaaS). The system supports
10 multiple frameworks, multiple application infrastructure services and
11 deployment to multiple clouds.
12
13 License
14 -------
15
16 Cloud Foundry uses the Apache 2 license. See LICENSE for details.
17
18 Installation Notes
19 ------------------
20
21 Cloud Foundry is made up of a number of system components (cloud controller,
22 health manager, dea, router, etc.). These components can run co-located in a
23 single vm/single os or can be spread across several machines/vm's.
24
25 For development purposes, the preferred environment is to run all of the core
26 components within a single vm and then interact with the system from outside of
27 the vm via an ssh tunnel. The pre-defined domain *.vcap.me maps to local host,
28 so when you use this setup, the end result is that your development environment
29 is available at [http://api.vcap.me](http://api.vcap.me).
30
31 For large scale or multi-vm deployments, the system is flexible enough to allow
32 you to place system components on multiple vm's, run multiple nodes of a given
33 type (e.g., 8 routers, 4 cloud controllers, etc.)
34
35 The detailed install instructions below walk you through the install process
36 for a single vm installation.
37
38 Versions of these instructions have been used for production deployments, and
39 for our own development purposes. many of us develop on mac laptops, so some
40 additional instructions for this environment have been included.
41
42 Detailed Install/Run Instructions:
43 ----------------------------------
44
45 There are two methods for installing VCAP. One is a manual process, which you
46 might choose to do if you want to understand the details of what goes into
47 a bringing up a VCAP instance. The other is an automated process contributed
48 by the community. In both cases, you need to start with a stock Ubuntu
49 server VM.
50
51 ### step -1:
52
53 * setup a VM with a pristine Ubuntu 10.04.2 server 64bit image,
54 [download here](http://www.ubuntu.com/business/get-ubuntu/download)
55 * you may wish to snapshot your VM now in case things go pear shaped.
56 * great snapshot spots are here and after step 4
57 * to enable remote access (more fun than using the console), install ssh.
58
0d64ea3 @nextmat Force ssh install instructions to display as a code block.
nextmat authored
59 To install ssh:
60
61 sudo apt-get install openssh-server
77abf5a @therubymug Fix README
therubymug authored
62
63 ### Automated Setup (experimental):
64
65 #### Step 0:
66 Run the install script. It'll ask for your sudo password at the
67 beginning and towards the end. The entire process takes ~1 hour, so just
68 keep a loose eye on it.
69
1a03d19 Slight readme update regarding when it is necessary to install curl
pbozeman authored
70 sudo apt-get install curl
77abf5a @therubymug Fix README
therubymug authored
71 bash < <(curl -s -k -B https://github.com/cloudfoundry/vcap/raw/master/setup/install)
72
4e5835a document workaround for initial ./vcap start issue
pbozeman authored
73 NOTE: if you have issues with 'vmc target api.vcap.me' after using the
74 automated installer, exit out of the shell you did the install in, open
75 a new shell, and perform the following operations:
76
77 cd ~/cloudfoundry/vcap
78 bin/vcap stop
79 bin/vcap start
80
77abf5a @therubymug Fix README
therubymug authored
81 Jump to step 9 in the manual process to optionally setup an ssh tunnel
82 and test your installation.
83
84 ### Manual Setup:
85
86 #### step 0: install system and rvm dependencies
87
88 sudo apt-get install autoconf curl git-core ruby bison build-essential zlib1g-dev libssl-dev libreadline5-dev
89
90 #### step 1: install rvm
91
92 For detailed rvm install instructions see: [https://rvm.beginrescueend.com/rvm/install/](https://rvm.beginrescueend.com/rvm/install/) or follow the quick steps below.
93
94 Install rvm using their script. Note: the -k
95 switch is only needed if the certificate validation fails:
96
97 bash < <(curl -s -k -B https://rvm.beginrescueend.com/install/rvm)
98
99 Follow the instructions given by the RVM
100 installer (a copy is included below for your convenience).
101
102 # you must complete the install by loading RVM in new shells.
103 #
104 #
105 # 1) Place the folowing line at the end of your shell's loading files
106 # (.bashrc or .bash_profile for bash and .zshrc for zsh),
107 # after all PATH/variable settings:
108 #
109 # # This loads RVM into a shell session.
110 # [[ -s \"$rvm_path/scripts/rvm\" ]] && source \"$rvm_path/scripts/rvm\"
111 #
112 # You only need to add this line the first time you install rvm.
113 #
114 # 2) Ensure that there is no 'return' from inside the ~/.bashrc file,
115 # otherwise rvm may be prevented from working properly.
116 #
117 # This means that if you see something like:
118 #
119 # '[ -z \"\$PS1\" ] && return'
120 #
121 # then you change this line to:
122 #
123 # if [[ -n \"\$PS1\" ]] ; then
124 #
125 # # ... original content that was below the '&& return' line ...
126 #
127 # fi # <= be sure to close the if at the end of the .bashrc.
128 #
129 # # this is a good place to source rvm
130 # [[ -s \"$rvm_path/scripts/rvm\" ]] && source \"$rvm_path/scripts/rvm\"
131 #
132 # <EOF> - this marks the end of the .bashrc
133 #
134 # Be absolutely *sure* to REMOVE the '&& return'.
135 #
136 # If you wish to DRY up your config you can 'source ~/.bashrc' at the
137 # bottom of your .bash_profile.
138 #
139 # Placing all non-interactive (non login) items in the .bashrc,
140 # including the 'source' line above and any environment settings.
141 #
142 # 3) CLOSE THIS SHELL and open a new one in order to use rvm.
143
144
145 #### step 2: use rvm to install ruby 1.9.2 and make it default
146
147 rvm install 1.9.2-p180
148 rvm --default 1.9.2-p180
149
150 #### step 3: use rvm to install ruby 1.8.7
151
152 rvm install 1.8.7
153
154 #### step 4: clone the vcap and vmc repos:
155
156 Optionally create new ssh keys and add them to your github account:
157
158 ssh-keygen -t rsa -C me@example.com
159
160 Note, this release uses a handful of submodules. It's important to
161 understand the impact of this which is that after cloning the vcap
162 repo, you must run: `git submodule update --init`
163
164 This ends up mounting the services and tests repos in the directory tree of vcap.
165 Any time you git pull in vcap, you must also git submodule update
166
167 mkdir ~/cloudfoundry; cd ~/cloudfoundry
168 git clone https://github.com/cloudfoundry/vcap.git
169
170 Note, there should be a .rvmrc file in the ~/cloudfoundry/vcap directory.
171 Make sure that the vcap/.rvmrc is present and that it contains rvm use 1.9.2
172
173 cd ~/cloudfoundry/vcap
174 git submodule update --init
175 gem install vmc --no-rdoc --no-ri
176
177 #### step 5: run vcap_setup to prep cloudfoundry for launch
178
179 Points to keep in mind:
180
181 1). Answer Y to all questions
182
183 2). Remember your mysql password, you will need it in a minute
184
185 cd ~/cloudfoundry/vcap
186 sudo setup/vcap_setup
187
188 After vcap_setup completes, edit your mysql_node config file
189 with the correct password created during install
190
191 cd ~/cloudfoundry/vcap/services/mysql/config
192 vi mysql_node.yml and change mysql.pass to your password
193
194 #### step 6: restart nginx with a custom config
195
196 cd ~/cloudfoundry/vcap
197 sudo cp setup/simple.nginx.conf /etc/nginx/nginx.conf
198 sudo /etc/init.d/nginx restart
199
200 #### step 7: install bundler gem and run bundler:install
201
202 cd ~/cloudfoundry/vcap
203 gem install bundler --no-rdoc --no-ri
204 rake bundler:install
205
206 #### step 8: start the system
207
208 cd ~/cloudfoundry/vcap
209 bin/vcap start
210 bin/vcap tail # see aggregate logs
211
212 #### step 9: *Optional, mac users only*, create a local ssh tunnel
213
214 From your vm, run ifconfig and note eth0, let's say it's: 192.168.252.130
215 go to your mac terminal window and create a local port 80 tunnel.
216 Once you do this, from both your mac, and from within the vm, api.vcap.me and *.vcap.me
217 map to localhost which maps to your running cloudfoundry instance
218
219 sudo ssh -L 80:192.168.252.130:80 mhl@192.168.252.130 -N
220
221 Trying your setup
222 -----------------
223
224 ### step 10: validate that you can connect and tests pass
225 #### From the console of your vm, or from your mac (thanks to local tunnel)
226
227 vmc target api.vcap.me
228 vmc info
229
230 #### This should produce roughly the following:
231
232 VMware's Cloud Application Platform
233 For support visit support@cloudfoundry.com
234
235 Target: http://api.vcap.me (v0.999)
236 Client: v0.3.10
237
238 #### Play around as a user, start with:
239 vmc register --email foo@bar.com --passwd password
240 vmc login --email foo@bar.com --passwd password
241
242 #### To see what else you can do try:
243 vmc help
244
245 Testing your setup
246 ------------------
247
248 Once the system is installed, you can run the following command Basic System
249 Validation Tests (BVT) to ensure that major functionality is working.
250
251 cd cloudfoundry/vcap
252 cd tests && bundle package; bundle install && cd ..
253 rake tests
254
255 ### Unit tests can also be run using the following.
256
257 cd cloud_controller
258 rake spec
259 cd ../dea
260 rake spec
261 cd ../router
262 rake spec
263 cd ../health_manager
264 rake spec
265
266 ### step 11: you are done, make sure you can run a simple hello world app.
267
268 Create an empty directory for your test app (lets call it env), and enter it.
269
270 mkdir env && cd env
271
272 Cut and paste the following app into a ruby file (lets say env.rb):
273
274 require 'rubygems'
275 require 'sinatra'
276
277 get '/' do
278 host = ENV['VMC_APP_HOST']
279 port = ENV['VMC_APP_PORT']
280 "<h1>XXXXX Hello from the Cloud! via: #{host}:#{port}</h1>"
281 end
282
283 get '/env' do
284 res = ''
285 ENV.each do |k, v|
286 res << "#{k}: #{v}<br/>"
287 end
288 res
289 end
290
291 #### Create & push a 4 instance version of the test app, like so:
292 vmc push env --instances 4 --mem 64M --url env.vcap.me -n
293
294 #### Test it in the browser:
295
296 [http://env.vcap.me](http://env.vcap.me)
297
298 Note that hitting refresh will show a different port in each refresh reflecting the different active instances
299
300 #### Check the status of your app by running:
301
302 vmc apps
303
304 #### Which should yield the following output:
305
306 +-------------+----+---------+-------------+----------+
307 | Application | # | Health | URLS | Services |
308 +-------------+----+---------+-------------+----------+
309 | env | 1 | RUNNING | env.vcap.me | |
310 +-------------+----+---------+-------------+----------+
Something went wrong with that request. Please try again.