edrixs and docker

Run edrixs in a docker container

To make life easier, we have built a docker image based on Ubuntu Linux (18.04) for edrixs, so you don’t need to struggle with the installation anymore. The docker image can be used on any OS as long as the docker application is available. Follow these steps to use the docker image:

  • Install the docker application on your system and learn how to use it.

  • Once Docker is running, create a directory to store data in your host OS and launch a container to run edrixs:

    mkdir /dir/on/your/host/os   # A directory on your host OS
    docker pull edrixs/edrixs    # pull latest version
    docker run -it -u rixs -w /home/rixs -v /dir/on/your/host/os:/home/rixs/data edrixs/edrixs
    

    it will take a while to pull the image from Docker Hub for the first time, while, it will launch the local one very fast at the next time.

    • -u rixs means using a default user rixs to login the Ubuntu Linux, the password is rixs.

    • -v /dir/on/your/host/os:/home/rixs/data means mounting the directory /dir/on/your/host/os from your host OS to /home/rixs/data on the Ubuntu Linux in the container.

  • In the container, you can play with edrixs as you are using an isolated Ubuntu Linux system. After launching the container, you will see data and edrixs_examples in /home/rixs directory. If you want to save the data from edrixs calculations to your host system, you need to work in /home/rixs/data directory:

    cd /home/rixs/data
    cp -r ../edrixs_examples .
    
    Play with edrixs ...
    

    Note that any changes outside /home/rixs/data will be lost when this container stops. You can only use your host OS to make interactive plots. Use sudo apt-get install to install software packages if they are needed.

  • Type exit in the container to exit. You can delete all the stopped containers by:

    docker rm $(docker ps -a -q)
    
  • If you do not need the image anymore, you can delete it by:

    docker rmi edrixs/edrixs
    

Connect to docker python session with Jupyter

Jupyter is a popular way to integrate your code with rich output including plots. You may find this working mode particularly useful for exploratory work, when you try many different approaches to calculations or analysis.

  • To use this follow the steps above, but pass an additional command -p 8888 when you launch the container i.e.:

    docker run -it -p 8888:8888 -u rixs -w /home/rixs -v /dir/on/your/host/os:/home/rixs/data edrixs/edrixs_interactive
    
  • the container will automatically launch a jupyter session as:

    jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root
    

    and will return a URL that you can enter in a browser on your host machine. The larger edrixs/edrixs_interactive container includes ipywidgets and ipympl for interactive computing.

    Jupyterlab provides access to a unix terminal, which you can create via File > New > Terminal. We suggest changing the terminal shell type by issuing the command bash in the terminal.

Sharing your code

Using Docker is a nice way to straightforwardly share your code with others. The standard way to specify which docker image is needed to run your code is to include a file named Dockerfile with the following contents

FROM edrixs/edrixs_interactive
USER rixs

You might like to checkout the jupyter-repo2docker project, which helps automate the process of building and connecting to docker images. The mybinder project might also be helpful as this will open a github respository of notebooks in an executable environment, making your code immediately reproducible by anyone, anywhere.