.. _cli-deploy-reference:

CLI Deployment Options
======================

There are a few ways to use the ``deploy`` command from the :ref:`cli-reference`
that we haven't looked at until this point. In this tutorial we will look at
those, to make sure you have a good idea of the options you have available.

.. Note:: Always remember the ``--help`` option. It can be used with each command as well
    as the whole ``mvi`` command-line app to get a description of what options you
    have. If you are unsure how and what-for a certain command is used, it should
    be your go-to option.

So far, we have only deployed services from project directories, but there are
a few more options. First of all, it is possible to deploy a service from a tarball
(.tar.gz file), which is actually what is been happening behind the scenes.

There's also two options for deployment source: ``--git`` which deploys a
service given a git repository with the same contents as the services we
have deployed so far. It is functionally identical to deploying from a
local directory. For now, it only supports public git repositories:

>>> mvi deploy --git my_service 1.0.0 https://github.com/sclorg/django-ex
Active host: http://your-host
Deploying service...
Service deployed successfully
MAIN    NAME        VERSION    STATUS    RUNNING
------  ----------  ---------  --------  -----------------------------------
*       my_service  1.0.0      running   Running (since 2020-11-23 16:56:06)

The ``--image`` option can be used to deploy any docker image as an MVI service.
This can be useful for deploying applications that are not written using the
SDK within the MVI framework. Similar to the ``--git`` option it only supports
public images for now. Keep in mind that most pre-build images will not
support the automatic interactive documentation:

>>> mvi deploy --image my_service2 1.0.0 traefik/whoami --port 80
Active host: http://your-host
Deploying service...
Service deployed successfully
MAIN    NAME         VERSION    STATUS    RUNNING
------  -----------  ---------  --------  -----------------------------------
*       my_service2  1.0.0      running   Running (since 2020-11-23 16:57:55)

In the last command we used an optional argument to change the internal port of
the service container. This is not required when deploying services locally or
from git repositories, but it might be necessary when deploying from an image.

Each of these options can also be used with only their first letter:

+-------------+--------------+
| Long Option | Short option |
+=============+==============+
| --git       | -g           |
+-------------+--------------+
| --image     | -i           |
+-------------+--------------+
| --port      | -p           |
+-------------+--------------+


Advanced Deployment of Docker Images
====================================

Extra ``key: value`` arguments (beyond port number and environment variables) needed for the docker image
to run properly can be specified when deploying the image via the ``/~image`` POST HTTP endpoint. These extra
``key: value`` arguments should be specified under the ``docker_run_args`` key in the request data field. The accepted
parameters for docker run which can be found `here <https://docker-py.readthedocs.io/en/stable/containers.html>`_.

For instance, a docker image
that requires ``privileged`` mode to run properly can be deployed like (using pythons request library)
::
    requests.post(
        url='https://<host>/~image,
        headers=<headers>,
        data = {
            'image':<image>
            'name':<name>,
            'version':<version>,
            'port':<port>,
            'docker_run_args': {
                'privileged': true,
                ...
            }
        })

The interactive docs at ``<host>/docs`` is also very useful for this kind of deployment.