.. _cloud-getting-started:

===============
Getting started
===============

.. contents::
   :local:
   :depth: 1

.. _cloud-install-client:

Installing Anaconda Client
==========================

You can use Anaconda Client command line interface (CLI) to:

* Connect to and manage your Anaconda Cloud account.

* Upload :ref:`packages <cloud-glossary-package>` you have 
  created.

* Generate access :ref:`tokens <cloud-glossary-token>` to allow 
  access to private packages.

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

This tool can be installed in three ways: with 
`conda <http://conda.pydata.org/>`_, with 
`pip <https://pip.pypa.io/en/latest/>`_ 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-Platform/anaconda-client

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

    anaconda -h

Finding, downloading and installing packages
============================================

Searching for public packages
-----------------------------

`Cloud <http://www.anaconda.org>`_ hosts hundreds of useful
Python packages for a wide variety of applications. You do not need 
to be logged in, or even need a Cloud account, to search for public
packages, download and install them. You need an account only to 
access :ref:`private packages <cloud-private-packages>` 
without a :ref:`token <cloud-accounts-tokens>` or to share your 
packages with others.

To search for packages:

#. In the top Search box, type part or all of the name of a 
   program you are searching for, and then press Enter.

#. Packages that match your search string are displayed. To see more 
   information, click the package name.
   
.. figure:: /img/cloud-search.png

   ..

|

For more information, see :ref:`cloud-packages`.

Refining your search results
----------------------------

You can filter search results using 3 filter controls:

* ``Type``: All, conda only or PyPI only.

* ``Access``: All, Public and/or Private--only available if you are 
  logged in.

* ``Platform``: All, source, linux-32, linux-64, linux-armv61, linux-armv71,
  linux-ppc641e, noarch, osx-32, osx-64, win-32, win-64.

``Source`` packages are source code only, not yet built for any
specific platform.

``Noarch`` packages are built to work on all platforms.


Downloading and installing packages from Cloud
----------------------------------------------

You can download and install packages using 
:doc:`Anaconda Navigator </anaconda/navigator/index>`, the graphical 
user interface for Anaconda. Advanced users may prefer a terminal 
window or command prompt.

Using Navigator
^^^^^^^^^^^^^^^

Navigator is automatically installed when you install 
Anaconda\ |reg|. 

To download and install a package into its own environment: 

#. Start Navigator by clicking its program icon on your desktop 
   or in your programs menu.  

#. Sign Navigator into Cloud so you can search for packages 
   marked as private. Click the top right Sign in to Anaconda 
   Cloud button and type your Cloud username and password, 
   then click the Login button.

#. On the **Environments** tab, in the far-right Search packages box, 
   enter the name of the desired package.

#. In the list to the left of Channels, select either Not installed or All,
   then click the Search button. 

#. Select the checkbox of the package you want to install, then 
   click the Apply button.

For more information, see :doc:`Navigator </anaconda/navigator/index>`.

Using conda in a terminal window or command prompt
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To download and install a package into its own environment: 

#. Locate a package on Cloud that you want to download, then click
   on the package name.

#. A detail page displays specific installation instructions 
   for the current operating system. Copy and paste the full 
   command into your terminal window.

For example, the command could be structured as::

    conda install -c username packagename

NOTE: For the following examples to work, you need to have 
`conda downloaded <http://conda.pydata.org/docs/download.html>`_ 
and installed.

TIP: Conda expands ``username`` to a URL such as
https://anaconda.org/username, based on the settings in the 
``.condarc`` file.

.. _cloud-getting-started-build-upload:

Building and uploading packages
===============================

:ref:`Open a Cloud account <cloud-accounts-create>` to upload 
packages or to access private packages without a token.

To build and upload packages, install the Client command line
interface (CLI). For more information, see 
:ref:`cloud-install-client`.

#. Open a terminal window and enter::

       conda install anaconda-client

#. Log into your Cloud account::

       anaconda login

   At the prompt, enter your Cloud username and password.

#. Choose the package you would like to build. For this example, 
   download our public test package::

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

#. To build your test package, first install ``conda-build`` and 
   turn off automatic Client uploading, then run the 
   ``conda build`` command::
   
       conda install conda-build
       conda config --set anaconda_upload no
       conda build .

#. Find the path to where the newly-built file was placed so you 
   can use it in the next step::

       conda build . --output

#. Upload your newly-built test package to your Cloud account::

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

   NOTE: Replace ``/your/path/`` with the actual path that you found 
   in the previous step.

For more information, see 
:ref:`conda packages <cloud-conda-packages>`.

Sharing notebooks
=================

To share a `Jupyter notebook <http://jupyter.org/>`_--formerly IPython
notebook--on Cloud:

#. Upload your notebook to Cloud::

       anaconda upload my-notebook.ipynb

   NOTE: Replace ``my-notebook`` with the actual name of your 
   notebook.

#. You can see an HTML version of your notebook stored at::

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

   NOTE: Replace ``<USERNAME>`` with your username, 
   and ``my-notebook`` with the actual name of your notebook.

#. Anyone who has access to Cloud can download your notebook::

       anaconda download username/my-notebook

   NOTE: Replace ``username`` with your username, and 
   ``my-notebook`` with the actual name of your notebook.

Sharing environments
====================

To share an environment on Cloud:

#. Save a `conda environment <http://conda.pydata.org/docs/using/envs.html>`_::

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

   NOTE: Replace ``my-environment`` with the actual name of your 
   environment.

#. Upload it to Cloud either using the web interface or the ``conda env upload``
   command.

   * Using the web interface:
   
     Go to ``https://anaconda.org/USERNAME/environments``.
     
     NOTE: Replace ``USERNAME`` with your username.
     
     In the top right corner use the Upload button to upload your environment.

   * Using the ``conda env upload`` command::

       conda env upload -f my-environment.yml

     NOTE: Replace ``my-environment`` with the actual name of your 
     environment.
   
#. You can see a list of your uploaded environments at::

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

   NOTE: Replace ``<USERNAME>`` with your username.

#. Anyone can download and install your environment from Cloud::

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

   NOTE: Replace ``my-environment`` with the actual name of 
   your environment.

.. |reg|    unicode:: U+000AE .. REGISTERED SIGN
