=========================== 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 :ref:`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 :ref:`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 api-tokens list Authentication failed List valid platform names ========================= .. include:: ../user-guide/list-platforms.rst 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 .. note:: For the valid values of python tags, see :ref:`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 :ref:`list-platforms`. 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 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 :ref:`list-platforms`. .. 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 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 [] 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`. .. _`enstaller's repack`: http://enstaller.readthedocs.org/en/4.8.1/user/tools.html#repack