.. _docker:

Docker |macos| |linux|
======================

Docker provides an isolated container to run applications.
Our docker image for NEST also includes NESTML.

1. If you do not have Docker installed, follow the Docker
   installation instructions for your system here:
   https://docs.docker.com/install/.

   If you are using **Linux**, we **strongly recommend** you
   also create a Docker group to manage Docker as a non-root
   user. See instructions on the Docker website:
   https://docs.docker.com/install/linux/linux-postinstall/


2. Create a directory or change into a directory that you want
   to use for your project.

.. code-block:: bash

    mkdir my_nest_scripts
    cd my_nest_scripts


Usage
-----

You can use the docker images directly out of https://hub.docker.com/r/nest/nest-simulator
like this:

.. code-block:: bash

    docker pull nest/nest-simulator:<TAG>

``<TAG>`` can be a version of NEST ``2.20.2`` or later. Alternatively, you can use ``dev`` for the
development branch (master).

.. _docker_compose:

NEST 3.2 and later
------------------

As of NEST 3.2, you can use the docker-compose feature. This feature provides options to run additional applications along with NEST.

To use ``docker-compose`` you need the definition file from the git repository.
Download it:

.. code-block:: bash

    wget https://raw.githubusercontent.com/nest/nest-docker/master/docker-compose.yml

You can then run ``docker-compose up`` with one of the following options:

NEST server
~~~~~~~~~~~

.. code-block:: bash

      docker-compose up nest-server

or

.. code-block:: bash

      docker run -it --rm -e NEST_CONTAINER_MODE=nest-server -p 52425:52425 \
           nest/nest-simulator:<TAG>

Starts the NEST API server container and opens the corresponding port 52425. Test it with `curl localhost:52425/api`.
See the :ref:`nest_server` documentation for more details.

.. _docker_desktop:

NEST Desktop
~~~~~~~~~~~~

.. code-block:: bash

      docker-compose up nest-desktop

or

.. code-block:: bash

      docker run -it --rm -e NEST_CONTAINER_MODE=nest-server -p 52425:52425 \
          nest/nest-simulator:<TAG>
      docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -p 54286:54286 \
          -e NEST_CONTAINER_MODE=nest-desktop nest/nest-simulator:<TAG>

Starts the NEST server and the NEST desktop web interface. Port 54286 is also made available.
Open NEST Desktop in the web browser using the following http link: `http://localhost:54286`

Visit the :doc:`NEST Desktop <desktop:index>` documentation to learn more.

Jupyter notebook with NEST
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

      docker-compose up nest-notebook

or

.. code-block:: bash

      docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -e NEST_CONTAINER_MODE=notebook \
          -p 8080:8080 nest/nest-simulator:<TAG>

Starts a notebook server with pre-installed NEST. The corresponding URL is displayed in the console. You can copy an
d paste into your browser.


Jupyter lab with NEST
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

      docker-compose up nest-jupyterlab

or

.. code-block:: bash

      docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -e NEST_CONTAINER_MODE=jupyterlab \
          -p 8080:8080 nest/nest-simulator:<TAG>

Starts a Jupyter lab server with pre-installed NEST. The corresponding URL is displayed in the console.
Copy and paste the URL into your browser.

Remove container
----------------

To stop and delete running containers use ``docker-compose down``.

To run NEST 2.20.2
------------------

Jupyter notebook with NEST 2.20.2:

.. code-block:: bash

    docker run -it --rm -e LOCAL_USER_ID=`id -u $USER` -v $(pwd):/opt/data -e NEST_CONTAINER_MODE=notebook \
               -p 8080:8080 nest/nest-simulator:2.20.2

NEST dev
--------

If you want to use the compose configuration for the ``dev`` NEST version, you can use the following file option:

.. code-block:: bash

    wget https://raw.githubusercontent.com/nest/nest-docker/master/docker-compose-dev.yml
    docker-compose -f docker-compose-dev.yml up nest-notebook

You can specify the container mode (nest-noteobook, nest-desktop, nest-server, or nest-jupyterlab)
This will download the docker image with the pre-installed
NEST master from https://hub.docker.com/r/nest/nest-simulator and start it.
After booting, a URL is presented. Click on it or copy it to your browser.


.. _docker_win:

Run NEST on Windows |windows|
-----------------------------

.. important::

    The following commands should work on Windows. Please note that NEST does not officially
    support Windows!

.. code-block:: bash

    docker run -it --rm -v %cd%:/opt/data -p 8080:8080 -e NEST_CONTAINER_MODE=<args> \
        nest/nest-simulator:<TAG>

In Powershell, '%cd%' might not work for the current directory. Then
you should explicitly specify a folder with existing write permissions.

In any case, this will download the docker image with the pre-installed
NEST master from https://hub.docker.com/r/nest/nest-simulator and start it.
After booting, a URL is presented. Click on it or copy it to your browser.
Voilá! Jupyter notebook starts from the docker image.

You can update the image with:

.. code-block:: bash

    docker pull nest/nest-simulator:<TAG>



For more information, you can checkout the `nest-docker repository <https://github.com/nest/nest-docker>`_

.. |linux| image:: ../static/img/linux.png
   :class: no-scaled-link
   :scale: 15%

.. |macos| image:: ../static/img/macos.png
   :class: no-scaled-link
   :scale: 15%


.. |windows| image:: ../static/img/windows.png
   :class: no-scaled-link
   :scale: 15%
