Vagrant is an environment for building and sharing pre-configured virtual machines. Some developers integrate Vagrant machines into the development environment to simulate local-remote connections. Perfect Sense provides a Vagrant virtual machine that has many of the development tools you need to simulate a remote server running Brightspot, an email server, or other applications.

Perfect Sense’s Vagrant virtual machine is actually an Ubuntu Linux machine. If you’re familiar with the Ubuntu Server, then you’re already familiar with our Vagrant virtual machine.

Install and Boot a Vagrant Virtual Machine

  1. Install VirtualBox from Download VirtualBox.

  2. Install Vagrant from Download Vagrant.

  3. On the host machine, create a directory where you want to install the Vagrant virtual machine, such as ~/virtual/. (Best practice: if you are using Vagrant to test Brightspot builds, create or identify a directory at or above the target/ directory created by mvn clean install. For a motivation for this best practice, see Vagrant Directory Structure.)

  4. Change to the directory you created or identified in the previous step.

  5. Clone the Brightspot virtual machine: curl -o Vagrantfile "".

  6. In a text editor, open Vagrantfile.

  7. Search for the key config.vm.hostname, and change the value to a standard domain name such as The name you choose must be different from all other domain names in your other Vagrant machines.

  8. Search for the key, and change the value to the domain name from step 7. The first few lines of the file Vagrant are now similar to the following:

    # -*- mode: ruby -*-
    # vi: set ft=ruby :
    # all vagrant configuration is done below. the "2" in vagrant.configure
    # configures the configuration version (we support older styles for
    # backwards compatibility). please don't change it unless you know what
    # you're doing.
    vagrant.configure(2) do |config|
      # the most common configuration options are documented and commented below.
      # for a complete reference, please see the online documentation at
      # change the config.vm.hostname and variables to match your project's name.
      config.vm.hostname = ""
      config.vm.provider :virtualbox do |vb| = ""
        vb.customize ["modifyvm", :id, "--memory", "2048"]
        vb.customize ["modifyvm", :id, "--cpus", "1"]
  9. Save and close the Vagrant file.

  10. Launch the Vagrant virtual machine; at the command prompt, type vagrant up. Respond to any prompts. When you return to the command line, the virtual machine is running.

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

vagrant@example: [example development sandbox(dev) 1]

Vagrant Directory Structure

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


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 ~/virtual_machines, then the following commands give the same listing:
    • On the host machine: ls ~/virtual_machines/.
    • On the Vagrant machine: ls /vagrant/.
  • If you cloned Vagrantfile into the same directory containing Maven’s target/ directory, then ls /vagrant/target/ shows the output from the Maven build.
  • The Tomcat configuration file is at /servers/training/conf/context.xml.
  • The Brightspot WAR file is at /servers/training/webapps/ROOT.war. If you build a Brightspot project in a directory not accessible to Vagrant, you can copy the resulting WAR file over the existing ROOT.war.
  • Brightspot’s base URL / points to /servers/training/www/.

Paths you configure in context.xml appear under the Brightspot base URL.

 <Environment name="dari/storage/local/class" value="com.psddev.dari.util.LocalStorageItem" type="java.lang.String" />
 <Environment name="dari/storage/local/baseUrl" value="/storage" type="java.lang.String" />
 <Environment name="dari/storage/local/originBaseUrl" value="http://localhost/storage" type="java.lang.String" />
 <Environment name="dari/storage/local/rootPath" value="/servers/training/www/storage/" type="java.lang.String" />

Referring to the previous snippet, line 2 indicates a base URL for storage items at /storage, which corresponds to the local absolute path /servers/training/www/storage/ in line 4.

Common Vagrant Commands

The following sections describe a few of the common commands used in developing Brightspot on a Vagrant machine.

Retrieving a Vagrant’s IP Address

You can retrieve the Vagrant machine’s IP address. At the Vagrant command prompt, enter ifconfig eth1.

eth1      Link encap:Ethernet  HWaddr 08:00:27:a0:5d:40
          inet addr:  Bcast:  Mask:
          inet6 addr: fe80::a00:27ff:fea0:5d40/64 Scope:Link
          RX packets:47 errors:0 dropped:0 overruns:0 frame:0
          TX packets:40 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:8252 (8.2 KB)  TX bytes:5452 (5.4 KB)

Referring to the previous example, the IP address is; your IP address may be different.

Stopping a Vagrant Machine

  1. On the host machine, change to the directory from where you started the Vagrant machine.
  2. At the command prompt, vagrant halt.

Direct HTTP Requests to Brightspot Running on Vagrant

You can install a Brightspot instance on a Vagrant machine, and then spoof domain name requests to the Vagrant machine. For example, you can redirect requests to an instance of Brightspot running on your Vagrant machine (instead of to the real domain

  1. Determine the Vagrant machine’s IP address; for details, see Retrieving Vagrant’s IP Address.

  2. Map the domain name to its IP address by doing the following:

    1. Open the file /etc/hosts in a text editor.

    2. Add a line <ipaddress> <hostname>, where <ipaddress> is the IP address from step 1 and <hostname> is the spoofed host name. localhost broadcasthost
    3. Save and close the file.

  3. In your browser, go to the spoofed domain name with /cms, such as Brightspot’s login page appears.