Reference

Dash Documentation

The Chassis documentation can be downloaded and viewed in Dash on Mac. Simply search for Chassis in the User Contributed docs.

../_images/dash.png

Other alternatives have been developed in cooperation with Dash.app’s developer Kapeli:

Commands

This is a very quick reference of Vagrant commands we find useful. For the full documentation, check out the Vagrant command reference.

# Start the VM
vagrant up

# SSH in to the VM
vagrant ssh

# Reprovisioning (e.g. after updating this repository)
vagrant provision

# Suspending (sleeping) the VM
vagrant suspend

# Halting (shutting down) the VM
vagrant halt

# Reboot (halt and up)
vagrant reload

# Destroying the VM (if your VM is completely broken)
vagrant destroy

Building a new Base Box for Vagrant Cloud

The Chassis base boxes are generated by the Chassis team and they are uploaded to Vagrant Cloud.

The Chassis base box will follow the SEM Versioning 2.0.0 specification which is MAJOR.MINOR.PATCH. For example:

  1. MAJOR version 2.0.0 - This would be a new Ubuntu distribution. e.g. Bionic Beaver.

  2. MINOR version 1.1.0 - This would be when we have added a new Chassis feature. e.g. upload_size

  3. PATCH version 1.0.1 - This would be when the Ubuntu base box has had an update or a bug fix.

To generate and upload a new base box a Vagrant Cloud Chassis team member will need to do the following:

  1. Open a new issue in the Chassis repository with details about the base box updates.

  2. Create a new branch off main for the base box updates.

  3. Backup any custom yaml configuration files you have as they will be deleted during this process.

  4. Delete any extensions in your extensions folder (apart from example as it’s required).

  5. Bump the version number of the base box in the build script, yaml file and documentation.

  6. Change _mode: normal to _mode: base in config.yaml.

  7. Run vagrant destroy -f.

  8. Run vagrant up.

  9. Run sh buildbox.sh in the root directory of Chassis.

  10. Login to your Vagrant Cloud account when you are prompted to do so.

  11. Wait for the upload to complete.

  12. Submit a Pull Request and wait for one of the Chassis team members to approve it.

When you’re building a new base box it’s a good idea to check the versions of the following software for when write the release notes:

  1. PHP - php -v

  2. software-properties-common - apt policy software-properties-common

  3. curl - curl --version

  4. pip - pip -V

  5. avahi-daemon - avahi-daemon -V

  6. puppet - puppet --version

  7. ruby - ruby -v

Troubleshooting

Logs

Chassis synchronises the Nginx and PHP log files from the Virtual Machine to your local development folder. These logs can be useful if your provisions are failing and you require further information.

There are three logs that we synchronise for you:

  1. logs/php/php_errors.log - This shows any PHP errors or warnings that have occurred.

  2. logs/nginx/error.log - This shows any errors that have occurred.

  3. logs/nginx/access.log = This shows details of any requests that Nginx has served.

Vagrant gets stuck on default: SSH auth method: private key on Windows machines

$ vagrant up
default: SSH auth method: private key

To resolve this issue you’ll need to do the following:

  1. Click the Search icon.

  2. Type Turn Windows features on or off in the search field.

  3. Click Open.
    ../_images/windows_features_1.jpeg
  4. Uncheck both Virtual Machine Platform and Windows Hypervisor Platform.
    ../_images/windows_features_2.jpeg

  5. Click OK and restart your computer.

  6. Change directories back to your Chassis project and run vagrant up.

Character encoding on Windows machines

$ vagrant up
Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'bento/ubuntu-16.04'...
C:/Vagrant/embedded/gems/2.1.1/gems/childprocess-0.6.3/lib/childprocess/windows/process_builder.rb:43:in `join': incompatible character encodings: Windows-1252 and UTF-8 (Encoding::CompatibilityError)

To resolve this issue you’ll need to create a symlink and set the VAGRANT_HOME path. e.g.

$ cd C:\users
$ mklink /J username usérnamé
$ setx VAGRANT_HOME "C:/users/username"

Alternatively you can set the path for VirtualBox to a directory that doesn’t have special characters. To do this open the VirtualBox application, select ‘File’ -> ‘Settings’ -> ‘General’ and change the default path for VM’s (e.g. to “C:VirtualBox VMs”).

Server IP address could not be found. (DNS_PROBE_FINISHED_NXDOMAIN)

This typically occurs on Mac when the DNS configuration has not been set up properly during the installation. SSH into the Chassis machine and run sudo service avahi-daemon restart

Further issues

In case the previous tips didn’t solve your issue, it is recommended to update your copy of Virtualbox, Vagrant, Chassis, and the Chassis box ( note that updating the box will recreate your instance from scratch ), and/or create a bug report on the GitHub repo.