.. _getting-started-reference:
Getting Started
===============
Daeploy consists of two components, a software development kit (SDK) and a manager application
that runs on the target machine. The SDK is a python library that you use in your
code to make into a service and the manager helps you deploy your code into running
applications.
Prerequisites
-------------
To use Daeploy, you need to have **python >= 3.6** installed in your development environment
and **docker** in your deployment environment.
Installation
------------
The Daeploy python library can be installed with `pip `_:
>>> pip install daeploy # doctest: +SKIP
Check your installation by running: ``daeploy --help`` in a terminal.
You will also need a manager container. To start a
manager running on ``localhost`` for development, run the following command:
>>> docker run -v /var/run/docker.sock:/var/run/docker.sock -p 80:80 -p 443:443 -d daeploy/manager:latest # doctest: +SKIP
You can check that it started correctly by opening http://localhost/ in your browser.
.. warning:: This configuration should **never** be used in production. It is missing crucial
features such as authentication and secured communication. Please refer to
:ref:`manager-configuration-reference` for an example of a production setup.
Deploying Your First Service
----------------------------
Once the Manager is up and running you are ready to start using Daeploy. The
fastest and easiest way to interact with the Manager is to use the
:ref:`cli-reference` (CLI) that comes packaged with the SDK. The CLI contains a
host of useful commands that make the deployment and monitoring of services fast
and painless.
.. note:: You can call ``daeploy --help`` at any time, to get a list and short description of
the available commands and ``daeploy --help`` to get a longer description
of that command.
Logging in to the Manager
-------------------------
The first step is to login to the host where Daeploy is running, if you started the manager with the
command above, your host is http://localhost. To do this, we call the ``daeploy login`` command.
If the manager has authentication enabled, you will be prompted for a username and password.
>>> daeploy login # doctest: +SKIP
Enter Daeploy host: http://localhost
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:
>>> daeploy 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:
>>> daeploy ls # doctest: +SKIP
You must log in to a Daeploy host with `daeploy 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:
>>> daeploy init # doctest: +SKIP
project_name [my_project]: my_first_daeploy_project
This creates a new directory called `my_first_daeploy_project` in
your current working directory. Let's see what's in it:
>>> ls -a ./my_first_daeploy_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_daeploy_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.
>>> daeploy deploy my_first_service 0.0.1 ./my_first_daeploy_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
``daeploy ls`` that it started properly.
>>> daeploy 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://localhost in a browser you should see the dashboard where you
can get much of the same information as through the CLI. And at
http://localhost/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 `_ is commonly used or
`curl `_ 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:
>>> daeploy 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.