.. _tutorial-setup:

*********************
Setup the Tutorials
**********************


In order to reduce the friction of first compiling a lot of applications before getting your hands dirty, we provide some scripts and a `Dockerfile` which should work in most Linux machines.
If you run into problems, feel to `raise an issue <https://gitlab.bsc.es/jvinyals/beppp-tutorials/-/issues/new>`_.

Requirements
===============================================

* Please make sure that you have a working `docker installation <https://docs.docker.com/engine/install/>`_
* We assume you have a GNU/Linux system to run the tutorials, some things might be different if you run on Windows
* As we run parallel applications, your machine should at least have 2 physical cores. We recommend minimum 6.


Setting up the environment
===============================================

First, we clone the repository and change directory into it:

.. code-block:: bash

    git clone https://gitlab.bsc.es/jvinyals/beppp-tutorials.git
    cd beppp-tutorials

To build the docker image we run:

.. code-block:: bash

    docker build --rm -t beppp-tutorials:latest ./docker


The ``--rm`` flag tells docker to remove the intermediate containers after a successful build.
We tag the newly build image with ``beppp-tutorials:latest`` and use the ``Dockerfile`` from the path ``./docker``

.. note::

    As we bootstrap and update the OS and install the tools manually, this can take some time.


Once this is finished we can quickly test if everything went smoothly, by trying to run a container from the freshly build image interactively:

.. code-block:: bash

    docker run --rm=true --name=beppp-tutorials -v $(readlink -f ./demo):/home/ubuntu/demo bsc-tools:latest

The ``--rm`` flag tells docker to remove the container with the name ``beppp-tutorials`` if it exists.
The ``-it`` tells docker to run an interactive session using a pseudo-TTY.
The ``-v $(readlink -f ./demo):/home/ubuntu/demo`` mounts the ``./demo`` path into the container at ``/home/ubuntu/demo``
You should be prompted with the following line:

.. code-block:: bash

    ubuntu@<somehash>:~$

From here you can do an ``ls`` and you should see the following output:

.. code-block:: bash
    ubuntu@1c4e5645fbb7:~$ ls
    demo  dlb  tracing

to return to your host computer and exit the container, just type ``exit``.

Using the GUI
-------------------------------

In order to use the GUI of :ref:`Paraver <paraver>`, we need to persuade the x11 system of your machine a bit and add some flags when running the docker container.

First of all you need to allow unauthorized requests to your x-server by typing

.. code-block:: bash

    xhost +



.. note::

    To enable the access control again just execute ``xhost -``


Now we can tell docker to use the ``$DISPLAY`` variable of your host system as well as expose the x-sever socket and bind it into the container.

To do this we add a few parameters to our ``docker run`` invocation:

.. code-block:: bash

    docker run --rm=true --name=beppp-tutorials \
    -v $(readlink -f ./demo):/home/ubuntu/demo \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix/:/tmp/.X11-unix \
    -it \
    beppp-tutorials:latest \



Now you should be able to start **Paraver** by typing ``wxparaver`` into the command line of the docker container.

Using performance counters
-------------------------------

As **Extrae** uses `PAPI <https://icl.utk.edu/papi/>`_ to collect hardware counters, which requires evelvated privileges we need to add the ``--privileged`` flag into the docker command to end up with:

.. code-block:: bash

    docker run --rm=true --name=beppp-tutorials \
    -v $(readlink -f ./demo):/home/ubuntu/demo \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix/:/tmp/.X11-unix \
    --privileged \
    -it \
    beppp-tutorials:latest