Local Chassis

Chassis is the bundled local development environment.

Configuration

It is possible to extend the default configuration for your local environment through the composer.json file. The values you can set correspond to those found in the Chassis documentation. In most cases you won't need to change anything here.

The following example adds some custom hosts and an extension:

{
	"extra": {
		"altis": {
			"modules": {
				"local-chassis": {
					"hosts": [
						"project.local",
						"subdomain.project.local",
						"alt-project.local"
					],
					"extensions": [
						"xdebug"
					]
				}
			}
		}
	}
}

PHP Version

From Altis v7 onwards the minimum required version of PHP is 7.4. If needed you can change the PHP version using the following configuration:

{
	"extra": {
		"altis": {
			"modules": {
				"local-chassis": {
					"php": "8.0"
				}
			}
		}
	}
}

Please note that not all Chassis extensions are guaranteed to work a version of PHP other than the default for your current version of Altis.

Elasticsearch Version

Altis supports Elasticsearch versions 6.2 to 7.10. The default version is currently 7.10.

You may wish to configure the Elasticsearch version to match the version currently in use on your cloud environments if it has not yet been upgraded.

This requires configuring 2 options for the local-chassis module, the repo_version which corresponds to the major version and version for the specific version. You must declare both values.

{
	"extra": {
		"altis": {
			"modules": {
				"local-chassis": {
					"elasticsearch": {
						"repo_version": "6",
						"version": "6.8.1"
					}
				}
			}
		}
	}
}

Setup

Chassis requires Vagrant and VirtualBox to be installed on your system.

To set up Chassis for Altis, run the following inside your project's directory:

composer chassis init

This will add Chassis to your development dependencies and prepare it to be run.

You can then use the other composer chassis commands to manage your machine.

Available Commands

A number of convenience commands are available:

  • composer chassis init - Initializes your local Chassis setup and starts the virtual machine.
  • composer chassis start - Starts the virtual machine.
  • composer chassis stop - Stops the virtual machine.
  • composer chassis status - Displays the status of the virtual machine.
  • composer chassis secure - Installs the generated SSL certificate to your trusted certificate store.
  • composer chassis destroy - Destroys the virtual machine.
  • composer chassis ssh|shell - Logs in to the virtual machine.
  • composer chassis exec -- <command> - Run a command on the virtual machine.
  • composer chassis restart|reload - Restart the virtual machine.
  • composer chassis provision - Updates the config.local.yaml file and re-provisions the machine.
  • composer chassis upgrade - Upgrade Chassis and the extensions. Note this will remove any extensions added manually.
  • composer chassis box update - Updates Chassis box image, this will destroy your data and start fresh.

Under the hood, the Local Chassis environment is powered by Chassis and Vagrant.

You can use the low-level Vagrant commands inside the chassis directory after you have run composer chassis init for the first time.

Extensions

Chassis has a number of extensions available which can be used to add additional functionality to your development environment. By default, your Local Chassis install is set up to mirror the Altis infrastructure, but you may wish to enable other tools for local development.

We recommend the following common development tools:

  • SequelPro - Adds a vagrant sequel command to instantly connect to your development MySQL server in Sequel Pro
  • XDebug - Installs XDebug for interactive debugging in your editor
  • phpdbg - Installs phpdbg for interactive command-line debugging
  • Mailhog - Captures outbound email from Altis and provides a fake inbox

You can add extra extensions by adding them to the project's composer.json config as shown in the configuration section of this page and running composer chassis provision.

Consult the Chassis documentation for further information about installing additional extensions.

Using HTTPS locally

Local Chassis will generate an HTTPS security certificate you can use to run your local environment over HTTPS. The file will be located in the /chassis directory, by default it will be called altis.local.cert but if you have customized the hosts in config.local.yaml it will use the first host name in that list for the file name.

Once your VM is running run the following command to install the certificate:

composer chassis secure

You should now be able to browse your local environment via HTTPS without certificate warnings.

Note: this command only supports OSX and Windows currently.

Windows

On Windows systems note that the composer chassis secure command requires administrator privileges.

In order for it to work you'll need to start your command prompt application such as GitBash by right-clicking the icon and selecting "Run as Administrator" from the context menu.

You can run the entire composer chassis init command in the administrator context but you should be sure that you are comfortable with everything the command is doing beforehand.

Firefox

Because the Firefox browser uses its own certificate store you will either need to install the generated certificate file manually or alternatively follow these steps:

  1. Open Firefox
  2. Browse to about:config
  3. Set security.enterprise_roots.enabled to true

Troubleshooting

Consult the Chassis Troubleshooting guide