This page assumes you are working standalone on your own laptop or desktop. To get started using Firefly inside the LSST Science Platform, see Getting Started.

Using Firefly in a standalone environment¶

Using lsst.display.firefly in a standalone environment, such as your laptop or desktop, is a supported use case. This page lays out how to use Docker to set up a fully functional environment to use the LSST Science Pipelines together with Firefly on your own machine.

Installing a Docker image of Science Pipelines¶

Instructions for using Docker images of the LSST Science Pipelines are available on the pipelines.lsst.io site. These images contain the Science Pipelines software (known colloquially as “the stack”) but do not contain Jupyterlab or the Firefly extension for Jupyterlab. This section shows how to install all these pieces for the example of the sixth weekly build of 2019, assuming you have already installed Docker and have it available on your machine.

First, change your directory to one that you want to mount inside your Docker container. Then, install the weekly build, taking care to leave ports open for Jupyterlab and optionally for other services.

docker run -itd -p 9888:9888 -p 9889:9889 -p 9890:9890 -v `pwd`:/home/vagrant/mnt --name lsst_w_2019_06 lsstsqre/centos:7-stack-lsst_distrib-w_2019_06

You will be able to use docker stop and docker start together with the name lsst_w_2019_06 to start and stop your Science Pipelines container.

Second, in a terminal window on your machine, open a shell inside the container.

docker exec -it lsst_w_2019_06 /bin/bash

From the container’s shell, set up Science Pipelines which includes Python and the conda distribution manager.

source /opt/lsst/software/stack/loadLSST.bash
setup lsst_distrib

This third step is needed only the first time you are setting up a Science Pipelines container, to install Jupyterlab and the Firefly Jupyterlab extension.

conda install jupyterlab nodejs ipywidgets
npm install —global babel-cli
jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension install jupyter_firefly_extensions
pip install jupyter_firefly_extensions
jupyter serverextension enable --py jupyter_firefly_extensions

Running a Docker image of Firefly¶

The commands in this section are run in a terminal on your machine, and not inside the container’s shell.

Start a Firefly server with 8 GB of memory on port 8080:

docker run -p 8080:8080 -e "MAX_JVM_SIZE=8G" --rm ipac/firefly:lsst-dev

In this case, the URL for Firefly will be http://localhost:8080/firefly.

Alternatively, to run it in the background on port 8090, saving logging information to a file:

docker run -p 8090:8080  -e "MAX_JVM_SIZE=8G" --rm ipac/firefly:lsst-dev >& my.log &

Useful Docker commands may be found in this cheat sheet.

Starting Jupyterlab¶

The commands in this section are to be used in your container’s shell. - For the Firefly Jupyter extension to work, you must set an environment variable or edit a configuration file to indicate how to connect to your Firefly server. To enable callbacks to work properly, it is recommended to find the network address of your machine and use that to set the FIREFLY_URL environment variable. On a Macintosh computer, that is found in System Preferences under Network.

export FIREFLY_URL=http://10.8.12.110:8080/firefly

Typically you will want to start Jupyterlab from the directory that you mounted inside your container, /home/vagrant/mnt.

cd /home/vagrant/mnt
jupyter lab --ip 0.0.0.0 --port 9888

Jupyterlab prints a long URL to copy and paste into a browser window on your machine. Typically what is printed needs some editing to start with 127.0.0.1. After pointing your web browser to the Jupyterlab URL, your Jupyterlab session will appear.

Removing the Firefly Jupyterlab extension¶

The Firefly Jupyterlab extension has not been extensively tested with this standalone setup with two Docker containers, one for the Science Pipelines and Jupyterlab, and one for Firefly. You may find it desirable or even necessary to disable the extension to use lsst.display.firefly.

To disable and uninstall the extension, issue these commands in your Science Platform container’s shell.

jupyter serverextension disable --py jupyter_firefly_extensions
pip uninstall jupyter_firefly_extensions
jupyter labextension uninstall jupyter_firefly_extensions

Listing installed extensions¶

Inside your Science Pipeline container’s shell, you can list the extensions that are installed for Jupyterlab.

jupyter labextension list
jupyter serverextension list

The server extension list will also indicate whether the extension is enabled.

Navigation