Getting Started with 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.

First steps

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

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

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