The core of Chassis is designed around you having everything needed for your
site-specific code in the
content/ directory. This includes project-specific
configuration (we load
content/config.php in during
loading) and your plugins and themes. This is designed such that you can keep
your site self-contained in a separate repository, including API keys and such.
We also load 4 configuration files, allowing you to store project-specific configuration while still allowing overriding:
project/content/config.local.yaml- project-specific overrides
project/content/config.yaml- project-specific defaults
project/config.local.yaml- global overrides
project/config.yaml- global defaults
This allows you to (e.g.) enable multisite for the entire project, while allowing specific users to override the hostname if it conflicts with existing projects.
Changing your Chassis box is a quick two-step process:
- Change the relevant configuration file as above and save
vagrant provision tells Vagrant to update the box with your new settings,
and should take care of updating everything internally.
WordPress developers will often require customisation of optional constants that are defined in
We discourage editing
wp-config.php in Chassis as we have an optional php file
local-config.php which can
contain custom constants and overrides for WordPress.
local-config.php exists it will be loaded before
wp-config.php so any constants that you define in
local-config.php will be the defaults.
PHP 5.6 is included with Chassis by default, plus we register the additional repositories for the other versions. We don’t download them all automatically, to avoid extra download times, but switching is still pretty fast as we pre-register the APT repositories.
To switch to 5.3 for example:
You can use either a two-part version (
5.3) or a three-part version
5.3.1) if you want to pick specifc versions. We support any version between
5.3.0 and 5.6.x.
There are a few known issues on Windows with PHP 5.4.
Chassis also includes the latest-released version of WordPress by default, but we also allow swapping this out completely for users who want the flexibility. Our built-in version follows the pattern laid out by WordPress Skeleton, however you can change this easily if you want.
For example, to swap out the current version of WordPress for the latest development version:
wpdir: wp-trunkto your
We want to make this as flexible as possible, without forcing you to run through any of these steps if you don’t need to.
If you’re forking Chassis and want to maintain it yourself, you’ll need to keep your copy of WP up-to-date as well. We recommend merging Chassis changes back to your forked version, but you can also do it yourself:
# To update to WP 4.2.1, e.g: bash puppet/update-wp.sh 4.2.1
Chassis includes built-in support for WordPress multisite, with both subdirectories and subdomains. This is turned off by default, but can be turned on easily.
- For multisite in subdirectories, set
- For multisite on subdomains, set
Then just reprovision.
When multisite is turned on, Chassis will set up WordPress in “subdirectory”
mode; that is, sites will be created under the root, but using the same domain.
A site called “test” would be created at
/test/, for example.
Subdirectory mode is great, but subdomain mode is even better. With subdomains,
a site called “test” would be available at
test.vagrant.local. This is one of
the most common ways that multisite is set up, since it also means you’re
separating your sites more cleanly. Simply set the value to
reprovision. Once this is done, subdomains will work automatically in your
browser. Create and remove sites at will, and Chassis will ensure it just works.
Changing from multisite back to single site requires creating the box from
vagrant destroy before running
vagrant up. This is due
to WordPress’ inability to switch back.
This will wipe your database, so make sure you export any sites’ content that you need (via the WordPress exporter).
When you first set up your site, Chassis will install WordPress and create the default admin user for you. By default, this user is set up as admin with the password password to keep it simple for local development.
To change this, simply set the
admin configuration option to different
values, like so:
admin: user: admin email: email@example.com password: password
You must include all lines shown above (albeit with your custom configuration), even if you’re not changing from the default.
Changing the default admin requires creating the box from scratch, using vagrant destroy before running vagrant up.
Note also that the indentation must be done with spaces, not tabs in YAML configuration.
Similar to the admin user configuration, you can also override the default MySQL username and password:
database: name: wordpress user: wordpress password: vagrantpassword
(Again, don’t forget to include all lines, and use spaces for indentation.)
Custom Host Names¶
By default, Chassis will set up
vagrant.local as your main domain. If you’d
like to change this, you can override the
hosts configuration item. Note
that this is a list, so it should have list items in the following format:
hosts: - vagrant.local - althost.local
The first host here will be set as the main host for the box and in WordPress. Subsequent hosts will be set as aliases of the main domain using nginx, and may be redirected by WordPress depending on your configuration or plugins.
Domains ending in something other than .local won’t have DNS set up for them automatically, so make sure to add these to your hosts file on your computer (not inside the virtual machine).
If you need to find out the IP address of your machine, run
to connect, then inside the box run
ifconfig eth1 and look for the line
Chassis picks an IP address for your box automatically, using DHCP. If you’d
prefer a static IP, you can specify this here with
(Typically, this should be in the private routing range; either
To speed up package installation, Chassis can tell Ubuntu to use the closest
mirror to you, rather than the main mirror (
ubuntu.com). This typically
speeds up installation by decreasing latency, however it may cause slowness with
some slower or badly-behaving mirrors.
You can tell Chassis to do this by setting
If you have a specific mirror you’d like to use, you can set this as the value instead, such as:
By default Chassis syncs the
nginx logs for you onto your local machine in the
You may want to keep your themes and projects along-side Chassis, instead of inside it. You’ll need to tell Chassis about these external directories, as it won’t know how to map them. You can tell Chassis to map some external directories into the generated VM like so:
synced_folders: a/host/directory: a/vm/directory "this:ones:got:colons": another/vm/directory
If you’re transplanting Chassis into an existing project, you can manually set some paths manually. These can be set to absolute paths, or relative paths.
paths: base: . wp: wordpress content: wordpress/wp-content
If you’re using plugins from the WordPress.org repository you can add them in a list using the plugins slug. These will be downloaded, installed and activated for you.
To find the slug just copy and paste the plugins slug from your browsers. For example the URL for Query Monitor is https://wordpress.org/plugins/query-monitor/ which makes the slug
plugins: - query-monitor - user-switching
If you’re using themes from the WordPress.org repository you can add them in a list using the themes slug. These will be downloaded for you. The last theme in the list will be the theme that is activated for your site.
To find the slug just copy and paste the plugins slug from your browsers. For example the URL for Twenty Sixteen is https://wordpress.org/themes/twentysixteen/ which makes the slug
themes: - twentyfifteen - twentysixteen
You can enable official Chassis extensions and third party extensions by listing their repo name in the
extensions: - Chassis/Tester - javorszky/chassis-openssl