=========================
Using Anaconda Repository
=========================


.. _repo-installing-anaconda-client:

Installing anaconda-client
==========================

NOTE: Anaconda Client is NOT necessary to search for and download packages.

The Anaconda client command line
interface (CLI) is used in a Terminal window to build and upload packages, 
connect to and manage your Anaconda Repository account from a Terminal 
window, upload packages you have created, and generate access tokens to
manage access to private packages. 

This tool can be installed in three ways: with conda, with PIP, or
with PIP from source. We recommend using conda.

Option 1, `conda <http://conda.pydata.org/>`_::

    conda install anaconda-client

Option 2, `PIP <https://pip.pypa.io/en/latest/>`_::

    pip install anaconda-client

Option 3, installing with pip from source::

    pip install git+https://github.com/Anaconda-Server/anaconda-client

After installing, view the complete list of CLI tasks with this command::

    anaconda -h


.. _repo-using-packages:

Packages
========

All files uploaded to Anaconda Repository are stored in packages. Each
Anaconda Repository package is visible at its own unique URL based on the 
name of the
user who owns the package and the name of the package. 

For example, if a user
"travis" uploads a test package named "testpkg", it will be visible at
``https://<your-anaconda-repo>/travis/testpkg``. 

These Anaconda Repository packages may contain
multiple files, and these files may be data files such as comma separated value
(CSV), tab separated value (TSV), or text (TXT), or package files such as conda
packages, PyPI packages, or R packages. 

Users can create an Anaconda Repository
package, and then upload files into it.

Deleting packages through the user interface
--------------------------------------------

#. Select ``Packages`` from the ``Tools`` pull-down menu.

#. Optional: Select ``All`` for Type under Filters if the packages 
   to delete are not visible.
   
   .. image:: /img/repo-access-delete-packages.png

#. Click the checkbox next to the packages to delete.

#. Click Delete.

#. Enter the account name in the confirmation popup and click Delete to
   permanently delete the selected package(s). 

   Warning: There is no undo for deleting a package. 
   
Setting access for packages through the user interface
------------------------------------------------------

#. Select ``Packages`` from the ``Tools`` pull-down menu.

#. Optional: Select ``All`` for Type under Filters if the packages you want to 
   change access for are not visible.
   
#. Click the checkbox next to the packages to change access for.

#. Click Set access, then select either ``Public`` or ``Private`` from the resulting popup menu. 
   
Namespaces
~~~~~~~~~~

Each user and organization has their own location called a **user
namespace** where they may host packages. You can view the public
packages in a user or organization's namespace by navigating to their
user page.

EXAMPLE: The travis user namespace
located at ``https://<your-anaconda-repo>/travis`` contains packages that were
uploaded and shared by the user whose account is named Travis.

NOTE: All packages are public if uploaded by users of free accounts.
Packages may be designated as private by upgrading to a paid account.

Anaconda Repository supports two package managers,
:ref:`conda <repo-using-conda-packages>` and
:ref:`PyPI <repo-using-pypi-packages>`. To work with conda or PyPI packages,
you must use their corresponding subdomains:

-  To install **conda** packages from the user travis, use the repository
   url ``https://conda.<your-anaconda-repo>/travis``
-  To install **pypi** packages from the user travis, use the repository
   url ``https://pypi.<your-anaconda-repo>/travis``


Labels
~~~~~~

The use of labels allows package authors to upload files
for development or testing purposes without affecting non-development
users.

Each file within a package may be tagged with one or more labels, or not
tagged at all to accept the default label. 

The default label is **main**, so packages that are uploaded without
specifying a label are automatically labeled "main". 

The version labeled
main is also downloaded by default, unless a user specifies a different
label. So, if a file is labeled **main** then the label name may be
omitted from the URL. For example the following repositories are
equivalent:

-  ``https://<your-anaconda-repo>/sean/label/main``
-  ``https://<your-anaconda-repo>/sean``

Commands such as ``conda install`` can be used with a channel or used
with a channel and a label::

     conda install --channel sean selenium
     conda install --channel sean/label/dev selenium
     conda install --channel sean/label/stable selenium


.. _repo-using-conda-packages:

Conda packages
~~~~~~~~~~~~~~

