anchor.diff:  │   └── blobs.yml
   ├── jobs
   ├── packages
  -├── src
  -└── ardo_web
  -
  -6 directories, 1 file
  +└── src
  +
  +5 directories, 1 file
   </pre>
   
  -**Note**: The release directory is where you run all the BOSH commands in this tutorial.
  -
  -## <a id="..."></a> Create the Job Skeletons ##
  -
  -For each piece of software you include in a release, you create a job.
  -
  -When first created, the job is a _skeleton_: an empty structure to be filled up
  +Notice that in the release directory, BOSH creates a subdirectory for each
  +of the fundamental elements: jobs, packages, source (which BOSH calls `src`), and blobs.
  +
  +## <a id="job-skel"></a> Create Job Skeletons ##
  +
  +When first created, the job is a _skeleton_: an empty structure that fills up
   as release creation progresses.
   
  -The example release only includes one job.
  -
  -Generate a job skeleton:
  -
  -  `bosh generate job ardo_web`
  -
  -Naming the job `ardo_web` distinguishes it from the original app.
  -
  -View the job skeleton with `tree`:
  +Generate job skeletons by running this command once for each job in your release:
  +
  +  `bosh generate job <job_name>`
  +
  +In our example, we run `bosh generate job` twice, once for the `web_ui` job,
  +and once for the `bg_worker` job.
  +
  +View the job skeletons with `tree`:
   
   <pre class="terminal">
  -$ tree jobs/ardo_web/
  -jobs/ardo_web/
  -├── monit
  -├── spec
  -└── templates
  -
  -1 directory, 2 files
  +$ tree .
  +.
  +├── blobs
  +├── config
  +│   └── blobs.yml
  +├── jobs
  +│   ├── bg_worker
  +│   │   ├── monit
  +│   │   ├── spec
  +│   │   └── templates
  +│   └── web_ui
  +│       ├── monit
  +│       ├── spec
  +│       └── templates
  +├── packages
  +└── src
  +
  +9 directories, 5 files
   </pre>
   
  -### <a id="..."></a> Create control script for the jobs  ###
  -
  -Every deployed app must have a way to start and stop.
  -You provide that in a BOSH release by writing a control script that
  -includes a start command and a stop command.
  -The script is an ERB template stored in the `templates` directory for the relevant job.
  -At compile time, BOSH transforms templates into files which
  -eventually reside on the VMs where the deployed software runs.
  -
  -In production situations, start and stop commands can be required to turn more things on and off
  +### <a id="control"></a> Create control scripts for the jobs  ###
  +
  +Every deployed app needs a way to start and stop.
  +You provide that in a BOSH release by writing a control script for each job.
  +
  +The control script:
  +
  +* Includes a start command and a stop command.
  +* Is an ERb template stored in the `templates` directory for the relevant job.
  +
  +At compile time, BOSH transforms templates into files, which it then replicates on
  +VMs where the deployed software runs.
  +
  +In production situations, start and stop commands typically turn more things on and off
   than the simple commands in our example do.
  -Control scripts can be the source of unexpected behavior that you discover while testing your dev releases.
  +Control scripts can be the source of unexpected behavior that you discover as you test your dev releases.
   When that happens, you refine your scripts and iterate.
   For these reasons, writing scripts is typically one of the heavier tasks entailed in creating a release.
   
  -Create the control script and save it as `ctl.erb` in the `templates` directory.
  -
  -### <a id="..."></a> Update the job specs  ###
  -
  -The `spec` file is where metadata about your job resides.
  -
  -You now possess two pieces of information which must be recorded in that metadata.
  -
  -1. When the software is deployed, the `ctl.erb` template should become
  -a file on the VM.
  -Its path on the VM should `bin/ctl`.
  -
  -1. Since there is an `ardo_web` job, you know that an `ardo_web` package must be created
  -sooner or later.
  -
  -In the `spec` file, edit the `templates` and `packages` blocks to reflect this information:
  +For each job, create a control script and save it as `ctl.erb` in the `templates` directory for its job.
  +
  +_insert ctl.erb as a snippet here? for one job or both?_
  +
  +If your release needs templates other than the control script, create them now.
  +
  +### <a id="job-specs"></a> Update job specs  ###
  +
  +Metadata for each job resides in a `spec` file.
  +
  +Two kinds of information which you now possess must be recorded in that metadata.
  +
  +1. **Job names.**
  +For each job you have created, list a package of the same name
  +in the `packages` block of the `spec` file for the job.
  +You can now and create the actual package later.
  +The package will be needed to provide source code and dependencies to the job.
  +
  +1. **Template names**.
  +List each template you have created in the `templates` block of the `spec`
  +file for its job.
  +At compile time, BOSH makes templates into files on VMs.
  +List the template and the path to the corresponding file as a key/value pair.
  +
  +Update the `spec` files for all the jobs in your release with the relevant job names and
  +template names.
  +
  +In our example, we edit the `spec` files for the both the `web_ui` and `bg_worker` jobs.
  +The updated `spec` file for the `bg_worker` job looks like this:
   
   ~~~yaml
   
  
