Installation

Overview

This guide covers installation of the IFCB dashboard on Windows 7 or 10. Windows 10 is recommended.

Pre-install checklist

• Your Windows machine has internet access
• Your Windows machine has virtualization enabled in the BIOS
• Your Windows machine is running 64-bit Windows 7 or 10 (see note below if you are running 32-bit)
• You have Administrator permissions and are able to install software on your Windows machine
• You have at least 2GB of free RAM (see note below)
• You can safely reboot your machine without losing access to it
• A browser other than Internet Explorer (see note below)

Note: the configurations provided are for 64-bit Windows. If you are running 32-bit Windows you will need to use a slightly different configuration, which will be provided and documented once it is tested. Until then, try replacing ubuntu/trusty64 with ubuntu/trusty32 in Vagrantfile.

Note: the default RAM usage of the dashboard is 2GB. It will likely work fine with less RAM (which is configured in Vagrantfile), but that has not been extensively tested.

Note: not all dashboard features work with Internet Explorer and because of limited support for development we cannot support it. To use all of the dashboard's web interface, you will need to use an alternate browser such as Firefox or Chrome. The browser we test with is Firefox for Windows.

Install required software packages

Install VirtualBox for Windows Hosts:

https://www.virtualbox.org/wiki/Downloads

The VirtualBox installation will temporarily interrupt network connections to and from your Windows machine. You may be prompted to accept the installation of network drivers; these are necessary for Windows to communicate with virtual machines, so accept them.

Install Git for Windows:

https://git-for-windows.github.io/

When installing Git for Windows, accept all defaults except for this one, which you should set to "checkout as-is, commit unix-style endings":

Install Vagrant for Windows. This will require a reboot.

https://www.vagrantup.com/downloads.html

Open "Git Bash". You should see a prompt. Type

cd
cd Documents

Get the code

In Git Bash, clone the ifcb-dashboard repository using this command:

git clone https://github.com/joefutrelle/ifcb-dashboard.git

this will create a directory called ifcb-dashboard. change to that directory using

cd ifcb-dashboard

Clone the oii repository using this command:

git clone https://github.com/joefutrelle/oii.git

Provision and run the virtual machine

Now use vagrant to start the virtual machine. This will take a long time initially, as it must download, install, configure, and start the dashboard.

vagrant up

During this process you may receive a pop-up asking if you want to grant access to networks from "VBoxHeadless". You should answer in the affirmative, to allow your computer to connect to the dashboard virtual machine.

If this process times out while attempting to connect with ssh, you may be attempting to boot a 64-bit version of Ubuntu on a 32-bit machine (see above), or you may not have enabled virtualization in your BIOS.

Once the virtual machine boots, you should be able to visit your dashboard now from the computer you are running it on at the following URL:

http://localhost:8888/

You will see a "blank" dashboard.

Do not attempt to re-provision your virtual machine using Vagrant. If you think provisioning has failed, use "vagrant destroy" followed by "vagrant up" to re-create your virtual machine.

Connect your data directory

To connect your dashboard to IFCB data, you have two options:

1. Store your data in a folder in the ifcb-dashboard folder, and
2. Serve your data from a Windows share

If you are installing the dashboard on a seagoing laptop, it is recommended to use the first option. If you are installing the dashboard on an onshore server, it is recommended to serve the data from a Windows share.

Option 1: store your data in the ifcb-dashboard folder

To use this option, store your data in a folder that is at or underneath the ifcb-dashboard folder where you made the GitHub clone. For example, if you cloned ifcb-dashboard at C:\Documents\ifcb-dashboard, and your data folder is called "data", move your folder to ifcb-dashboard so the resulting path is C:\Documents\ifcb-dashboard\data.

When you use this option, the pathname you will use in when configuring your time series on the dashboard will start with /vagrant and end with your folder name or the path of your folder underneath ifcb-dashboard. If you created a folder called data underneath ifcb-dashboard, the pathname will be /vagrant/data. If you created a folder called my_datasets containing a data folder called dataset1, the pathname will be /vagrant/my_datasets/dataset1, etc.

Option 2: serve your data from a Windows share

If you are serving your data from a Windows share, you can use the share configuration tool described in Interactive backend tools to choose what share to connect to, and what the pathname of that share will be on the virtual machine. That latter pathname is what you will use when configuring your time series on the dashboard.

