=========================== 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 ===================== .. 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 :ref:`authenticating-to-eds`. 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 ``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 :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 the Enthought Deployment Server. 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 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 :ref:`list-platforms`. .. 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 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 Note that for that to work, you will need to make sure your `~/.edm.yaml` includes the corresponding repository under ``repositories``.