Installation#

GFINDER software, application data and SPICE kernels are installed on MOS JupyterHub.

Note

  • GFINDER is currently usable as single-user application installed on user’s local machine. However it is intended to be used a multi-user web application. To that end, a staging VM has been setup to test developing solutions.

  • In order to facilitate the installation, update and deployment of GFINDER, it is intended to be packaged it into Docker container(s). Meanwhile, better installation, update, and starting scripts shall be provided.

Software requirements#

  • Python 3.7+

  • Git

  • conda

  • Pandoc (required for PDF documentation generation)

  • node.js (required to use Plotly in JupyterLab)

Note

JupyterLab is required on the staging/production virtual machine (VM) environment. Otherwise, it should be installed together with GFINDER Python modules and other dependencies on a single-user computer environments.

Known working environments:

  • OS: OS X, Linux

  • CPU: 64bit

Deployment environments#

  • User’s local machine (development environment)

  • MAJIS MORS staging VM at IAS (majis-operation-simulator-rec.ias.u-psud.fr)

  • MAJIS MORS VM at IAS (for GFINDER v1.0 and above)

Note

Ideally the MAJIS MORS VM domain names should be shorter and easier to remember, eg: majis-sciops.ias.u-psud.fr.

Steps#

Follow these steps to install and configure GFINDER on your local machine (notes are provided for staging VM). If you encounter any problem, go to troubleshooting.

1. Create your working directory#

Your working directory is where GFINDER source code and application data will be installed. It also from where you will be starting and using GFINDER:

mkdir {/path/to/working_directory}

2. Setup Python virtual environment#

Create, and activate, your virtual environment in your working directory:

cd {/path/to/working_directory}
virtualenv venv
. venv/bin/activate

3. Download and install GFINDER software package#

Download the gfinder-python-cli package in your working directory:

git clone https://git.ias.u-psud.fr/majis_sgs_mos/gfinder-python-cli.git

Install GFINDER and Python dependencies:

pip install --editable gfinder-python-cli

Test GFINDER CLI:

gfinder --version
gfinder, version 0.6.0

4. Download and install JupyterLab dependencies#

Plotly JupyterLab support (Python 3.5+)

For use in JupyterLab, install the jupyterlab and ipywidgets packages using pip:

pip install jupyterlab "ipywidgets>=7.5"

Then run the following commands to install the required JupyterLab extensions to be installed:

# JupyterLab renderer support
jupyter labextension install jupyterlab-plotly@4.11.0

# OPTIONAL: Jupyter widgets extension
jupyter labextension install @jupyter-widgets/jupyterlab-manager plotlywidget@4.11.0

ipyleaflet JupyterLab support

For use in JupyterLab, install the nbextension and labextension extensions:

jupyter nbextension enable --py --sys-prefix ipyleaflet  # can be skipped for notebook 5.3 and above
jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-leaflet

5. Download SPICE Kernels#

The SPICE kernels directory is where the ESA’s JUICE SPICE Kernel Dataset (SKD) will be located. We recommend you to create the spice_kernels directory in your working directory like so:

mkdir {/path/to/working_directory}/spice_kernels

If you choose to create it outside of your working directory for whatever reason, then do so and create a symbolic link like so (it will be handy to browse its content from JupyterLab):

cd {/path/to/working_directory}
ln -s {/path/to/spice_kernels} spice_kernels

Download the ESA’s JUICE SKD:

cd {/path/to/working_directory}/spice_kernels
git clone https://repos.cosmos.esa.int/socci/scm/spice_kernels/juice.git

6. Setup GFINDER Data Store#

Download the gfinder-data package in your working directory:

cd {/path/to/working_directory}
git clone https://git.ias.u-psud.fr/majis_sgs_mos/gfinder-data.git

Note

Tagging and/or branching of the gfinder-data package repository should be defined and implemented so that users can use application data relevant to different GFINDER versions and purposes (eg: testing, training, operations).

7. Install SPICE utility programs (optional)#

SPICE offers utility programs to produce, manage, manipulate or summarize SPICE kernels. They are available for the following computer environments:

  • MacIntel_OSX_32bit

  • MacIntel_OSX_64bit

  • PC_Cygwin_32bit

  • PC_Cygwin_64bit

  • PC_Linux_32bit

  • PC_Linux_64bit

  • PC_Windows_32bit

  • PC_Windows_64bit

  • SunIntel_32bit

  • SunIntel_64bit

  • unSPARC_32bit

Download SPICE utility programs matching the target computer environment, eg:

cd {/path/to/working_directory}
mkdir spice
cd spice
wget --ftp-user=anonymous ftp://naif.jpl.nasa.gov/pub/naif/utilities/{MacIntel_OSX_64bit}/*
chmod u+x *

Set PATH to SPICE utility programs:

export PATH=${PATH}:'{/path/to/working_directory}/spice'

Test it by running the brief command.

8. Configure default settings and starting script#

Copy the start_gfinder.sh shell script in your working directory:

cd {/path/to/working_directory}
cp gfinder-python-cli/start_gfinder.sh .

Edit your start_gfinder.sh copy to change the path to the JUICE SPICE kernels and Data Store directories, and other default parameters (eg: mission scenario ID).

Set required environment variables by the running the following commands:

export GFINDER_KERNELS_DIR='{/path/to/working_directory}/spice_kernels/juice/kernels/'
export GFINDER_DATA_DIR='{/path/to/working_directory}/gfinder-data'
export GFINDER_MISSION_SCENARIO_ID='CREMA30'
export GFINDER_MAPSERVER_URL='http://127.0.0.1:8000'

Note

export GFINDER_MAPSERVER_URL='http://majis-operation-simulator-rec.ias.u-psud.fr:8124' on MAJIS MORS staging VM.

9. Create your Notebooks directory#

Copy the /gfinder-python-cli/docs/source/notebooks/ into your working directory:

cp -R gfinder-python-cli/docs/source/notebooks/ notebooks

10. Test GFINDER CLI and Python environment#

Run JupyterLab server from your working directory:

jupyter lab &

Note

jupyter lab --ip=0.0.0.0 --port=8123 & on MAJIS MORS staging VM.

You’re ready to use the GFINDER CLI, and the Python API for visualisation of calculation results in JupyterLab from http://localhost:8888/lab.

Note

http://majis-operation-simulator-rec:8123/?token=<token> if installed on MAJIS MORS staging VM, where <token> is a token issued by JupyterLab every time the server starts, eg.: token=167df844346fee5d9940ffb1de9961f4d0d494b207f0fccf.

When are done testing, shut down JupyterLab and deactivate GFINDER virtual environment by simply running the deactivate command.

11. Setup GFINDER Web Application#

Warning

The GFINDER Web Application is in development and not yet functional.

From the gfinder-python-cli/gfinder_web directory:

Create an admin user with a password of your choice:

python manage.py createsuperuser --email admin@example.com --username admin

Make sure to set the GFINDER_MAPSERVER_URL environment variable correctly (see start_gfinder.sh above).

Run Django server:

python manage.py runserver

Note

python manage.py runserver 0.0.0.0:8124 & on MAJIS MORS staging VM.

You’re ready to test the GFINDER Web Viewer and REST API from the following URLs:

Note

When installed on MAJIS MORS staging VM: