Installation
============

IMMP uses the latest and greatest Python features (that is, native ``async``/``await`` syntax and
asynchronous generators), and therefore requires at least **Python 3.6**.

From PyPI
---------

Install the core module from `PyPI <https://pypi.org/project/IMMP/>`_:

.. code-block:: console

    $ pip install immp

This only pulls in the core requirements; it doesn't include dependencies for most plugs and hooks,
see below for how to obtain them.

From the repo
-------------

Check out a copy of the repository from `GitHub <https://github.com/Terrance/IMMP>`_:

.. code-block:: console

    $ git clone git@github.com:Terrance/IMMP.git
    $ cd IMMP

Then install IMMP as a link to the checkout:

.. code-block:: console

    $ pip install -e .

If you don't intend to work on the code and just want the bleeding edge, you can alternatively
install with pip directly:

.. code-block:: console

    $ pip install git+https://github.com/Terrance/IMMP.git

With dependencies
-----------------

For Python library dependencies, review the :ref:`appendix/index:Python requirements` to see what
each plug and hook needs.

The setup script defines a number of *extras* which can be used to pull in one or more categories
of requirements:

.. code-block:: console

    $ pip install immp[runner,uv,db,web,webui,console,sync,discord,hangouts,slack,telegram]

If installed from the repo, replace ``immp`` with ``.`` as above to use the current directory.

Alternatively, you can just install all possible dependencies with the included requirements file:

.. code-block:: console

    $ pip install -r requirements.txt

Using Docker
------------

A Dockerfile is included in the repo, and an image can be built using the standard commands (here
assuming you have configured Docker to accept commands from non-root users):

.. code-block:: console

    $ docker build . --tag immp

To run it, you need to bind a config file to ``/data/config.yaml``.  If you need auxiliary files,
you can bind-mount the entire ``/data`` directory to provide them from the host:

.. code-block:: console

    $ docker run --mount type=bind,source=/var/lib/immp,target=/data immp

IMMP will be run using ``/data`` as its working directory, so you can reference other files from
your config without needing to specify the full path.  This will run without the ``-w`` flag, so
config changes will not be written back on exit -- override the command if you need this.

Note that Docker mounts don't allow changing the owner or group, and will default to UID/GID 1000.
This means the files on the host must be writeable by UID 1000, or be world-writeable.  If your
host owner or group is different, you can set the ``uid`` and ``gid`` build args to match:

.. code-block:: console

    $ docker build --build-arg uid=1002 --build-arg gid=1001 . --tag immp