Containers and clusters
=======================

.. versionadded:: 0.9.0
    `LiberTEM repository on Docker Hub
    <https://hub.docker.com/r/libertem/libertem/tags>`_ with images
    for public use.

.. versionchanged:: 0.12.0
    Container images are now available from `the GitHub container registry
    <https://ghcr.io/libertem/libertem>`_ instead.

.. note::
    The LiberTEM server will only bind to localhost by default, unless
    token-based authentication is enabled or the :code:`--insecure` flag is
    provided. It should run behind a reverse proxy that supplies the token and
    adds encryption, authentication and authorization when access from an
    untrusted network is desired. :ref:`jupyter integration` can be used for
    that.
    
    Third-party commands like :code:`dask-scheduler` may bind to public
    interfaces by default, which can expose a machine to remote code execution.
    For that reason the interface should always be specified and limited to
    trusted networks.
    
    Furthermore, the default command of the LiberTEM Docker container starts a
    server that binds to all interfaces to facilitate integration. Docker runs
    containers in an isolated environment and requires the user to expose the
    port explicitly. Singularity, however, will run the container like a regular
    user program. That means it exposes an insecure LiberTEM server to all
    interfaces when running the default container command. For that reason the
    command to run should always be specified explicitly when using Singularity.

.. _`containers`:

Containers
----------

Docker images can be found in `the LiberTEM repository on the GitHub contrainer registry
<https://ghcr.io/libertem/libertem>`_. LiberTEM is
installed in a virtual environment in :code:`/venv/` in the Docker image. The
executables :code:`libertem-server`, :code:`dask-scheduler` and
:code:`libertem-worker` can be found in :code:`/venv/bin/`, consequently. The
container runs :code:`/venv/bin/libertem-server --host 0.0.0.0 --insecure --port 9000`
by default.

When using Docker, you can run and expose the LiberTEM server to
:code:`localhost` while accessing local data like this:

.. code-block:: shell

    $ docker run -p 127.0.0.1:9000:9000 \
      --mount type=bind,source=/path/to/your/data/,dst=/data/,ro ghcr.io/libertem/libertem

To use the Docker image and Singularity to start :code:`libertem-server`:

.. code-block:: shell

    $ singularity exec docker://ghcr.io/libertem/libertem /venv/bin/libertem-server

Available versions
..................

The tag "latest" (default) points to the stable release with the highest version
number. Version tags for all stable releases are available as well. See `the LiberTEM
contrainers on the GitHub container registry <https://ghcr.io/libertem/libertem>`_ for
details.

.. note::

    Older versions are also available on `Docker Hub
    <https://hub.docker.com/r/libertem/libertem/tags>`_.

Updating
........

You can update to the latest release like this:

.. code-block:: shell

    $ docker pull ghcr.io/libertem/libertem

or

.. code-block:: shell

    $ singularity pull docker://ghcr.io/libertem/libertem

.. _`cluster`:

Starting a custom cluster
-------------------------

LiberTEM can connect to a running Dask cluster. To start a cluster on
:code:`localhost`, first run a scheduler:

.. code-block:: shell

    (libertem) $ dask-scheduler --host localhost

GPU support in LiberTEM requires specific resource tags and environment settings
on the dask workers. The easiest way to start workers with the appropriate
settings is

.. code-block:: shell

    (libertem) $ libertem-worker tcp://localhost:8786

There are a few command line options available:

.. include:: ../autogenerated/libertem-worker.help
    :literal:

.. versionadded:: 0.6.0
.. versionadded:: 0.9.0
    :code:`--preload` was added.

For a cluster setup, you can run the scheduler on the appropriate network interface and
run workers on all cluster nodes to connect to the scheduler.

You can then connect to the cluster's scheduler URL in the LiberTEM web GUI.

For easier deployment of in container-based environments, you can also use the
Docker image.

Example: Start a scheduler and workers in an isolated environment with Docker.

.. code-block:: shell

    $ docker run --mount type=bind,source=/path/to/your/data/,dst=/data/,ro \
      ghcr.io/libertem/libertem /venv/bin/dask-scheduler
    $ docker run --mount type=bind,source=/path/to/your/data/,dst=/data/,ro \
      ghcr.io/libertem/libertem /venv/bin/libertem-worker tcp://<scheduler-addr>:8786

Example: Start a scheduler and workers in the context
of the local user with Singularity.

.. code-block:: shell

    $ singularity exec docker://ghcr.io/libertem/libertem /venv/bin/dask-scheduler --host localhost
    $ singularity exec docker://ghcr.io/libertem/libertem /venv/bin/libertem-worker tcp://localhost:8786