Virtual Machine

This section outlines how to run a local version of Islandora as a virtual machine (VM) image. The Islandora VM is a virtual instance of Ubuntu Linux that comes with all of the components of the Islandora stack already installed and configured properly, resulting in a minimal Islandora instance (similar to the Islandora Sandbox). Due to the generic way that the Islandora VM is configured, it should not be used as a production instance (for a production Islandora, see the Enterprise installation section). The Islandora VM is best used as a disposable isolated environment for testing and experimentation with Islandora’s internals. Users who are new to Islandora are encouraged to use the VM to explore the backend of a working Islandora instance and try out new modules without lasting consequences.

The primary way to use the Islandora VM is by downloading a .ova file (which stands for Open Virtual Application, a type of file format for VMs) from the http://islandora.ca/downloads and running it with VirtualBox. Every time a new version of Islandora is released, you will find it on the Islandora website for download. Release candidates (betas of new Islandora versions) are also sometimes made available for testing before a release.

Another option is to use Vagrant a command line utility that provides an alternate interface to VirtualBox as well as an alternate way of packaging and distributing virtual machines for others to use as a Vagrantfile (and associated provisioning scripts). Vagrant is popular with Islandora developers because it allows them to quickly destroy and rebuild VMs from the command line, as well as create customized virtual Islandora instances featuring new modules and/or different components and easily share them with others for review.

Both of the above methods for running the Islandora VM are described in greater detail below, and require administrative access to a machine with at least 4GB of RAM. Running an operating system inside of an operating system consumes a relatively large amount of memory, so at least 4GB is recommended in order to avoid slow-running VMs.

Using VirtualBox

The easiest way to use the Islandora VM is by running it with VirtualBox. See chapter 2 of the VirtualBox documentation for instructions on how to install VirtualBox for your operating system. Once VirtualBox has been installed on your machine, download the virtual machine image of the latest stable Islandora release from http://islandora.ca/downloads under “Virtual Machine Image”, or download past versions of Islandora from the list at the bottom of the page under “Virtual Machine Archive”. All of these links lead to .ova files which are fairly large and may take a while to download.

Once the .ova file has finished downloading, double click on it or open it with VirtualBox. This will open up VirtualBox’s import menu, where it displays the preset configurations. Click the “Import” button at the bottom of the window to start the import process (this may take a few minutes). When VirtualBox is done importing, select the Islandora VM from the list of all imported virtual machines (if you have installed VirtualBox from scratch, the Islandora VM should be the only one) and then select the green “Start” arrow at the top of the window to run the Islandora VM.

This will open up a console in a new window giving you command line access to the Islandora VM. Once the VM is done loading, it will prompt you for a username and password: both are ‘vagrant’. After logging in, you will be in the home directory of the running Islandora VM. You can find the VM’s Drupal instance by navigating to ‘/var/www/drupal/htdocs/’, Fedora, Solr and Tomcat are at ‘/usr/share/fedora’, ‘/usr/share/solr’ and ‘/usr/share/tomcat6’, respectively.

Access Islandora in your browser by going to http://localhost:8000/.The default VM user name is "admin" and the password is "islandora".

If you have SSH available on your local machine, you can log in to the virtual machine directly with ‘ssh -p 2222 vagrant@localhost’ and entering the password ‘vagrant’ (this is helpful if you dislike the black and white VirtualBox shell interface, or prefer to use your own terminal emulator).

Using Vagrant

If you prefer to work from the command line or your want to easily create customized virtual Islandora instances to share with the community, consider using Vagrant. Vagrant requires VirtualBox to run, so after installing VirtualBox download and install Vagrant and learn the basic commands. You can find the latest Islandora Vagrantfile and provisioning scripts at https://github.com/Islandora-Labs/islandora_vagrant; follow the instructions in the README.md file to get it up and running. Downloading and installing all Islandora’s components will take some time. Grab a coffee while you wait!

Once you have the Islandora Vagrant VM running, you will find Drupal at ‘/var/www/html/drupal’. Fedora, Solr and Tomcat are at ‘/usr/local/fedora’, ‘/usr/local/solr’ and ‘/var/lib/tomcat7’, respectively. Individual components of the Islandora stack are installed with shell scripts in the repo’s scripts folder.

If you would like to create your own customized instance of Islandora to share with others and/or test a specific use case, make a fork of the islandora_vagrant repo, modify the scripts and Vagrantfile to accommodate whatever customizations you require and share the new repo’s GitHub URL with others. If you make changes to a customized Islandora Vagrant repo and would like to contribute those changes back to the original author, be a good neighbor and submit them with a pull request.