Installing ecco

Using ecco as a Docker image

The simplest way to use ecco is to start it from its Docker image. To do so, there are three solutions:

• run image online using play with Docker
• run image on your computer using a helper script
• run image on your computer using Docker command line interface

Zero installation

This solution is well suited if you just want to try ecco. Docker offers an online playground with 4h of time to run whatever you want.

• go to Play with Docker
• log in to the service, using one of the proposed accounts
• click the Start button
  • if the server is overloaded you get an error message, just go back and click Start again
  • you eventually get a page with a 4 hours countdown
• click +ADD NEW INSTANCE on the left
• after a few seconds, you get a shell (large black rectangle filled with gibberish)
• at the prompt $ type or copy/paste docker run -p 8000:8000 franckpommereau/ecco jupyterhub
  • this will display a bunch of progress bars
  • wait until it’s all finished (it may take a loooong time)
  • ecco is ready to use when you see a line starting with a timestamp and ending with JupyterHub is now running at http://:8000
• click OPEN PORT at the top of the page and type 8000 at the prompt
  • alternatively, wait for a link 8000 to appear next to the button and click on it
• this pops-up a new browser window
  • log in as user ecco with password ecco
  • you get a working Jupyter with ecco installed
  • either upload your notebook and files or go to folder doc to get some examples
• when you are done with ecco, go back to Play with Docker and click CLOSE SESSION

Launching script

To run ecco Docker image on your machine, you must first install Docker. Then, you can download and run this Python script that will take care of running Docker with the right options. Run python ecco.py --help to see the available options for the script:

• -t TAG run a specific version (e.g. 0.4, default: latest)
• -p PORT run Jupyter on specific port (default: 8000)
• -n do not launch web browser
• -g start Desktop integration GUI
• -m DIR mount local directory DIR into the Docker container
• COMMAND... run a specific command (default: jupyter-notebook)

For instance, running python ecco.py -m . will run Jupyter notebook server (without JupyterHub) and give it access to the current directory. When the server is ready, Jupyter opens in the default browser.

The first time ecco is started, Docker will have to download the image to run, just like in the previous solution, and this will take a long time. However, these images will be stored on your computer and the next startup will be almost instantaneous.

To use desktop integration, first install Python package PySide2 and run python ecco.py -g -n on your session startup to run a background instance of the container and install an icon in the system tray. Clicking on this icon allows to open the browser onto the Jupyter server.

Invoking Docker manually

If you wish to start ecco Docker image manually, run docker run -p 8000:8000 franckpommereau/ecco jupyterhub then point your browser to http://localhost:8000 and log in as user ecco with password ecco.

The Docker command above runs ecco on the top of a multi-user JupyterHub installation, you may reconfigure it according to you needs (in particular, to add users and data persistence) for a production usage.

You may also want to run

docker run -p 8000:8000 -u ecco -w /home/ecco franckpommereau/ecco jupyter-notebook --no-browser --port=8000 --ip=0.0.0.0

to start only Jupyter Notebook without JupyterHub.

To run a specific version of ecco, use docker run ... franckpommereau/ecco:VERSION ... where version is one of the tags listed on Docker hub repository.

Installing ecco

ecco has a lot of dependencies, the best way to install it is to follow the content of the distributed Dockerfile. Every line starting with RUN is a shell command that should be run in order to install the varied dependencies and ecco itself at the end. These commands are mainly apt-get commands for (Debian) system packages that should be installed, or pip3 commands for Python packages that should be installed.

The tricky part is to install pyddd and pyits because they rely on libraries that are very hard to get compiled in a way that is suitable for Python use. To simplify this part of the installation, we provide precompiled binaries but they may not work everywhere, in which case it is necessary to install libITS manually.