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¶
Download the VirtualBox DMG file applicable to your MacOS version, and install from the disk image.
Download the Vagrant DMG file applicable to your MacOS version, and install from the disk image.
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 bymvn 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 thebrightspot/express/site
directory.Using the command-line interface, change to the directory you identified in the previous step.
Clone the Brightspot virtual machine:
curl -o Vagrantfile "https://s3.amazonaws.com/brightspot-vagrant/brightspot/Vagrantfile"
.In a text editor, open
Vagrantfile
.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.Save and close the Vagrant file.
Windows¶
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
- Install VirtualBox 5.0.12:
choco install virtualbox --version 5.0.12.104815 --force
. - Install Vagrant 1.9.3:
choco install vagrant --version 1.9.3 --force
.
Option 2: Download from Sites
- Install VirtualBox 5.0.12. Download the Windows EXE file from VirtualBox 5.0.12.
- Install Vagrant 1.9.3. Download the Windows MSI file from Vagrant 1.9.3.
- Install VirtualBox 5.0.12:
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 bymvn 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 thebrightspot/express/site
directory.Using the PowerShell command-line interface, change to the directory you identified in the previous step.
Clone the Brightspot virtual machine:
curl -outFile Vagrantfile "https://s3.amazonaws.com/brightspot-vagrant/brightspot/Vagrantfile"
.In a text editor, open
Vagrantfile
.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.Save and close the Vagrant file.
Boot Vagrant Machine¶
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)
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]
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.
Copy the Brightspot WAR into the Vagrant directory
/servers/brightspot/webapps
, naming the target WAR fileROOT.war
. For example:cp tutorial-init-1.0-SNAPSHOT.war /servers/brightspot/webapps/ROOT.war
Tomcat automatically deploys the WAR.
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.Optionally, map a host name to the host IP address. See Map Host Name to IP Address.
Start Brightspot by entering the URL in the browser URL bar, for example,
172.28.128.13/cms
orbrightspot-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:
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/
.
- On the host machine:
If you cloned
Vagrantfile
into the parent directory containing Maven’starget/
directory, thenls /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.
For a Unix-based OS, open the file
/etc/hosts
in a text editor.For Windows, open the
Windows/System32/drivers/etc/hosts
file.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
Save and close the file.
Stop a Vagrant Machine¶
- If you are logged into the virtual machine, type
exit
to end the ssh session, which returns you to the host machine. - 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.
Delete the Vagrant cached version of the VM:
vagrant box remove brightspot
Download the latest version of Vagrantfile:
curl -o Vagrantfile "https://s3.amazonaws.com/brightspot-vagrant/brightspot/Vagrantfile"
In a text editor, open
Vagrantfile
.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.Save and close the Vagrant file.
-
A line similar to the following appears in the console messages:
Downloading: https://s3.amazonaws.com/brightspot-vagrant/brightspot.box