positive.code: 
  _add examples inline_
  
  ### <a id="..."></a> Add Blobs Locally ###
  
  When creating a release, use Git for your source code.
  Since Git is not well-suited to dealing with large binaries,
  it's a good idea to avoid checking blobs into Git.
  
  Instead:
  
  * Add blobs to a local blobstore while creating
  dev releases.
  * Upload blobs to a public blobstore before you create a final release.
  
  Normally, all the binaries you record in your packaging specs should be added to a local blobstore.
  
  ### <a id="..."></a> Create a local blobstore  ###
  
  The `config` directory (of which there is only one per release) is where you record the information
  BOSH needs to create a local blobstore and pull in the proper binaries.
  
  * The `final.yml` file names the blobstore and declares that it is local.
  * The `private.yml` file specifies the path of the blobstore, along with a secret.
  
  The `config` directory also contains two files whose content is automatically generated:
  the `blobs.yml` file and the `dev.yml` file.
  
  Adapt the example `final.yml` and `private.yml` files to fit the specifics of your release.
  
  _insert examples_
  
  Note that `final.yml` and `private.yml` essentially divide up a small amount of content.
  At some point in the release creation process, `private.yml` may contain keys.
  For that reason, it is automatically gitignored (assuming you used the `--git` option when
  running `git init release` at the beginning of this tutorial), so its contents truly
  remain private in that they are not checked into Git.
  
  The "secret" in the example `private.yml` file is "does not matter."
  The reason is that the `secret` line, while required, is deprecated, so its content actually
  does not matter.
  
  ### <a id="..."></a> Add blobs to blobstore ###
  
  For each blob, run:
  
  `bosh add blob <path> <package_name_as_prefix>`
  
  You construct this command by taking the same information found in the spec for each package in the
  `packages` directory.
  
  For example, in `packages/libyaml_0.1.4/spec`, you find:
  
  ~~~yaml
  
  files:
  - libyaml_0.1.4/yaml-0.1.4.tar.gz # From http://pyyaml.org/download/libyaml/yaml-0.1.4.tar.gz
  
  ~~~
  
  To construct the command, just reverse the order of what's in the spec and delete the filename from the prefix:
  
  `bosh add blob http://pyyaml.org/download/libyaml/yaml-0.1.4.tar.gz libyaml_0.1.4`
  
  
  ## <a id="..."></a> Update Specs ##
  
  ### <a id="..."></a> Add blob to dependency spec ###
  
  * libyaml spec needs to know about libyml blob
  * BOSH looks in two locations: `src` and `blobs`
  
  ### <a id="..."></a> Update package spec with dependency information  ###
  
  * Add ruby's dependence on libyaml to Dependencies section of ruby spec
  * satisfies a line in the `packaging` script
  
  ### <a id="..."></a> Update package spec with blobs information ###
  
  * ruby, rubygems, bundler
  * with `ruby_1.9.3` prefix — all part of that package
  * `bosh blobs` to see that they are there and copy filenames
  * paste filenames into the `ruby_1.9.3` spec
  
  
  ## <a id="..."></a> Create Properties  ##
  
  * Properties are inputs ...
  * Coordinating with the `properties` block in the manifest...
  
negative.code: Write your packaging scripts now.
  To get started, study the examples.
  
  * Use your dependency graph to determine which dependencies belong in each
  packaging script.
  
  * Begin each script with a `set -e -x` line.
  This aids debugging at compile time by causing the script to exit immediately if an error occurs.
  
  ### <a id="..."></a> Update packaging specs ###
  
  Within each package directory is a `spec` file which states:
  
  