Installation on Virtual Machine

You can install Brightspot on a virtual machine running on your host. This scenario is useful when developing several instances of Brightspot, or if you want to share a virtual instance with other developers.

Perfect Sense provides a Vagrant-based virtual machine that has all of the dependencies required to run Brightspot: Ubuntu Linux server, Tomcat, databases, and ancillary software. You can compile your version of Brightspot and deploy the war file to this virtual machine.

The following sections describe how to retrieve the preconfigured virtual machine and then use it to run Brightspot.

System Requirements

Ensure you have the following software installed before proceeding.

Installing the Preconfigured Virtual Machine

Brightspot’s preconfigured virtual machine runs on VirtualBox and Vagrant. The following sections describe how to install the proper versions of VirtualBox and Vagrant for the supported operating systems.

MacOS

To install the preconfigured virtual machine on OS X:

  1. Download and install the VirtualBox DMG:
  2. Download and install the Vagrant DMG:
  3. On the host, create or identify the directory where you want to install the preconfigured guest. As a best practice, use a directory with a name different from all other directories containing other preconfigured guests.
  4. In a terminal emulator, change to the directory you identified in step 3.
  5. Retrieve the preconfigured guest: curl -o Vagrantfile https://s3.amazonaws.com/brightspot-vagrant/boxes/Vagrantfile.

Windows

To install the preconfigured virtual machine on Windows:

  1. Download and install the executable VirtualBox 5.0.12.
  2. Download and install the MSI Vagrant 1.9.3.
  3. On the host, create or identify the directory where you want to install the preconfigured guest. As a best practice, use a directory with a name different from all other directories containing other preconfigured guests.
  4. Using the PowerShell command-line interface, change to the directory you identified in step 3.
  5. Retrieve the preconfigured guest: curl -o Vagrantfile https://s3.amazonaws.com/brightspot-vagrant/boxes/Vagrantfile.

Installing Brightspot on the Virtual Machine

To install Brightspot on the preconfigured virtual machine:

  1. Build your Brightspot project: in the root directory, type mvn clean install.

  2. Boot the guest by doing the following:

    1. Change to the directory where you downloaded Vagrantfile.
    2. Type vagrant up. Respond to any prompts.

  3. Log in to the guest: type vagrant ssh. The guest’s command prompt is similar to the following:

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

  4. In the guest, change to the directory that maps to the directory where the Brightspot war resides, such as cd /vagrant/target (see the illustration Vagrant host and guest directory structures).

  5. Copy the Brightspot war into the guest directory /servers/brightspot/webapps/, naming the target war file ROOT.war. For example:

    cp /vagrant/express-site-4.2-SNAPSHOT.war /servers/brightspot/webapps/ROOT.war

    Tomcat automatically deploys the war.

  6. Retrieve the guest’s IP address: on the guest, type hostname -I. The guest displays addresses similar to the following. Use the address that starts with 172.

    10.0.2.15 172.28.128.13

  7. (Optional) Map a host name to the host IP address. See Mapping a Host Name to a Virtual IP Address.

  8. Start a Brightspot session by pointing a browser to the guest’s directory cms, such as 172.28.128.13/cms. If a POC (proof-of-concept) Starter Kit appears, click Skip. 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.

../../../_images/vagrant-directory-structure.svg

Vagrant host and guest directory structures

Referring to the previous illustration:

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

    • On the host: ls ~/brightspot-tutorial/init/.
    • On the guest: 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 deployed 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/. For example, 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" />

See also:

Mapping a Host Name to a Virtual IP Address

You can optionally map a host name to the guest’s IP address.

To map a host name to a guest’s IP address:

  1. In a text editor, open one of the following files:

    • For a Unix-based OS, open /etc/hosts.
    • For Windows, open C:\Windows\System32\drivers\etc\hosts.

  2. Add a line <ipaddress> <hostname>, where <ipaddress> is the guest’s IP address and <hostname> is a name of your choice.

    127.0.0.1 localhost
255.255.255.255 broadcasthost
172.28.128.13 custom-brightspot

  3. Save and close the file.

Stopping a Vagrant Machine

To stop a running Brightspot virtual machine:

  1. If you are logged in to the guest, type exit until you return to the host.
  2. At the host’s command prompt, type vagrant halt.

Upgrading to Latest VM

The first time you run the script Vagrantfile, the script downloads a virtual machine. Vagrant caches the virtual machine, so you may eventually be using an unsupported version. If you receive runtime error messages, consider upgrading your version of the virtual machine by using the following procedure.

To upgrade a virtual machine:

  1. In a terminal emulator, change to the directory containing the file Vagrantfile.

  2. Delete the cached version of the VM:

    vagrant box remove <name>

  3. Download the latest version of Vagrantfile:

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

  4. Install Brightspot as described in Installing Brightspot on the Virtual Machine.