Continuum Analytics: Documentation

# Using Anaconda Cloud

## Getting started

### Overview

### Installing anaconda-client

The Anaconda client command line interface (CLI) is used to connect to and manage your Anaconda Cloud account, upload packages you have created, and generate access tokens to allow access to private packages. View the complete list of tasks after installing with this command:

    anaconda -h

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

Option 1, conda:

    conda install anaconda-client

Option 2, PIP:

    pip install anaconda-client

Option 3, installing with pip from source:

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

## Packages

All files uploaded to Anaconda Cloud are stored in Anaconda Cloud packages. Each Anaconda Cloud 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://anaconda.org/travis/testpkg . These Anaconda Cloud 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 Cloud package and then upload files into it.

### 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://anaconda.org/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 Cloud supports two package managers, conda and PyPI. To work with conda or PyPI packages, you must use their corresponding subdomains:

- To install conda packages from the conda user, use the repository url https://**conda**.anaconda.org/conda
- To install pypi packages from the conda user, use the repository url https://**pypi**.anaconda.org/conda

### Labels

Each file within a package may be tagged with one or more labels, or not tagged at all. The use of labels allows package authors to upload files for development or testing purposes without affecting non-development users.

At the channel https://conda.anaconda.org/sean a dropdown menu lists all the available labels.

For example, all of the conda packages labeled as “dev” can be shown here:

- https://conda.anaconda.org/sean/label/dev

The default label is main, so packages that are uploaded without specifying a label are automatically labeled “main”. The version labeled main is also delivered by default unless a user specifies a different label. So, if a file is labeled as main then the label name may be omitted from the URL. For example the following repositories are equivalent:

- https://conda.anaconda.org/sean/label/main
- https://conda.anaconda.org/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 packages

#### Uploading

This example shows how to build and upload a conda package to Anaconda Cloud using conda build.

If you do not already use conda, follow the miniconda quick install instructions.

Now make sure you have Anaconda client and conda build installed:

    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 conda test package:

    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 and 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 Anaconda’s 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 Cloud with the anaconda upload command:

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

You may also wish to read the articles Building conda packages and Tutorials on conda build for more information on conda’s overall build framework.

#### Installing

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

Conda knows how to interact with Anaconda Cloud. Specifying the channel `sean` translates to https://conda.anaconda.org/sean:

    conda config --add channels sean

Now you can install public conda packages from sean’s Anaconda Cloud account. Try installing the testci package:

    conda install testci

### PyPI packages

#### Uploading PyPI packages

We can test PyPI package uploading with a small example package saved in the anaconda-client repository. 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://anaconda.org/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.anaconda.org/USERNAME/simple pypi-test-package

#### Installing private PyPI packages

All Anaconda Cloud 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.anaconda.org/t/$TOKEN/USERNAME/simple test-package

### Uploading packages

To easily upload package files to Anaconda Cloud use the anaconda-client command line interface and the upload command:

    anaconda login
    anaconda upload PACKAGENAME

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

Your package is now available at: `https://anaconda.org/<USERNAME>/<PACKAGENAME>`

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

    anaconda download USERNAME/PACKAGENAME

### Private packages

By default all packages, notebooks and environments uploaded to Anaconda Cloud are publicly accessible. To make these items private you must first upgrade to a paid plan. See our pricing for details and the instructions to upgrade your account.

Packages uploaded to your user channel on Anaconda Cloud 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://anaconda.org/<username>/<package>/settings/admin

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

Other Anaconda Cloud 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 access token that includes the following scope for the Anaconda client CLI:

    conda:download

or in Web UI 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.anaconda.org/t/<token>/<channel>

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

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

Private pypi packages can also be installed using:

    https://pypi.anaconda.org/t/<token>/<channel>

#### Private packages with login

To make your private package available to users who have logged in, make an organization. Make a group in that organization, which may be a read-only group. Add the users you want to be able to download and install the package to the group. Upload the package to the organization, or transfer an existing package to the organization.

Now a user can install Anaconda client, log in and install the package. 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

Or instead:

    conda install anaconda-client
    anaconda login
    conda install -c https://conda.anaconda.org/OrgName conda-package

### Uploading other types of files

In addition to uploading packages, you can also upload other types of files to Anaconda Cloud. 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 Cloud, which will create a namespace that can hold multiple files. Then we will upload the file into this namespace.

1. Use the anaconda-client command line interface to create a new package and namespace for your file on Anaconda Cloud:

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

2. 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://anaconda.org/<USERNAME>/<babynames>`

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

    anaconda download USERNAME/baby-names

### Remove a past version of a package

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

1. Click the package name.
2. Click the tab “Files”.
3. Click the checkbox to the left of the version you wish to remove.
4. Click the “Actions” menu and then “Remove”.

You may instead use the command line interface:

    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://anaconda.org/<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 Cloud, including all of its versions:

1. Click the package name.
2. Click the tab “Settings”.
3. Click “Admin” on the left side menu.
4. Click “Delete”.

You may instead use the command line interface:

    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://anaconda.org/<USERNAME>`

## Notebooks

Upload a Jupyter notebook (formerly IPython notebook) to Anaconda Cloud:

    anaconda upload my-notebook.ipynb

An HTML version of the notebook will be at:

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

Anyone can download it:

    anaconda download username/my-notebook

## Environments

Save a conda environment and upload it to Anaconda Cloud:

    conda env export -n my-environment
    conda env upload my-environment

A list of your uploaded environments is at:

    http://envs.anaconda.org/<USERNAME>

Anyone can download and install your environment from Anaconda Cloud:

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

## Organizations

Organizations enable you to maintain group-owned repositories.

### Create organization

To create an organization:

- Log in to Anaconda Cloud.
- 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.

### 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://anaconda.org/<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 <OrgName> package.tar.bz2

### 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.

## 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 Cloud labels allow you to upload files to your packages and control how they are accessed.

With Anaconda Cloud 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 Cloud using the anaconda-client upload command.

Adding the `--label` option tells Anaconda Cloud 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://anaconda.org/USERNAME/conda-package`

    anaconda label --copy test main

Now your version 2.0 is in main:

    conda search --override -c USERNAME conda-package