.. _getting-started-with-hatcher:

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

.. contents::

.. _installing-hatcher:

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

Installing with ``edm``
-------------------------

To install hatcher into an EDM-managed Python environment, simply run the
following from within the desired environment::

    $ edm install hatcher

Installing with ``pip``
-------------------------

To install hatcher into a Python environment not managed by EDM, run::

    $ pip install hatcher


.. _first-steps:

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

.. _specify-eds-server:

Specifying an Enthought Deployment Server
------------------------------------------

When running Hatcher, the first thing to keep in mind is that it always
needs to know the URL of an Enthought Deployment Server (EDS).  The ``-u`` or
``--url`` option of the ``hatcher`` command is used to specify the root
EDS 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 assume that the EDS URL is passed
    through the environment variable.

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

If the Enthought Deployment 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 Enthought Deployment
    Server is trusted.


.. _authenticating-to-eds:

Authenticating to Enthought Deployment Server
---------------------------------------------

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

Enthought Deployment Server 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
~~~~~~~~~~~~~~~~~~~~

.. note::

    API tokens can only be used to control access to Enthought's own deployment
    server (including customer-controlled repositories that are hosted by
    Enthought), not to customers' on-site deployment servers.

Enthought Deployment Server (EDS) provides token-based authentication in
addition to password authentication.  This first requires that the user
create an API token for EDS (using password authentication); 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 EDS 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