Virtual Machine: ``vagrant-EdJL``
=================================

The vagrant VM created by this process automatically sets up your `uhed` and
provides a web interface for creating `JupyterLab <https://jupyterlab.readthedocs.io>`_ 
notebooks as well as a web-based interface for accessing the VM shell.

.. note:: 
  See the Configurable Options section below for environment variables 
  which can tweak the settings of the VM environment that is created.

=========================
Installation Dependencies
=========================

Install these dependencies before creating the Vagrant VM.

* VirtualBox (https://www.virtualbox.org/wiki/Downloads)
* Vagrant (https://www.vagrantup.com/downloads.html)

.. note:: 
   1. After installation of Virtualbox, go to the downloads link again and
      download and install the extension pack for all systems.
   2. After installation of vagrant, you will need to restart your computer.
   3. Once restarted, go to your command line and also install the plugin
      ``vagrant-vbguest`` for vagrant using the command::

        vagrant plugin install vagrant-vbguest

=============================
Set up your EdJL VM directory
=============================

* Create a directory on your system named ``edujlab`` to hold your UHED environment
* Copy ``datapool.tar.gz`` to this directory
* Copy ``imports.tar.gz`` to this directory
* Download the vagrant setup files 

 * On systems with ``curl`` (MacOS X, Linux) you can use the following command::

    curl -O http://docs.uh-netlab.org/software/tool-environments/_files/vagrant-EdJL/Vagrantfile
 
 * On Windows systems with Powershell you can use the following::

    PS C:\edujlab> $client = new-object System.Net.WebClient
    PS C:\edujlab> $client.DownloadFile("http://docs.uh-netlab.org/software/tool-environments/_files/vagrant-EdJL/Vagrantfile", "C:\edujlab\Vagrantfile")

   .. note::
      The full path for the destination *must* be specified in the second 
      argument to `DownloadFile`

* Create your vagrant vm using ``vagrant up`` in this directory

.. note::
  This may take a long time (20+ minutes) depending on the speed of your 
  internet connection

=================================
Load the JupyterLab web interface
=================================

* Open any web browser and load ``http://localhost:8990``
* In the Launch page of the UI, choose ``Python 3`` to open a notebook 
* In the new notebook enter ``%load_ext uhed`` in the first cell and
  press Shift and Enter at the same time to execute the command
* In the next cell, enter ``%practice`` to load a set of exercise questions

====================
Configurable Options
====================

The following environment variables can be set to change the parameters 
under which the VM is created when `vagrant up` is first executed:

+----------------------+-------------+------------------------------------------------------------+
| **Name**             | **Default** | **Description**                                            |
+----------------------+-------------+------------------------------------------------------------+
| ``te_jupyter_port``  | 8990        | Local port the Jupyter web interface will be exposed on    |
+----------------------+-------------+------------------------------------------------------------+
| ``te_ram``           | 3072        | Amount of memory available to the VM                       |
+----------------------+-------------+------------------------------------------------------------+
| ``te_cores``         | 2           | Amount of cores available to the VM                        |
+----------------------+-------------+------------------------------------------------------------+
| ``apt_cache``        | *unset*     | URL of proxy used for apt downloads                        |
+----------------------+-------------+------------------------------------------------------------+
| ``pypi_test``        | *unset*     | If set, use the test PyPI repository instead of production |
+----------------------+-------------+------------------------------------------------------------+