==============================
 Getting Started with Hatcher
==============================

.. contents::

.. _installing-hatcher:

Installing Hatcher
==================

Installing with ``enpkg``
-------------------------

.. warning::
    Hatcher is not yet available as an enstaller egg.  Installation via
    source is currently the only option.


Installing from Source
----------------------

The simplest way to install (or update) ``hatcher`` from source is using
``pip`` directly with GitHub::

    $ pip install -U git+ssh://git@github.com/enthought/hatcher@<selected-tag>#egg=hatcher

.. note::

    It is very important that the latest *release* tag is selected for
    install.  See releases_ for the latest release.

This will install the latest development version of hatcher in the
current Python envorinment.

.. _releases: https://github.com/enthought/hatcher/releases

.. _first-steps:

First steps
===========

.. _specify-brood-server:

Specifying the Brood Server
---------------------------

When running Hatcher, the first thing to keep in mind is that it always
needs to know the URL of the Brood server.  The ``-u`` or ``--url``
option of the ``hatcher`` command is used to specify the root Brood URL::

    $ hatcher -u https://packages.enthought.com ...

.. hint::

    All options to the ``hatcher`` command support being passed as
    environment variables.  The environment variable for any option is
    named ``HATCHER_<option>``, where ``<option>`` is the long name for
    the option in upper case.  For example ``HATCHER_URL`` for the
    ``--url`` option.

.. note::

    All commands in this documentation will assume that the Brood URL is
    passed through the environment variable.

Handling self-signed SSL certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the Brood server is using SSL and the certificate is invalid (e.g. it
is a self-signed certificate or for a different domain than the server
is using), the ``--insecure`` (or ``-k``) option is required to prevent
SSL connection errors.

.. warning::

    The ``--insecure`` option should only be used if the Brood server is
    trusted.


.. _authenticating-to-brood:

Authenticating to Brood
-----------------------

Password Authentication
~~~~~~~~~~~~~~~~~~~~~~~

Brood requires users to be authenticated in order to perform any
actions.  The simplest authentication method is password authentication.
This can be used by passing the ``--username`` (or ``-U``) option to
``hatcher``.  Hatcher will prompt the user for the password when needed.
There is a ``--password`` option to pass the option, but this is not
considered secure as the password is then easily readable by other
processes through Hatcher's command line arguments.

::

    $ hatcher --username user@example.com ...
    Password:
    ...

Password authentication always takes precedence over API token
authentication, even if the username/password is passed via environment
variables and the token via command line.

.. _token-authentication:

Token Authentication
~~~~~~~~~~~~~~~~~~~~

Brood provides token-based authentication in addition to password
authentication.  This first requires that the user create an API token
for Brood (using password authentication), and then the token is stored
and used for future authentication attempts.  When a token is created, a
user-recognizable name is provided so that the user is able to view all
tokens associated with the account.  Tokens can be revoked at any time
when they are no longer needed and will never be re-generated by the
server.

Creating tokens
+++++++++++++++

To create a new token, use the ``api-tokens create`` command::

    $ hatcher -U user@example.com api-tokens create user-laptop-token
    Password:
    Created API token user-laptop-token: 'eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ'

.. warning::

    The api token should be treated as private and never shared.  It
    provides the same level of access to Brood as authenticating with a
    username and password.  The benefit of a token is that it can be
    easily revoked at any time.

Using tokens
++++++++++++

The token value can be copied and used in scripts via the ``--token``
(or ``-t``) option or placed in the ``HATCHER_TOKEN`` environment
variable to enable automatic token-based authentication::

    $ hatcher -U user@example.com api-tokens list
    Password:
    Name              | Created                    | Last Used
    user-laptop-token | 2014-10-20T17:30:07.956240 |

    $ hatcher --token <token-data> api-tokens list
    Name              | Created                    | Last Used
    user-laptop-token | 2014-10-20T17:30:07.956240 | 2014-10-20T17:31:31.224082

    $ export HATCHER_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ
    $ hatcher api-tokens list
    Name              | Created                    | Last Used
    user-laptop-token | 2014-10-20T17:30:07.956240 | 2014-10-20T17:32:33.329669

Revoking tokens
+++++++++++++++

To delete a token that is no longer required, the following can be
used::

    $ hatcher api-tokens delete user-laptop-token
    Password:

Following token deletion, if attempting to authenticate using the token,
authentication will fail and the user will need to use a different token
or switch to password authentication::

    $ hatcher --token <token-data> api-tokens list
    Authentication failed