Configuration¶

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 wp-config.php 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 5 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
~/.chassis/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
Run vagrant provision

vagrant provision tells Vagrant to update the box with your new settings, and should take care of updating everything internally.

Base Box Mode¶

By default, we use a box built with the default settings. This speeds up initial provisioning time and reduces disk usage by sharing the common parts of the VM.

The normal box will use the Chassis box that we’ve built and uploaded to Vagrant Cloud which uses PHP 7.4.

To create a customised base box for your project you could have create a config.local.yaml file as follows:

hosts:
    - client.local

# PHP version
php: 7.2

# Maximum file upload size. This will set post_max_size and upload_max_filesize in PHP and client_max_body_size in Nginx.
upload_size: 512M

# Values: normal, base, custom
_mode: base

extensions:
    - chassis/mailhog
    - chassis/xdebug
    - chassis/tester
    - chassis/sequelpro

If you have your own box in Vagrant Cloud or you wish to use another vendors Vagrant Cloud box then you can use a custom box in your config.local.yaml:

# Values: normal, base, custom
_mode: custom

# The box you'd like to use.
box: bento/ubuntu-21.10

wp-config.php¶

wp-config.php

WordPress developers will often require customisation of optional constants that are defined in wp-config.php.

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.

If 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 Version¶

php¶

PHP 7.4 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.6 for example:

Add php: 5.6
Run vagrant provision

You can use either a two-part version (5.6) or a three-part version (5.6.1) if you want to pick specifc versions. We support any version between 5.6.0 and 8.4.x.

PHP File Upload Size¶

upload_size¶

A file upload size of 1024M is included with Chassis by default. This sets post_max_size and upload_max_filesize in php.ini and sets client_max_body_size in Nginx.

To switch to 100M for example:

Add upload_size: 100M to one of your .yaml files.
Run vagrant provision

Note: Additional php.ini settings can be configured by using the Chassis Phpini extension.

WordPress Directory¶

wpdir¶

Note: Deprecated; use paths.wp instead.

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:

Clone https://github.com/WordPress/WordPress.git to wp-trunk/
Add wpdir: wp-trunk to your config.local.yaml
Run vagrant provision

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.

Note

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

Multisite¶

multisite¶

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 multisite: Yes
For multisite on subdomains, set multisite: subdomains

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.

If you’re using subdomains then add your subdomains you’d like to use to a yaml file. e.g.

hosts:
  - vagrant.local
  - wat.vagrant.local
  - moo.vagrant.local

Then run vagrant provision. Once this is done, subdomains will work automatically in your browser. Create and remove sites at will, and Chassis will ensure it just works.

Each time you add a new subdomain you will need to add the subdomain to your yaml file and run vagrant provision.

These subdomains will be added to /lib/systemd/system/chassis-hosts.service

Note

Changing from multisite back to single site requires creating the box from scratch, using 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).

Default Admin¶

admin¶

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: admin@example.com
    password: password

Warning

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.

Database Configuration¶

database¶

Similar to the admin user configuration, you can also override the default MySQL name, user, password, charset and prefix:

database:
    name: wordpress
    user: wordpress
    password: vagrantpassword
    prefix: wp_
    charset: utf8mb4
    collation: utf8mb4_unicode_ci

(Again, don’t forget to include all lines, and use spaces for indentation.)

MySQL Configuration¶

mysql¶

Similar to the admin user configuration, you can also override the default MySQL options:

mysql:
    mysqld:
        sql_mode:
            - 'ERROR_FOR_DIVISION_BY_ZERO,NO_ZERO_DATE,NO_ZERO_IN_DATE'

(Again, don’t forget to include all lines, and use spaces for indentation.)

MariaDB Configuration¶

mariadb¶

You can change the default database flavour to be MariaDB by overridding the default MySQL settings:

mysql:
    package_name:
        mariadb-server
    mysqld:
        log-error:
            /var/log/mysql/mariadb.log
        pid-file:
            /var/run/mysqld/mysqld.pid
        ssl-disable:
            true
    mysqld_safe:
        log-error:
            /var/log/mysql/mariadb.log

(Again, don’t forget to include all lines, and use spaces for indentation.)

Custom Host Names¶

hosts¶

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.

Note

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 vagrant ssh to connect, then inside the box run ifconfig eth1 and look for the line starting with inet addr:.

IP Address¶

ip¶

Chassis picks an IP address for your box automatically, using DHCP. If you’d prefer a static IP, you can specify this here with ip: 192.168.1.114

(Typically, this should be in the private routing range; either 192.168.x.x or 10.x.x.x)

APT Mirror¶

apt_mirror¶

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 apt_mirror: Yes

If you have a specific mirror you’d like to use, you can set this as the value instead, such as:

