.. _docker_install:

Installing with Docker (recommended)
************************************

Pulling the Docker Image
========================
With Docker installed, run the following command to pull the newest version of
the ImmuneDB Docker image:

.. code-block:: bash

    $ docker pull  ghcr.io/arosenfeld/immunedb


.. _running-the-container:

Running the Container
=====================
To start a shell session within the container run:

.. code-block:: bash

    $ docker run -v $HOME/immunedb_share:/share \
        -p 8080:8080 -it arosenfeld/immunedb

This will start a shell with ImmuneDB and accessory scripts pre-installed as
well as create a shared directory between the host and Docker container.  Files
placed in the host's ``$HOME/immunedb_share`` directory and it will appear in
``/share`` within the Docker container (and vice versa).  Note ``$HOME`` on
macOS is generally ``/Users/your_username/`` and on Linux it is generally
``/home/your_username``.

Additionally, MySQL stores its data in ``/share/mysql_data`` so databases will
persist across multiple container invocations.

The location of important files are:

- ``/root/germlines``: IMGT aligned germlines for IGH, TCRA, and TCRB.
- ``/apps/bowtie2/bowtie2``: The local-alignment tool Bowtie2.  This file is in
  the container's ``$PATH``.
- ``/share/configs``: The recommended directory to store ImmuneDB
  configurations generated by ``immunedb_admin create``.
- ``/share/mysql_data``: The location MySQL (specifically MariaDB) will store
  its data.
- ``/example``: A set of example input data to familiarize yourself with
  ImmuneDB.

Running ImmuneDB
====================
Once the Docker container is running, you should continue by testing out the
:ref:`example pipeline <pipeline_example>`.