Docker
======

Versions
--------

The images published on Docker hub are built from the current
``master`` repository branch (tag ``latest``, will be used by default)
and from the current release (tag ``vX.Y.Z``, use
``ivre/<imagename>:vX.Y.Z`` to use it).

Images
------

IVRE ships the following Docker images (all built from the
``Dockerfile``\ s under ``docker/``):

=================== ==============================================================
Image               Role
=================== ==============================================================
``ivre/base``       Base image with IVRE and its dependencies installed;
                    parent of every other image.
``ivre/client``     CLI container, used to run ``ivre`` subcommands
                    against the database.
``ivre/web``        nginx front-end serving the Web UI static assets and
                    reverse-proxying ``/cgi/``, ``/dokuwiki/`` and
                    ``/mcp`` to the internal backends.
``ivre/web-uwsgi``  uWSGI application server running the IVRE Web API
                    (Bottle app in :mod:`ivre.web.app`).
``ivre/web-doku``   PHP-FPM container running the Dokuwiki wiki
                    integrated in the Web UI.
``ivre/web-mcp``    :doc:`../usage/mcp-server` exposed over the Streamable
                    HTTP transport, reachable through the
                    ``ivre/web`` reverse proxy at ``/mcp``. Bundles
                    Debian's ``nmap-common`` data files under
                    ``/usr/share/nmap/`` so the MCP
                    ``nmap_service_values`` tool can enumerate known
                    service names and products.
=================== ==============================================================

Using docker compose
--------------------

The easiest way, just run:

::

    $ docker compose up

The containers should now be running, with the TCP port 80 of your
host redirected to the ``ivreweb`` container.

To get a shell with the CLI tools and Python API, attach to the
``ivreclient`` container:

::

   $ docker attach ivreclient
   root@fd983ba5e6fd:/#

You can detach from the container (without stopping it) by using
``C-p C-q`` and attach to it again later with the same
``docker attach ivreclient`` command.

To initialize the database and start playing with IVRE, you need to
enter some commands described in the `related section
below <#initialization>`__.

Using Vagrant
-------------

If you already manage your Docker containers using `Vagrant
<https://www.vagrantup.com/>`__, you can use it to run the containers.

With the ``Vagrantfile`` as it is provided, the TCP port 80 of your host
will be used, so you need either to make sure it is not already in use,
or to modify the ``Vagrantfile`` after the ``cp`` step in the
instructions below to use another port.

To use the ``Vagrantfile`` located in the ``docker/`` directory of the
source tree (or the ``[PREFIX]/share/ivre/docker/`` directory when IVRE
has been installed), run (from the folder where you want to store your
data):

::

   $ mkdir -m 1777 var_lib_mongodb ivre-share dokuwiki_data
     # For people using SELinux enforced, you need to run
   $ sudo chcon -Rt svirt_sandbox_file_t var_lib_mongodb ivre-share dokuwiki_data

   $ cp [path to ivre source]/docker/Vagrantfile .
   $ vagrant up --no-parallel

The ``--no-parallel`` option prevents Vagrant from starting the
``ivreuwsgi`` container before the ``ivredb`` is ready.

To access the ``ivreclient`` container, see the `Using Docker Compose
<#using-docker-compose>`__ since it is similar.

Build the images
----------------

By default, the images will be downloaded from the Docker Hub. But you
also can build the images from the provided ``Dockerfile``\ s. For
that, from the ``docker/`` directory, run:

::

   $ for img in base client web web-doku web-mcp web-uwsgi ; do
   > docker build -t "ivre/$img" "$img"
   > done

This might take a long time.

Alternative builds for the base image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Local archive
^^^^^^^^^^^^^

It is also possible to build the ``ivre/base`` image without fetching
the *tarball* from GitHub, by creating it locally and using the
``base-local`` directory instead of ``base``. From the repository root,
run:

::

   $ git archive --format=tar --prefix=ivre/ HEAD -o docker/base-local/ivre.tar
   $ tar --owner=root:0 --group=root:0 --transform='s#^#ivre/#' -rf docker/base-local/ivre.tar ivre/_version.py
   $ docker build -t ivre/base docker/base-local

Using pip
^^^^^^^^^

Another way to create the ``ivre/base`` image is to use
`pip <https://pypi.python.org/pypi/pip>`__. From the
``docker/`` directory, run:

::

   $ docker build -t ivre/base base-pip

Initialization
--------------

Attach to the ``ivreclient`` container and run the initialization
commands:

::

   user@host:~$ docker attach ivreclient
   root@ivreclient:/# yes | ivre ipinfo --init
   root@ivreclient:/# yes | ivre scancli --init
   root@ivreclient:/# yes | ivre view --init
   root@ivreclient:/# yes | ivre flowcli --init
   root@ivreclient:/# ivre ipdata --download

Then we can integrate the Nmap results to the database
``nmap`` database and create a ``view`` from it:

::

   root@ivreclient:/# ivre scan2db -r -s MySource -c MyCategory /ivre-share
   root@ivreclient:/# ivre db2view nmap

You can then detach from the container (``C-p C-q``).

::

   root@ivreclient:/# exit

You can start the container again later by issuing:

::

   $ docker start -i ivreclient
   root@ivreclient:/#

If you do not want to exit the shell but only detach from it, use
``C-p C-q``. You can attach to it again later by issuing
``docker attach ivreclient``.
