Vagrant Installation

Vagrant is an environment for running preconfigured virtual machines. The Brightspot virtual machine is preconfigured with an Ubuntu Linux operating system, Tomcat, and databases, and is periodically updated with other software that integrates with Brightspot. You only need to manage the virtual environment and deploy the application WAR.

This topic describes the Vagrant installation in the context of running a Brightspot project in a virtual machine. It assumes that you have downloaded and built either the Brightspot Tutorial or a full Brightspot project. The topic applies to both Unix-based and Windows host operating systems.

System Requirements

To build a development environment with Vagrant, you’ll need the following:

Note

MacOS Mojave requires VirtualBox 5.2.20 and Vagrant 2.2.0.

Install Vagrant Machine

A Vagrant machine requires VirtualBox and Vagrant.

Depending on your operating system, see MacOS or Windows.

MacOS

  1. Download the VirtualBox DMG file applicable to your MacOS version, and install from the disk image.

  2. Download the Vagrant DMG file applicable to your MacOS version, and install from the disk image.

  3. On the host machine, identify the directory where you want to install the Vagrant virtual machine. As a best practice, use the directory above the target/ directory created by mvn clean install.

    For example, if you built the init application in the Brightspot Tutorial project, use the brightspot-tutorial/init directory. For the Brightspot project, use the brightspot/express/site directory.

  4. Using the command-line interface, change to the directory you identified in the previous step.

  5. Clone the Brightspot virtual machine: curl -o Vagrantfile "https://s3.amazonaws.com/brightspot-vagrant/brightspot/Vagrantfile".

  6. In a text editor, open Vagrantfile.

  7. Set the vb.name key (typically line 13) to a unique host name that identifies your Brightspot application, for example, vb.name=brightspot-tutorial-init. The name you choose must be different from all other host names in your other virtual machines, as required by VirtualBox.

  8. Save and close the Vagrant file.

Windows

  1. Install VirtualBox and Vagrant.

    Our recommended install procedure is to use the Chocolatey Package Manager to install Vagrant and VirtualBox. Optionally, you can download the install files from the VirtualBox and Vagrant sites and launch the installers.

    Option 1 (Recommended): Chocolatey

    1. Install VirtualBox 5.0.12: choco install virtualbox --version 5.0.12.104815 --force.
    2. Install Vagrant 1.9.3: choco install vagrant --version 1.9.3 --force.

    Option 2: Download from Sites

    1. Install VirtualBox 5.0.12. Download the Windows EXE file from VirtualBox 5.0.12.
    2. Install Vagrant 1.9.3. Download the Windows MSI file from Vagrant 1.9.3.

  2. On the host machine, identify the directory where you want to install the Vagrant virtual machine. As a best practice, use the directory above the target/ directory created by mvn clean install.

    For example, if you built the init application in the Brightspot Tutorial project, use the brightspot-tutorial/init directory. For the Brightspot project, use the brightspot/express/site directory.

  3. Using the PowerShell command-line interface, change to the directory you identified in the previous step.

  4. Clone the Brightspot virtual machine: curl -outFile Vagrantfile "https://s3.amazonaws.com/brightspot-vagrant/brightspot/Vagrantfile".

  5. In a text editor, open Vagrantfile.

  6. Set the vb.name key (typically line 13) to a unique host name that identifies your Brightspot application, for example, vb.name=brightspot-tutorial-init. The name you choose must be different from all other host names in your other virtual machines, as required by VirtualBox.

  7. Save and close the Vagrant file.

Boot Vagrant Machine

  1. Launch the Vagrant virtual machine; at the command prompt, type vagrant up. Respond to any prompts.

    Building the new VM may take a few minutes. Upon completion, Vagrant displays a message similar to the following:

    Welcome to Ubuntu 14.04.3 LTS (GNU/Linux 3.19.0-25-generic x86_64)

  2. Log in to the virtual machine: vagrant ssh. The virtual machine’s command prompt is similar to the following:

    vagrant@brightspot-tutorial-init: [brightspot-tutorial-init-development sandbox(dev) 1]

  3. Go to the Vagrant directory that maps to the target directory where the Brightspot WAR resides: cd /vagrant/target.

    For a visual representation, see Vagrant Directory Structure.

  4. Copy the Brightspot WAR into the Vagrant directory /servers/brightspot/webapps, naming the target WAR file ROOT.war. For example:

    cp tutorial-init-1.0-SNAPSHOT.war /servers/brightspot/webapps/ROOT.war

    Tomcat automatically deploys the WAR.

  5. Retrieve Vagrant’s IP address that you will use to access Brightspot. Type hostname -I.

    This displays addresses similar to the following. Use the address that starts with 172.

    10.0.2.15 172.28.128.13

    Alternatively, you can use the ifconfig eth1 command.

  6. Optionally, map a host name to the host IP address. See Map Host Name to IP Address.

  7. Start Brightspot by entering the URL in the browser URL bar, for example, 172.28.128.13/cms or brightspot-tutorial-init/cms.

    You are greeted by a POC (proof-of-concept) Starter Kit. If you elect to skip the kit, a login page similar to the following appears:

    ../../../_images/login-page.png