.. _repo-uploading-conda-packages:

Uploading
^^^^^^^^^

This example shows how to build and upload a
`conda <http://conda.pydata.org/>`_ package to Anaconda Repository using 
conda build.

Before you start, install Anaconda client and conda build::

      conda install anaconda-client conda-build

Now choose the repository you would like to build the package for. In
this example we'll use a simple public `conda test
package <https://github.com/Anaconda-Server/anaconda-client/tree/master/example-packages/conda>`_::

      git clone https://github.com/Anaconda-Server/anaconda-client
      cd anaconda-client/example-packages/conda/

In this directory we can see two required files:
`meta.yaml <https://github.com/Anaconda-Server/anaconda-client/blob/master/example-packages/conda/meta.yaml>`_
and
`build.sh <https://github.com/Anaconda-Server/anaconda-client/blob/master/example-packages/conda/build.sh>`_
(for Linux or Mac) or bld.bat (for Windows). 

To build the package, turn
off automatic anaconda-client uploading, and then run the conda build
command::

      conda config --set anaconda_upload no
      conda build .

All packages built in this way are placed in a subdirectory of
:doc:`Anaconda's </anaconda/index>` *conda-bld*
directory. You can check where the resulting file was placed with the
``--output`` option::

      conda build . --output

Now upload the test package to Anaconda Repository with the :ref:`anaconda
upload <repo-cli-upload>` command::

      anaconda login
      anaconda upload /path/to/conda-package.tar.bz2

You may also wish to read the articles `Building conda
packages <http://conda.pydata.org/docs/building/bpp.html>`_ and
`Tutorials on conda
build <http://conda.pydata.org/docs/build_tutorials.html>`_ for more
information on conda's overall build framework.


Installing
^^^^^^^^^^

Install conda packages from Anaconda Repository by adding channels to your
conda config.

Conda knows how to interact with Anaconda Repository. Specifying the channel
``sean`` translates to
``https://<your-anaconda-repo>/sean``::

      conda config --add channels sean

Now you can install public conda packages from sean's Anaconda Repository
account. Try installing the testci
package at ``https://<your-anaconda-repo>/sean/testci``::

      conda install testci

.. _repo-using-pypi-packages:

PyPI packages
~~~~~~~~~~~~~

.. _repo-uploading-pypi-packages:

Uploading PyPI packages
^^^^^^^^^^^^^^^^^^^^^^^

We can test PyPI package uploading with a small public example package saved in
the `anaconda-client
repository <https://github.com/Anaconda-Server/anaconda-client/tree/master/example-packages/pypi>`_.

Begin by cloning the repository from the command line::

      git clone git@github.com:Anaconda-Server/conda-server.git
      cd conda-server/example-packages/pypi/

Now you can create your PyPI package with the ``setup.py`` script::

      python setup.py sdist

