Hatcher Quick Start Guide

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

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.

The first thing that most users should do is create an Enthought Deployment Server 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 Enthought Deployment Server.

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

orphan

Most hatcher commands require that a platform be specified. The following command lists all valid platforms in the Enthought Deployment Server:

$ hatcher platforms list
Platforms
-----------
osx-x86_64
osx-x86
rh5-x86_64
rh5-x86
rh6-x86_64
rh6-x86
rh7-x86_64
rh7-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 rh6-x86_64 platform, the following command is used:

$ hatcher eggs list enthought free rh6-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 rh6-x86_64 platform, the following command is used:

$ hatcher eggs list enthought free rh6-x86_64 cp27
Egg Name                      Python Tag
----------------------------  ------------
affine-2.0.0.post1-1.egg      cp27
alabaster-0.7.9-1.egg         cp27
alabaster-0.7.10-1.egg        cp27
alembic-0.8.10-2.egg          cp27
amqp-1.4.5-1.egg              cp27
amqp-2.2.2-1.egg              cp27
aniso8601-0.92-1.egg          cp27
ansi2html-1.1.1-1.egg         cp27
...

Note

The valid platforms can be listed with the command in Listing current platforms recognized by an Enthought Deployment 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 the Enthought Deployment Server. 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 rh6-x86_64 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 internal-dev rh6-x86_64
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 an Enthought Deployment Server.

Note

Hatcher will refuse to upload eggs that are not in a supported metadata format. This means that eggs built with setuptools’ bdist_egg will need to be repacked using EDM’s repack-egg command before they can be uploaded. (For more information see http://docs.enthought.com/edm/user/cli.html#egg-repacking). Here is an example of using EDM’s repack-egg command:

$ edm repack-egg -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

After an egg has been uploaded to one of the Enthought Deployment Server repositories, you may want to download it on some machine or install it into a Python environment. The download command for eggs is constructed as follows:

$ hatcher eggs download <organization-name> <repository-name> <platform> <python-tag> <package name> <package version>

To install an uploaded egg, you can also use EDM in the same way you would for any other egg from our regular repositories:

$ edm install <requirements>

Note that for that to work, you will need to make sure your ~/.edm.yaml includes the corresponding repository under repositories.