.. _edrixsanddocker:

*********************
EDRIXS and docker
*********************

Run EDRIXS in a docker container
--------------------------------

To make life easier, we have built a Docker image based on Ubuntu Linux 24.04
for EDRIXS, so you do not need to install its compiler toolchain yourself.
The image is published for both AMD64 and ARM64 systems.
The ``latest`` tag tracks the latest stable release. For reproducible work,
pin a release tag such as ``edrixs/edrixs:v0.1.3``.
The docker image can be used on any OS as long as the `docker <https://www.docker.com/>`_ application is available.
Follow these steps to use the docker image:

* Install the `docker <https://www.docker.com/>`_ application on your system.

* Once Docker is running, create a directory to store data and create a file called ``docker-compose.yml`` with contents ::

    services:
      edrixs-jupyter:
          image: edrixs/edrixs
          volumes:
            - ./:/home/rixs
          working_dir: /home/rixs
          ports:
            - 8888:8888
          command: "jupyter lab --ip=0.0.0.0 --port=8888 --no-browser --allow-root"
      edrixs-ipython:
          image: edrixs/edrixs
          volumes:
            - ./:/home/rixs
          working_dir: /home/rixs

  and execute ::

    docker compose up

  This will return a URL, which you can open to connect to the Jupyter session.

* If you would like to access a terminal rather than jupyter run ::

    docker compose run --rm edrixs-ipython


Use the docker image as a Dev Container
----------------------------------------

You can use the EDRIXS docker image as a `Dev Container
<https://containers.readthedocs.io/>`_ in VS Code or GitHub Codespaces without
cloning the full repository. Create a file ``.devcontainer/devcontainer.json``
in your project with the following contents ::

    {
        "name": "edrixs",
        "image": "edrixs/edrixs"
    }

Open the project in VS Code with the `Dev Containers
<https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers>`_
extension installed and choose **Reopen in Container** when prompted.

See :ref:`devcontainer` for more details on using Dev Containers with EDRIXS.

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

You might like to checkout the `jupyter-repo2docker
<https://repo2docker.readthedocs.io/en/latest/>`_ project, which helps automate the process of building and connecting to docker images. The `mybinder <https://mybinder.org/>`_ project might also be helpful as this will open a github repository of notebooks in an executable environment, making your code immediately reproducible by anyone, anywhere.