Coiled clusters in 10 minutes
=============================

In this guide you will:

#. Sign up for Coiled
#. Install the Coiled Python library
#. Set up Coiled with your cloud provider
#. Run your Dask computation in your cloud account

Here's a video walkthrough of setting up Coiled using AWS:

.. raw:: html

    <p align="center"><iframe width="560" height="315" src="https://www.youtube.com/embed/q_5onf9mpsw?start=153" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe></p>

1. Sign up
----------

`Sign up for Coiled <https://cloud.coiled.io/signup>`_ using GitHub, Google, or your email address.

2. Install
----------

.. tabs::

    .. tab:: Install with pip

        .. code-block:: bash

            pip install coiled 'dask[complete]'

    .. tab:: Install with conda

        .. code-block:: bash

            conda install -c conda-forge coiled
        
.. _coiled-setup:

3. Set up Coiled with your cloud provider
-----------------------------------------

You can set up Coiled using the ``coiled setup`` command line tool:

.. code-block:: bash

    $ coiled setup

You'll then navigate to https://cloud.coiled.io/profile on the Coiled web
app where you can create and manage API tokens.

.. code-block:: bash

    Please login to https://cloud.coiled.io/profile to get your token
    Token:

Your token will be saved to :doc:`Coiled's local configuration file <configuration>`.

.. note:: **For Windows users**
   
   You will need to first log in with ``coiled login --token <your-token>`` since the Windows clipboard will not be active at the "Token" prompt. Then, you can run ``coiled setup`` to finish setting up Coiled with your cloud provider account. Unless you are using WSL, you will need to use a command prompt or PowerShell window within an environment that includes coiled.
   
   You can also login with ``!coiled login --token <your-token>`` from a Jupyter notebook.

You'll then be prompted to configure your Google Cloud or AWS account (see :doc:`cli_setup`).

.. figure:: images/coiled-setup.png
    :width: 75%
    :alt: Terminal output prompting configuring your AWS or Google Cloud account. Text reads, Welcome to Coiled! To begin we need to connect Coiled to your cloud account. Select one of the following options: 1. Amazon Web Service (AWS), 2. Google Cloud Platform (GCP), 3. I don't have a cloud account, set me up with a free trial? x (in red) Exit setup.

If you don't have an AWS or GCP account and would like help choosing which to use, see :ref:`no-cloud-provider`

.. _first-computation:

4. Run your Dask computation
----------------------------

Next, spin up a Dask cluster in your cloud by creating a :class:`coiled.Cluster` instance
and connecting this cluster to the Dask ``Client``.

.. code-block:: python

    import coiled

    # create a remote Dask cluster with Coiled
    cluster = coiled.Cluster(name="my-cluster")

    # connect a Dask client to the cluster
    client = cluster.get_client()

    # link to Dask scheduler dashboard
    print("Dask scheduler dashboard:", client.dashboard_link)


.. note::
   If you're using a :doc:`Team account <teams>`, be sure to specify
   the ``account=`` option when creating a cluster:

   .. code-block:: python

      cluster = coiled.Cluster(account="<my-team-account-name>")

   Otherwise, the cluster will be created in your personal Coiled account.

You will then see a widget showing the cluster state overview and progress bars as resources are provisioned (this may take a minute or two).

.. figure:: images/widget-gif.gif
   :alt: Terminal dashboard displaying the Coiled cluster status overview, configuration, and Dask worker states.

Once the cluster is ready, you can submit a Dask DataFrame computation for execution. Navigate to the `Dask scheduler dashboard <https://docs.dask.org/en/stable/dashboard.html>`_ (see ``Dashboard Address`` in the widget) for real-time diagnostics on your Dask computations.

.. code-block:: python

    import dask

    # generate random timeseries of data
    df = dask.datasets.timeseries("2000", "2005", partition_freq="2w").persist()

    # perform a groupby with an aggregation
    df.groupby("name").aggregate({"x": "sum", "y": "max"}).compute()

You can also monitor your cluster, access the Dask scheduler dashboard, and see cluster state and worker logs from https://cloud.coiled.io.

.. figure:: images/cloud-cluster-dashboard.png
    :width: 100%
    :alt: Cluster dashboard on the Coiled cloud web app with rows for each cluster and columns for cluster name, status, number of workers, software environment, last seen timestamp, and cost (in credits).
   
    Cluster dashboard (click to enlarge)

Lastly, you can stop the running cluster using the following commands. By default, clusters will shut down after 20 minutes of inactivity.

.. code-block:: python

    # Close the cluster
    cluster.close()

    # Close the client
    client.close()

Learn more about options for launching Dask clusters :doc:`here <cluster_creation>`.
