Hatcher Quick Start Guide¶
Contents
This document provides a brief introduction to the most common set of commands that users will need.
Before starting, make sure that Hatcher is installed
Set up the environment¶
Before running any commands, the easiest way to specify which server to
connect to is using the HATCHER_URL environment variable. All
further commands in this document expect that this has been set.
In bash:
$ export HATCHER_URL="https://packages.enthought.com"
In Windows CMD:
C:\> set HATCHER_URL=https://packages.enthought.com
In Windows PowerShell:
PS C:\> $Env:HATCHER_URL = "https://packages.enthought.com"
Note
If the server in use has an invalid SSL certificate (e.g. the
certificate for the packages.enthought.com server above is issued
to *.enthought.com), the HATCHER_INSECURE option should be
set in addition to the HATCHER_URL:
$ export HATCHER_INSECURE=1
Creating an API Token¶
The first thing that most users should do is create a Brood API token for authenticating further requests. This can then be placed in a script or environment variable to simplify Hatcher commands. More details about API tokens can be found in Authenticating to Brood.
To create an API token, the api-tokens create command is used:
$ hatcher -U user@example.com api-tokens create user-laptop-token
Password:
Created API token user-laptop-token: 'eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ'
Note that, by design, after creation, the token data eyJhbG... is not recoverable so it should be stored somewhere, such as in an environment variable. For ease of use in scripts, it is recommended to use HATCHER_TOKEN for the environment variable name.
In bash:
$ export HATCHER_TOKEN="eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ"
In Windows CMD:
C:\> set HATCHER_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ
In Windows PowerShell:
PS C:\> $Env:HATCHER_TOKEN = "eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ"
All further commands can then omit any authentication information, and the token set in the environment will be used:
$ hatcher api-tokens list
Name | Created | Last Used
user-laptop-token | 2014-10-20T17:30:07.956240 | 2014-10-20T17:31:31.224082
If the token data is lost, it should be revoked and a new one must be created.
Revoking an API Token¶
If an API token is no longer in use or has been compromised, it should be immediately revoked:
$ hatcher api-tokens delete user-laptop-token
Any further commands making use of this token will fail:
$ hatcher --token <token-data> api-tokens list
Authentication failed
List valid platform names¶
In order to follow the next examples, the available platform support of Brood is required. This command lists all valid platforms in Brood:
$ hatcher platforms list
osx-x86_64
osx-x86
rh5-x86_64
rh5-x86
win-x86_64
win-x86
These are the valid values for any command that requires specifying a
platform. For example, to list the eggs in the enthought/free
repository for the rh5-x86_64 platform, the following command is
used:
$ hatcher eggs list enthought free rh5-x86_64 cp27
List eggs in a repository¶
A common part of upload workflow is to interactively inspect the contents of a repository to verify that new artefacts are present. The format of the command to list eggs is:
$ hatcher eggs list <organization-name> <repository-name> <platform> <python-tag>
Note
For the valid values of python tags, see Python Tags.
For example, to list the eggs in the enthought/free repository for
the rh5-amd64 platform, the following command is used:
$ hatcher eggs list enthought free rh5-amd64 cp27
Egg Name Python Tag
---------------------------- ------------
agw-0.9.1-1.egg cp27
AppInst-2.0.1-3.egg py27
AppInst-2.0.3-1.egg py27
AppInst-2.0.4-1.egg py27
AppInst-2.0.4.dev25071-1.egg py27
AppInst-2.0.4.dev25079-1.egg py27
appinst-2.1.0-1.egg py27
appinst-2.1.1-1.egg py27
appinst-2.1.2-1.egg py27
AppTools-3.2.0-1.egg py27
...
Note
The valid platforms can be listed with the command in Listing current platforms recognized by a brood server.
Upload egg to a repository¶
As part of an automated build workflow, it may be required to upload the new build artefact to a development repository in Brood. The upload command for eggs is constructed as follows:
$ hatcher eggs upload <organization-name> <repository-name> <platform> <filename>
For example, if a new traits package has been built containing a new
feature that requires testing by developers, it may be uploaded to an
internal-dev repository:
$ hatcher eggs upload enthought internal-dev win-amd64 dist/traits-4.6.5.dev1234-2.egg
Once the upload is complete, before long the egg should be visible in the repository:
$ hatcher eggs list enthought free rh5-amd64
agw-0.9.1-1.egg
AppInst-2.0.1-3.egg
AppInst-2.0.3-1.egg
AppInst-2.0.4-1.egg
...
traits-4.6.5.dev1234-2.egg
...
Note
The valid platforms can be listed with the command in Listing current platforms recognized by a brood server.
Note
Hatcher will refuse to upload eggs that are not in the enstaller metadata format. That means that to upload eggs built with setuptool’s bdist_egg will need to be repacked using enstaller’s repack tool:
$ python -m enstaller.tools.repack -b 2 -a win-x86_64 my_egg-0.1-py2.7-win-amd64.egg
--------------------
metadata_version = '1.2'
name = 'my_egg'
version = '0.1'
build = 2
arch = 'amd64'
platform = 'win32'
osdist = None
python = '2.7'
python_tag = 'cp27'
packages = []
--------------------
Download egg from a repository¶
Once an egg is uploaded to one of the Brood repositories, you may want to download it on some machine or install it inside a python installation. The download command for eggs is constructed as follows:
$ hatcher eggs download <organization-name> <repository-name> <platform> <python-tag> <package name> <package version>
Since enpkg can work with brood servers, to install an egg uploaded, you can also use enpkg the same way you would install any other egg from our regular repositories:
$ enpkg <package name> [<package version>]
Note that for that to work, you will need to make sure your ~/.enstaller4rc lists the URL of the repository in its IndexedRepos list and that use_webservice is set to False.