Install the FABRIC Python API

Most users will start using FABRIC via our pre-configured JupyterHub environment. However, advanced users might want to install the Python API on their laptop or a server. This article describes how to install the FABRIC Python API on your machine and use it in standard Python applications or even by running Jupyter notebooks locally.

This example shows how install the FABRIC API and run the Jupyter example suite in a Python virtual environment on your local machine.

The FABRIC API is available in the following github repo https://github.com/fabric-testbed/fabric-cli.

Prerequisites

• Python 3.9

IMPORTANT: Using a Python version less than 3.9 is the most common issue that prevents users from successfully deploying the FABRIC API locally.

Setup

Check your Python3 version. If it is less than 3.9 you need to upgrade.

bash-3.2$ python3 --version 
Python 3.9.2

Use pip3 to install the python virtual environment software

bash-3.2$ pip3 install virtualenv virtualenvwrapper

Start a python virtual environment to contain your experiments

bash-3.2$ virtualenv fabric-jupyter
created virtual environment CPython3.9.0.final.0-64 in 551ms
  creator CPython3Posix(dest=/Users/pruth/git/fabric-jupyter, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/Users/pruth/Library/Application Support/virtualenv)
    added seed packages: pip==21.2.3, setuptools==57.4.0, wheel==0.37.0
  activators BashActivator,CShellActivator,FishActivator,PowerShellActivator,PythonActivator
bash-3.2$ source fabric-jupyter/bin/activate
(fabric-jupyter) bash-3.2$ 

Install the FABRIC testbed CLI/API

(fabric-jupyter) bash-3.2$ pip3 install fabrictestbed

Configure the Environment

Set the environment variables to point to the the FABRIC Credential Manager and Orchestrator hosts

(fabric-jupyter) bash-3.2$ export FABRIC_CREDMGR_HOST=cm.fabric-testbed.net
(fabric-jupyter) bash-3.2$ export FABRIC_ORCHESTRATOR_HOST=orchestrator.fabric-testbed.net

Use the portal to Generate a FABRIC token.

To generate a new token, click “Create Token”

You new token has been created. Download or cut/paste your new token to a file in a known location on your local machine.

This token is valid for 24 hours. If you want to use FABRIC tomorrow you will need to generate another token.

Save the token in a file on the local machine. Do not remove the json information in the file. Set the environment variable to point to the json file containing your new token.

(fabric-jupyter) bash-3.2$ export FABRIC_TOKEN_LOCATION=/Users/pruth/.fabric_token.json

At this point your environment is ready to run an application using the FABRIC API. If you have an existing FABRIC application you can run it now and skip the rest of this article. If you want to use FABRIC via a local Jupyter notebook continue reading.

Install Jupyter in the Virtual Environment

Install Jupyter in the virtual environment using pip3.

(fabric-jupyter) bash-3.2$ pip3 install jupyter

Run the FABRIC Jupyter-examples Notebook Suite

Clone the github repo that include the example notebooks.

(fabric-jupyter) bash-3.2$ git clone https://github.com/fabric-testbed/jupyter-examples.git

Many of the examples use paramiko to access your FABRIC slices via ssh. Optionally, install paramiko if you want use in notebooks that require it.

(fabric-jupyter) bash-3.2$ pip3 install paramiko

Some of the examples use bash. You can install the Jupyter bash kernel if you want to use these notebooks.

(fabric-jupyter) bash-3.2$ pip3 install bash_kernel
(fabric-jupyter) bash-3.2$ python -m bash_kernel.install

Run the FABRIC table of contents notebook.

(fabric-jupyter) bash-3.2$ jupyter-notebook jupyter-examples/start_here.ipynb 

This should load the notebook in a new browser tab. You can now click any notebook to open it in another browser tab.

Trouble Shooting

Error: No module named ‘fabrictestbed’

Upgrading to Python 3.9 occasionally causes errors when importing the FABRIC Python modules. If you see the following error when trying to import the fabrictestbed module the solution is below.

This might have been caused by installing Jupyter when another version of Python was set as the default. Check the Jupyter kernel config file here: /usr/local/share/jupyter/kernels/python3/kernel.json. Edit the Python path to lead to python3.9

{
 "argv": [
  "/usr/local/bin/python3.9",
  "-m",
  "ipykernel_launcher",
  "-f",
  "{connection_file}"
 ],
 "display_name": "Python 3 (ipykernel)",
 "language": "python",
 "metadata": {
  "debugger": true
 }
}