The package has now been built as a source tarball and is ready to be
uploaded::

      anaconda upload dist/*.tar.gz

Your package is now available at
``http://<your-anaconda-repo>/USERNAME/PACKAGE``.


Installing PyPI packages
^^^^^^^^^^^^^^^^^^^^^^^^

The best way to install a PyPI package is using pip. For the following,
we will use the package we authored in the examples above::

      pip install --extra-index-url https://pypi.<your-anaconda-repo>/USERNAME/simple pypi-test-package


Installing private PyPI packages
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The best way to manage access or make PyPI and other packages private is to create
:ref:`Organizations <repo-creating-orgs>` or :ref:`Groups <repo-org-groups>`,
which allow you to set separate permissions per package, notebook or
environment.

You can also control access with the token system.

All Anaconda Repository urls can be prefixed with ``/t/$TOKEN`` to access
private packages::

      TOKEN=$(anaconda auth --create --name YOUR-TOKEN-NAME)
      pip install --index-url https://pypi.<your-anaconda-repo>/t/$TOKEN/USERNAME/simple test-package

NOTE: Replace YOUR-TOKEN-NAME with a name for the token and replace $TOKEN with
the actual random string generated when you created the token.

Uploading packages
~~~~~~~~~~~~~~~~~~

To upload package files to Anaconda Repository use the
:doc:`anaconda-client <cli>` command line interface and the
:ref:`upload <repo-cli-upload>` command::

      anaconda login
      anaconda upload PACKAGENAME

Anaconda Repository automatically detects packages and notebooks, package or
notebook types, and their versions.

Your package is now available at:
``https://<your-anaconda-repo>/<USERNAME>/<PACKAGENAME>``

Your package can be also downloaded by anyone using the Anaconda CLI::

      anaconda download USERNAME/PACKAGENAME


.. _repo-using-private-packages:

Private packages
~~~~~~~~~~~~~~~~

By default all packages, notebooks and environments uploaded to Anaconda Repository are accessible to anyone who has access to the repository. 

Packages uploaded to your user channel on Anaconda Repository can be marked as private through the Web UI by selecting the package, clicking the Settings tab and clicking Admin from the sidebar. 

Alternatively,
you can reach this page with the following URL::

    https://<your-anaconda-repo>/<username>/<package>/settings/admin

NOTE: Jupyter Notebooks and conda environments can also be marked private using this procedure and URL.

Other Anaconda Repository users may access your private packages either with tokens or by logging in.


Private packages with tokens
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To make your private packages available to be accessed with tokens, first create 
an :ref:`access token <repo-using-tokens>` that includes the following scope for the Anaconda client CLI::

    conda:download

or in your web browser with::

    Allow private downloads from Conda repositories

The token is a random alphanumeric string and this is used to install a package or add
a channel from which you wish to install private packages.

Using the provided token a user's channel can be added to the config with::

    conda config --add channels https://conda.<your-anaconda-repo>/t/<token>/<channel>

The token can also be used to install packages without first adding the channel::

    conda install -c https://conda.<your-anaconda-repo>/t/<token>/<channel> <package>

Private pypi packages can also be installed using::

    https://pypi.<your-anaconda-repo>/t/<token>/<channel>


Private packages with login
^^^^^^^^^^^^^^^^^^^^^^^^^^^

To make your private package available to users who have logged in, 

1. Create an :ref:`organization <repo-organizations>`. 
2. Create a group in that organization, which may be a read-only group. 
3. Add the users you want to be able to download 
   and install the package to the group. 
4. Upload the package to the organization, or transfer an existing 
   package to the organization.

Now another user can download and install your package using the web 
interface or Anaconda client.

1. In their web browser, they can navigate to your channel.

2. If the 
organization name is "OrgName" and the package name is "conda-package", the user 
would use these commands::

    conda install anaconda-client
    anaconda login
    conda install -c OrgName conda-package


Uploading other types of files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to uploading packages, you can also upload other types of
files to Anaconda Repository. In this example we will upload a spreadsheet
named "baby-names" in comma separated value (CSV) format. Any type of file
can be uploaded with the Anaconda CLI by using these steps. First we will create
the new package on Anaconda Repository, which will create a namespace that can hold
multiple files. Then we will upload the file into this namespace.

#. Use the :doc:`anaconda-client <cli>` command line interface to
   create a new package and namespace for your file on Anaconda Repository::

       anaconda login
       anaconda package --create USERNAME/baby-names

#. Now upload the file to the new namespace. PyPI package files, conda package
   files and notebook files are automatically detected. There is no auto-detect
   for other types of files, so you must explicitly specify the 'package',
   'package-type' and 'version' fields.

   In this example the user or organization name is travis, the package name is
   baby-names, the package type is a file, this is the first version that we are
   uploading, and the full filename is baby-names1.csv::

       anaconda upload --user travis --package baby-names --package-type file --version 1 baby-names1.csv

Downloading other types of files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Your file is available at
``https://<your-anaconda-repo>/<USERNAME>/<babynames>``

Your file can also be downloaded by anyone using the Anaconda CLI::

        anaconda download USERNAME/baby-names

Deleting files through the user interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

#. Select ``Packages`` from the ``Home`` menu.

#. Select the Files tab.

#. Optional: Select ``All`` for Type under Filters if the files you want to delete are not visible.

   .. image:: /img/repo-delete-files.png

#. To select individual files, first expand the Package the files are located in, then click 
   the checkbox next to the files to delete.

#. Select the checkboxes next to the files to delete.

#. Click Delete.

#. Enter your account name in the confirmation popup and click Delete to permanently delete the selected files. 
   Warning: There is no undo for deleting a file. 

Remove a past version of a package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To remove a past version of one of your packages from Anaconda Repository:

#. Click the package name.

#. Click the tab "Files".

#. Click the checkbox to the left of the version you wish to remove.

#. Click the "Actions" menu and then "Remove".

You may instead use the :doc:`command line interface <cli>`::

      anaconda remove jsmith/testpack/0.2

NOTE: Replace ``jsmith``, ``testpack``, and ``0.2`` with your actual
user name, package name, and version.

The change can now be seen on your profile page:
``https://<your-anaconda-repo>/<USERNAME>/<PACKAGE>``

Add a collaborator to a package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can add other users that are not part of an organization to collaborate on 
your packages. You'll need to know the username of the other user(s).

-  From your dashboard select the package for which you want to add a
   collaborator by clicking on its name.
-  Click the Settings option to display the package settings.
-  Click the Collaborators option.
-  Enter the username of the person you want to add as a collaborator
   and click the Add button.

NOTE: All collaborators are given full read/write permissions to the package,
even private packages.


Remove a collaborator from a package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To revoke package access previously granted to a collaborator:

-  From your dashboard select the package for which you want to add a
   collaborator by clicking on its name.
-  Click the Settings option to display the package settings.
-  Click the Collaborators option to display the current
   collaborators.
-  Click the red X button next to a collaborator to revoke their access.


Transfer a package to a new owner
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By default, when you create or add packages, they are attached to your
individual profile. You can transfer ownership to another owner account
you control, such as an Organization profile you manage. To
transfer a package to a new owner:

-  From your dashboard (or the dashboard of an organization you
   administer), select the package for which you want to transfer
   ownership. The system displays options for that package.
-  Click the Settings option to display the package settings.
-  Click the Admin option.
-  Under Transfer this package to a new owner, click the Transfer
   button.
-  Select the organization name for the new owner and click the Transfer
   Ownership button.

Delete a package
~~~~~~~~~~~~~~~~

To delete one of your packages from Anaconda Repository, including all of its
versions:

#. Click the package name.

#. Click the tab "Settings".

#. Click "Admin" on the left side menu.

#. Click "Delete".

You may instead use the :doc:`command line interface <cli>`::

      anaconda remove jsmith/testpak

NOTE: Replace ``jsmith`` and ``testpak`` with your actual user name and
package name.

The change can now be seen on your profile page:
``https://<your-anaconda-repo>/<USERNAME>``


Notebooks
=========

Upload a `Jupyter notebook <http://jupyter.org/>`_ (formerly IPython
notebook) to Anaconda Repository::

    anaconda upload my-notebook.ipynb

An HTML version of the notebook will be at::

    http://notebooks.<your-anaconda-repo>/<USERNAME>/my-notebook

Anyone can download it::

    anaconda download username/my-notebook


Environments
============

A `saved conda environment <http://conda.pydata.org/docs/using/envs.html>`_
can be uploaded to Anaconda Repository with the web interface or the
``conda env upload`` command.

To save the environment::

    conda env export -n my-environment -f my-environment.yml

To use the web interface go to::

    https://<your-anaconda-repo>/<USERNAME>/environments

Then use the Upload button in the top right corner.

To use the ``conda env upload`` command::

    conda env upload -f my-environment.yml

A list of your uploaded environments is located at::

    http://envs.<your-anaconda-repo>/<USERNAME>

Anyone can download and install your environment from Anaconda Repository::

    conda env create user/my-environemnt
    source activate my-environment


.. _repo-organizations:

Organizations
=============

Organizations enable you to maintain group-owned repositories.

.. _repo-creating-orgs:

Create organization
-------------------

To create an organization:

-  Log in to your Anaconda Repository.
-  Select the Organizations item from the Tools pull-down menu
   and scroll to the bottom of the page.
-  Supply an organization name. NOTE: Organization names cannot include
   spaces or special characters.
-  Supply an email address, then click the Create Organization button.
   The system displays the dashboard for the new organization.

As the creator and owner of an organization, you have automatic
administrative access to this organization and any packages associated
with the organization.

The Group Membership page from the Tools pull-down menu shows a list of all organizations to
which you belong.


Delete an organization
----------------------

To delete an organization you administer and erase all data associated
with it:

-  Select "Switch To" from the Profile pull-down menu.
-  Select organization you wish to delete.
-  Select "Settings" from the Profile pull-down menu.
-  Click the "Account" option. You may be asked to verify your password.
-  Under the "Delete Account" section, click the "Delete" button. The
   confirmation page will request that you provide the full name of the
   organization.


.. _repo-org-groups:

Customize users and groups
--------------------------

Administrators may add, remove or edit group and user access. To access
these features, first Switch To the organization profile from the Profile
pull-down menu.

After switching from your user view to an organization view, you can
review and edit the current group and user access for an organization,
as well as add new groups and users at this address::

        https://<your-anaconda-repo>/<OrgName>/groups/

by selecting Groups from the Tools pull-down menu.

Users will receive a dashboard notification when you add them to an
organization.


Uploading packages to an organization
-------------------------------------

To upload a package to an organization, use the ``-u/--user`` option::

    anaconda upload --user ORGANIZATION package.tar.bz2

Only the co-owners of an organization may upload packages to the organization.
    
NOTE: Replace ORGANIZATION with the actual name of the organization, and package.tar.bz2 with the actual name of the package.

Create groups for differing access levels
-----------------------------------------

Within an organization, you can create a group to customize access for a
group of users:

-  Click the +New Group button. Give the group a name, and assign the
   desired permissions (Read-Only, Read-Write, or Administration).
-  Add the desired members by username in the Members box.
-  Add the packages which this group can access in the Packages box.
-  Click the Save Group button.

.. _repo-using-labels-in-the-development-cycle:

Using labels in the development cycle
=====================================

Labels can be used to facilitate a development cycle and organize the
code that is in development, in testing, and in production.

Anacona Repository labels allow you to upload files to your packages and
control how they are accessed.

With Anaconda Repository labels you can upload a file to a specific label, so
only users who put that label in the URL they search will be able to
install it. This is particularly useful for moving a package through a
development and testing flow.

In this example we will show you how to use a ``test`` label, so that
you can upload files without affecting your production quality packages.
Without a ``--label`` argument the default label is ``main``.

Let's start with a conda package. If you don't have one, use our example
conda package. Before you build the package edit the version in the
``meta.yaml`` file in ``anaconda-client/example-packages/conda/`` to be
2.0.

::

    git clone https://github.com/Anaconda-Server/anaconda-client
    cd anaconda-client/example-packages/conda/
    vim meta.yaml # Bump version to 2.0
    conda config --set anaconda_upload no
    conda build .

Now, upload your test package to Anaconda Repository using the
:ref:`anaconda-client upload <repo-cli-upload>` command.

Adding the ``--label`` option tells Anaconda Repository to make the upload
visible only to users who specify that label::

    anaconda upload /path/to/conda-package-2.0.tar.bz2 --label test

You will notice now that even when you search conda ``main``, you won't
see the ``2.0`` version of the test package. This is because you have to
tell conda to look for your new ``test`` label.

The ``--override`` argument tells conda not to use any channels in your
``~/.condarc`` file.

No 2.0 results::

    conda search --override -c USERNAME conda-package

Your 2.0 package is here::

    conda search --override -c USERNAME/label/test conda-package

You can give the label ``USERNAME/label/test`` to your testers. Once
they finish testing, you may then want to copy the ``test`` packages
back to your ``main`` label.

You can also manage your package labels from your dashboard:
``https://<your-anaconda-repo>/USERNAME/conda-package``

::

    anaconda label --copy test main

Now your version 2.0 is in main::

    conda search --override -c USERNAME conda-package

Projects
========

You can now add Projects to your Anaconda repository. 
Projects can be any directory of code and assets. 
Often projects will contain notebooks or Bokeh apps, for example.

To access Projects, select ``Projects`` from the ``Tools`` menu.

The Projects page shows your existing projects. 
Click on a project to display the Details page for that project, 
including the files for the project, the revisions, history and 
settings for the project. 

Under settings for the individual project, you can change options, 
set groups and collaborations, and manage administration of the project, 
including making it public, private or authenticated, transfering membership, 
or deleting it. 

Additional projects can be uploaded using the Anaconda Client. 
