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 theconfig.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:
- Open Firefox
- Browse to
about:config
- Set
security.enterprise_roots.enabled
to true
Troubleshooting
Consult the Chassis Troubleshooting guide