Getting Started with Hatcher¶
Contents
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