.. _first-service-reference:

Deploying Your First Service
============================

Once the MVI Manager is up and running you are ready to start using MVI. The
fastest and easiest way to interact with the Manager is to use the
:ref:`cli-reference` (CLI). The CLI contains a host of useful commands that make
the deployment and monitoring of services fast and painless.

.. note:: You can call ``mvi --help`` at any time, to get a list and short description of
    the available commands and ``mvi <COMMAND> --help`` to get a longer description
    of that command.

Logging in to the Manager
-------------------------

The first step is to login to the host where MVI is running. To do this,
we call the login command:

>>> mvi login # doctest: +SKIP
Enter MVI host: http://your-host
Username: <username>
Password: <password>

Once you have logged in you are connected to your specified host and able to
communicate with the Manager running there. Logins last for a week, before you
have to login again. We can check if we are logged in by calling:

>>> mvi ls # doctest: +SKIP
MAIN    NAME    VERSION    STATUS    RUNNING
------  ------  ---------  --------  ---------

It should return an empty list. If you didn't log in, you would get this message:

>>> mvi ls # doctest: +SKIP
You must log in to a MVI host with `mvi login` before using this command.
Aborted!

Creating a New Service
----------------------

When creating a new service we recommend the user to create a project template with:

>>> mvi init # doctest: +SKIP
project_name [my_project]: my_first_mvi_project

This creates a new directory called `my_first_mvi_project` in
your current working directory. Let's see what's in it:

>>> ls -a ./my_first_mvi_project # doctest: +SKIP
.  ..  .s2i/  .s2iignore  README.md  requirements.txt  service.py  tests/

Let's not worry about the individual files and directories. For now it is enough
to know that `my_first_mvi_project` contains a fully functioning hello world service
that we can deploy straight away.

Deploying the Service
---------------------

The CLI has a command to deploy a service. It requires that you to give it a name and
version and then specify the path to the project directory.

>>> mvi deploy my_first_service 0.0.1 ./my_first_mvi_project # doctest: +SKIP
Deploying service...
Service deployed successfully
MAIN    NAME              VERSION    STATUS    RUNNING
------  ----------------  ---------  --------  -----------------------------------
*       my_first_service  0.0.1      running   Running (since 2020-11-20 15:48:45)

After a few seconds the service should be up and running. We can check with
``mvi ls`` that it started properly.

>>> mvi ls # doctest: +SKIP
MAIN    NAME              VERSION    STATUS    RUNNING
------  ----------------  ---------  --------  -----------------------------------
*       my_first_service  0.0.1      running   Running (since 2020-11-20 15:48:45)

If you open http://your-host in a browser you should see the dashboard where you
can get much of the same information as through the CLI. And at
http://your-host/services/my_first_service_0.0.1/docs you can read the automated
API documentation of the service and test its functionality.

.. note:: To communicate with your services from outside of the documentation you can use
    any HTTP library, which are available in most programming languages. In python
    `requests <https://requests.readthedocs.io/en/master/>`_ is commonly used or 
    `curl <https://curl.se/>`_ in bash.

Killing a Service
-----------------

Say that you are finished with your service, then the process can be stopped and the
service removed by calling:

>>> mvi kill my_first_service 0.0.1 # doctest: +SKIP
MAIN    NAME              VERSION    STATUS    RUNNING
------  ----------------  ---------  --------  -----------------------------------
*       my_first_service  0.0.1      running   Running (since 2020-11-20 15:48:45)
Are you sure you want to kill the above service(s)? [y/N]: y
Service my_first_service 0.0.1 killed.

What's next?
------------

Now that you know the basics of how to deploy a service using the CLI it might be
time to learn how to write your own service: :ref:`custom-service-reference`,
or maybe take a look at the :ref:`cli-reference` documentaion.