Note

If you experience excessively slow performance with either the host OS or the guest Ubuntu OS, you may need to adjust memory allocation in the VirtualBox Manager.

Vagrant Directory Structure

The following illustration shows some of the dedicated directories in the Vagrant machine.

/
   ├── vagrant
   |   └── target
   |       ├── /classes
   |       ├── /generated-sources
   |       ├── /maven-archiver
   |       ├── /war
   |       └── <file-name>-SNAPSHOT.war
   └── servers
       └── brightspot
           ├── /conf
           |   └── context.xml
           └── /webapps
               └── ROOT.war

Referring to the previous illustration:

  • The host directory from which you boot the Vagrant machine is available from Vagrant’s directory /vagrant/. If you launched the Vagrant machine from ~/brightspot-tutorial/init, then the following commands give the same listing:

    • On the host machine: ls ~/brightspot-tutorial/init/.
    • On the Vagrant machine: ls /vagrant/.

  • If you cloned Vagrantfile into the parent directory containing Maven’s target/ directory, then ls /vagrant/target/ shows the output from the Maven build.

  • The Brightspot WAR file is at /servers/brightspot/webapps/ROOT.war.

  • The Tomcat configuration file is at /servers/brightspot/conf/context.xml.

    Should you need to modify the default configuration in context.xml, note that the Brightspot base URL is /servers/brightspot/www/.

    Referring to the following snippet, line 3 indicates a base URL with the relative path of /storage, which corresponds to the absolute path /servers/brightspot/www/storage/.

1
2
3
<Environment name="dari/storage/local/class" value="com.psddev.dari.util.LocalStorageItem" type="java.lang.String" />
<Environment name="dari/storage/local/originBaseUrl" value="http://localhost/storage" type="java.lang.String" />
<Environment name="dari/storage/local/baseUrl" value="/storage" type="java.lang.String" />

Map Host Name to IP Address

You can optionally map a host name to the Vagrant IP address.

  1. For a Unix-based OS, open the file /etc/hosts in a text editor.

    For Windows, open the Windows/System32/drivers/etc/hosts file.

  2. Add a line <ipaddress> <hostname>, where <ipaddress> is the IP address and <hostname> is a name of your choice. For example, you can use the host name that you specified in the Vagrant file.

    127.0.0.1 localhost
255.255.255.255 broadcasthost
172.28.128.13 brightspot-tutorial-init

  3. Save and close the file.

Stop a Vagrant Machine

  1. If you are logged into the virtual machine, type exit to end the ssh session, which returns you to the host machine.
  2. At the command prompt of the host machine, vagrant halt.

Upgrade to Latest VM

Vagrantfile is a script that downloads the virtual machine (VM) when you execute the script for the first time. Because the VM is subject to environment updates, you may want to upgrade your Brightspot project with the latest VM version.

  1. Delete the Vagrant cached version of the VM:

    vagrant box remove brightspot

  2. Download the latest version of Vagrantfile:

    curl -o Vagrantfile "https://s3.amazonaws.com/brightspot-vagrant/brightspot/Vagrantfile"

  3. In a text editor, open Vagrantfile.

  4. Set the vb.name key (typically line 13) to a unique host name that identifies your Brightspot application, for example, vb.name=brightspot-test. The name you choose must be different from all other host names in your other virtual machines, as required by VirtualBox.

  5. Save and close the Vagrant file.

  6. Boot Vagrant Machine.

    A line similar to the following appears in the console messages:

    Downloading: https://s3.amazonaws.com/brightspot-vagrant/brightspot.box