When you use that tool, the default pathname is /mnt/ifcb_data; there is usually no reason to use a non-default path.

Your data will not yet appear in the dashboard; first you may want to adjust your URL settings to allow non-local access to the dashboard.

Note: it's very important for the proper functioning of the dashboard for the share to remain accessible at all times. If your share is served from a machine that is rebooted frequently or is not always accessible over the network, then your dashboard may become unresponsive and you will probably need to manually unmount and remount the share on the virtual machine, or reboot it.

Allowing non-local access to your dashboard

If you would like to be able to connect to your dashboard from a different computer than the one you are running it on, you will need to make a small configuration change to dashboard_conf.py in the ifcb-dashboard directory.

By default, there is a line in dashboard_conf.py that reads:

DASHBOARD_BASE_URL='http://localhost:8888/'

Edit this, replacing localhost with the fully qualified domain name of your computer. For instance if your computer is called mycomputer.something.edu, change the line to

DASHBOARD_BASE_URL='http://mycomputer.something.edu:8888/'

Note: don't change WORKFLOW_URL.

Now restart the dashboard. You will need to do this by being logged into the virtual machine (using vagrant ssh) and running the command

sudo service apache2 restart

Note: you will see a warning that begins "Could not reliably determine the server's fully qualified domain name". You can ignore this warning.

If you are running Windows Firewall, you will need to make sure that it is not blocking TCP traffic on port 8888.

Administration and security

Server administration actions, such as loading data into the dashboard (aka "accession") require logging into the dashboard as a privileged user. The default administrative username is "admin@whoi.edu" and the default password is "12345678". Click on the "Admin" link at the bottom of the web interface, log in, navigate to the "Users" tab, and you can (and should!) change the password for this user from the default.

On the users tab you can also create and modify users, and grant/revoke administrative privileges to a user. You should always have at least one user with administrative privileges that you can log in as.

Recovering from a forgotten password or lost administrative access

If you forget your password, or you accidentally revoke administrative privileges from all users, or you delete all users, you can use the password reset tool described in Interactive backend tools. This tool will allow you to change the password of an existing user, or will allow you to create a new user with administrative privileges and set their password.

Accession

On the administration page, navigate to "Time Series" and click on "Add Another Time Series". Give your time series a short name (no spaces) and a brief description, and set "enabled" to "true". Next, fill in the empty path entry with the path /mnt/ifcb_data (or /vagrant/data if you created a data folder in the ifcb-dashboard directory). Make sure that default setting of "raw" is selected under the path. The correct directory to add is either one that contains data files, or one that contains a subdirectory for each year that has data.

If you are using a share and used a pathname other than the default /mnt/ifcb_data when you connected to the share, use that pathname instead.

If you are storing your data in the ifcb-dashboard folder, use the /vagrant-based pathname of your data folder (e.g., /vagrant/data). See "Connect your data directory" for details on this method.

Click the blue "Save" button (not the "Add Another Path" button). Then click the "Check paths" button. You should receive a message indicating that data has been found at the path you specified. If you see a message that data is not found, you have either set the path wrong or there is a problem accessing your data share.

Once "Check paths" succeeds, click "Accede". Navigate back to the time series by clicking on time series link. Now if you reload repeatedly you should see data appear on the timeline.

Note: if you put new data in your data directories, the dashboard will not automatically detect and load the data. You will need to press the "Accede" button again to load the new data.

Debugging accession

If you are having trouble with accession, check that all the following are set up correctly:

• Your data directory share is mounted on your virtual machine (e.g., at /mnt/ifcb_data) and on the virtual machine, you can list the files on your mount point (e.g., with "ls /mnt/ifcb_data") and see something (rather than nothing)
• Your time series configuration on the dashboard Admin page has a "raw" path that is set to your mount point (e.g., /mnt/ifcb_data followed by the appropriate subdirectory on your share)
• Clicking "Check paths" on your time series does not generate a warning about not being able to find data
• You have clicked "Accede"
• You have waited at least 30 seconds and have reloaded the dashboard in your browser

If all of these are taken care of, the next simplest course of action is to reboot your virtual machine. In Git Bash, in your ifcb-dashboard directory, run the following commands:

vagrant halt
vagrant up

Once your virtual machine is back up, navigate to the dashboard's Admin page and re-attempt accession.

Another approach is to halt the virtual machine, reboot the Windows machine that the virtual machine is running on, and restart the virtual machine.