The first question anyone asks when starting work on an existing application is: “How do I get this running on my machine?” The answer to this is different for every app and technology, but the frustrations that arise on a regular basis are the same everywhere. How many of these sound familiar?

• There’s no documentation and the app doesn’t work. What do I need to do?
• I followed the documentation, but now I’m getting this error?
• The documentation references files that don’t seem to exist anymore.
• What other software do I need to install for this app to run?

Getting your app up and running on a new developer’s machine should not be a difficult chore. Outside of minor details like a developer’s choice in database names or user accounts, this process can and should be scripted.

In fact, if your app is using a Continuous Integration tool like Travis CI, CircleCI, or a local install like Jenkins, you’ve already done this because the app has to work for the tests to pass. Let’s move the CI setup steps to a location that any developer can run locally.

At Collective Idea, we use Travis CI extensively. Our .travis.yml files often look like the following:

language: ruby
before_script:
  - cp config/mongo.yml.example config/mongo.yml
  - cp config/resque.yml.example config/resque.yml
  - cp config/secrets.yml.example config/secrets.yml
...

Instead of coding these steps only for Travis, lets build a local bin/bootstrap file and reference that file in Travis instead.

language: ruby
before_script: 
  - sh bin/bootstrap
...

A good bootstrap script meets the following criteria:

1. Minimal dependencies. Try to write these in a language that is guaranteed to exist on the developer’s machine. A bootstrap file that itself can’t run because of missing software misses the point.
2. Idempotentcy. The script should be safe to run as many times as you want without clobbering itself or causing problems.
3. Informative. Tell the user what’s going on so they know it ran correctly or not.
4. Give good, clear instruction for steps that can’t or shouldn’t be run automatically. Sometimes the configuration is up to the developer, e.g. how the developer manages versions of Ruby (rvm, rbenv, chruby, etc).

With these rules in mind, what do we need to do in our bootstrap file?

• Ensure the language of choice is installed (in our case, Ruby)
• Copy over example configuration files
• Install dependencies
• Set up and possibly seed the database

I’ve provided a sample bootstrap script, written in Bash, that includes examples of all of these steps:

Now, when the application has another setup dependency, you’re required to update the bootstrap script to ensure CI runs successfully, while also reducing the burden of new machine and new developer setup.

Rails 4.2

If you’re running an application under Rails 4.2, there’s a new convention available: bin/setup. This script is generated with any rails new application using 4.2 or later, and includes most of the steps you would need for any typical Rails application.