Setting up Chassis

If you do want to set up Chassis to work on projects, here’s how you go about that.

Quick note on terminology: “machine” and “box” both refer to the same thing: a virtual machine running on your computer. The two terms are used interchangeably.

Install Prerequisites Install Prerequisites

Chassis is a local development environment that creates a virtual machine on your computer. It uses two underlying tools that you need to install:

  • VirtualBox – VirtualBox handles the underlying machines.
  • Vagrant – Vagrant manages virtual machines, and provides tools to access them.

Once you’ve installed these, you can then set up your first Chassis box.

Downloading Chassis Downloading Chassis

Each different project you work on will use a new Chassis box, with one-project-per-VM. Chassis is designed to be customisable for your project, so you can set it up to match the production environment (such as WordPress.com VIP, or the Human Made Platform).

You can use Chassis by adding it to an existing project, or by creating a new project from scratch. We’re going to create a brand new project from scratch first, as it’s the simplest way to set up a machine.

To get a copy of Chassis, you need to clone it from git into a directory of your choice. We’re going to clone into a new directory called demo-project:

$ git clone --recursive https://github.com/Chassis/Chassis.git demo-project

This will download Chassis into demo-project, where you can start working from. Feel free to open that directory in your editor if you’d like.

Starting the Box Starting the Box

We then need to start the virtual machine up. The first time you start a Chassis box, it needs to “provision”. This installs all the necessary pieces onto the machine, including PHP and MySQL. This should take less than 5 minutes, but may take longer depending on your internet. To start the machine, we tell Vagrant to “bring the machine up“:

# If you didn't already:
$ cd demo-project/

$ vagrant up

You should see a lot of output here as it boots up, then eventually:

==> ======================================
==> Your Chassis box has been provisioned!
==> ======================================
==>
==> URL: http://vagrant.local/
==> Username: admin
==> Password: password

This shows you the URL to access your brand new WordPress install, and the WordPress username and password to access the Dashboard.

If you’re not using the machine, you can power it down to avoid wasting memory and CPU on your computer. To stop the machine, we tell Vagrant to “halt and catch fire”:

$ vagrant halt

If you’re completely done with the machine, you can save some disk space by removing the box completely. This will delete the virtual machine’s disk, so you’ll lose any data you have saved on the machine. This won’t affect anything you have in code, and you can always recreate the box later. To remove the box’s disk, we tell Vagrant to “destroy the machine”:

$ vagrant destroy

Configuring the Box Configuring the Box

You can set up Chassis how you want, depending on the project you’re working on. To configure it, create a new file in the Chassis directory called config.local.yaml. You can save your settings in here, and they override the defaults set in config.yaml.

After you change anything in your configuration, you’ll need to re-provision the box to update what’s installed and configured:

$ vagrant provision

Hosts Hosts

The key thing you’ll want to change most of the time is the hostname. For example, if you’re working on a project called “Galileo”, you can use galileo.local instead:

hosts:
    - galileo.local

Note: You may need to reboot the machine after changing this. You can do this and re-provision at the same time:

$ vagrant reload --provision

Extensions Extensions

Similar to WordPress, Chassis has a concept of add-on parts, which it calls “extensions”. These are activated by adding them into the extensions/ directory inside Chassis. This can either be done through a git clone, or Chassis can install these automatically for you. As an example, we can install Memcache, which most of our projects use for object caching:

extensions:
    - Chassis/memcache

This will install memcached onto the server, run it, and set the configuration for your WordPress install automatically.

So Much More! So Much More!

Chassis has a tonne of configuration you can set, these are just some common ones. Check out the Chassis documentation for much more about this.

Adding Chassis to an Existing Project Adding Chassis to an Existing Project

Already got a project, but need a virtual machine to run it in? Chassis can handle this too with another configuration option, called paths.

Let’s say we already have a project called existing-project/. This directory contains content for our content, and wordpress with the WordPress install.

The first step is to clone Chassis, but this time into a subdirectory called chassis:

# If you haven't already:
$ cd existing-project/

$ git clone https://github.com/Chassis/Chassis.git chassis

Once you’ve done this, create the config.local.yaml inside the chassis directory. Add your regular hosts configuration if you want to change that, and also set the paths:

hosts:
    - existingproject.local

paths:
    base: ..
    content: content
    wp: wordpress

This tells Chassis: we want to use .. (existing-project/) as our main directory, we want to use the content subdirectory (existing-project/content/) for the content, and we want to use the wordpress subdirectory (existing-project/wordpress/) for the WordPress directory.

Once you’ve done this, you can then use vagrant up for the first time.

If you forget to do this before you bring the machine up, you’ll need to reboot the machine before you re-provision it:

$ vagrant reload --provision