apt_mirror: http://mirror.optus.net/ubuntu/

Synced Folders¶

synced_folders¶

By default Chassis syncs the php and nginx logs for you onto your local machine in the logs folder.

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

NFS¶

nfs¶

Under the hood, Vagrant uses the default synced folders implementation for your system. In certain cases and uses, this might be too slow for everyday usage. You can instead use NFS under the hood, which has much better performance, but requires root on your computer.

nfs: true

We highly recommend also installing the vagrant-bindfs plugin, which ensures that users are correctly mapped into the virtual machine for you. If you’re experiencing permissions errors, try installing this before anything else.

Paths¶

paths¶

If you’re transplanting Chassis into an existing project, you can manually set some paths. These can be set to absolute paths, or relative paths.

paths:
   base: .
   wp: wordpress
   content: wordpress/wp-content

There are a few important things to note about paths:

Paths must be set in config.local.yaml in the same directory as your Vagrantfile.
Path’s can’t be used in content/config.yaml.
base is relative to Vagrantfile.
content and wp are relative to base.
When used, the internal mount point is changed to /chassis instead of /vagrant.
Any time you make a change to the paths you will need to run vagrant reload for those changes to take effect.

In case you have the Chassis folder nested within the project rather than wrapping it, eg: base : .., you will need to navigate to Chassis folder in order to carry out any Vagrant commands, like vagrant up/vagrant halt and vagrant ssh, because they only work from the folder that has a VagrantFile. There is a workaround for that, which is to use the VAGRANT_CWD variable, eg: VAGRANT_CWD=chassis vagrant ssh. And you can automate this by using dotenv files with direnv``_. Install it and from the project directory execute: ``direnv allow .; echo 'export VAGRANT_CWD=chassis' > .envrc; replacing chassis with your relative Chassis directory name.

Note

When you change the paths configuration you will need to run vagrant provision for the changes to be applied.

Plugins¶

plugins¶

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.

Alternatively, if you want to install a plugin from a Git repository you can use a URL to a zip file of your plugin. e.g. https://github.com/humanmade/S3-Uploads/archive/master.zip

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 query-monitor.

plugins:
   - query-monitor
   - user-switching
   - https://github.com/humanmade/S3-Uploads/archive/master.zip

Themes¶

themes¶

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.

Alternatively, if you want to install a theme from a Git repository you can use a URL to a zip file of your theme. e.g. https://github.com/humanmade/S3-Uploads/archive/master.zip

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 twentysixteen.

themes:
   - twentyfifteen
   - twentysixteen
   - https://github.com/WordPress/twentyseventeen/archive/master.zip

Site Title¶

website¶

You can customize the title Chassis uses when installing your local WordPress site.

website:
   name: My Local WordPress Site

Extensions¶

extensions¶

You can enable official Chassis extensions and third party extensions by listing their repo name in the extensions section:

Extension names can be specified in one of three ways:

extension-name: Official Chassis extensions can be specified just by name.
user/repo: Extensions on GitHub can be specified using the username and repo separated with a slash.
https://github.com/example/example.git: Any other extension can be specified by its full git URL.

extensions:
   - Tester
   - chassis/chassis-openssl
   - https://bitbucket.org/some/example.git

You can also remove extensions that you have previously installed. All configuration files will be remove from your Chassis server.

To remove an extension simply add new section to one of your .yaml configuration files:

disabled_extensions:
   - chassis/mailhog

Machine Customisations¶

The underlying virtual machine managed by Vagrant can be customised, but depends on which provider you are using.

Virtual Machines - VirtualBox and Parallels¶

virtualmachine¶

When using VirtualBox or Parallels, you can customise how much memory (in megabytes) and how many virtual CPUs will be assigned to the machine. The default values for both (null) are to use the defaults are (1024 MB of RAM, and 2 vCPUs).

virtualmachine:
   memory: null
   cpus: null

machine_name¶

By default the machine name is “default”. This can make it difficult to distinguish between virtual machines in the VirtualBox GUI or when listing VMs on the command line. Overriding the machine name makes it easier to tell which one is which.

Note that if the machine name is changed after it has already been created vagrant will not be able to find the VM. It is recommended to destroy the VM before making this change and then recreating it.

machine_name: project.local

Configuration¶

Base Box Mode¶

wp-config.php¶

PHP Version¶

PHP File Upload Size¶

WordPress Directory¶

Multisite¶

Default Admin¶

Database Configuration¶

MySQL Configuration¶

MariaDB Configuration¶

Custom Host Names¶

IP Address¶

APT Mirror¶

Synced Folders¶

NFS¶

Paths¶

Plugins¶

Themes¶

Site Title¶

Extensions¶

Machine Customisations¶

Virtual Machines - VirtualBox and Parallels¶

Navigation

Related Topics