.. _cloud-quickstart:

|ccloud| Quick Start
====================

This quick start shows you how to get up and running with |ccloud|. This quick start will show the basics of using |ccloud|,
including creating topics and producing and consuming to a Kafka cluster in |ccloud|.

.. include:: ../includes/cloud.rst

For more information about |ccloud|, see the :ref:`Confluent Cloud documentation <cloud-home>`.

Prerequisites
    - `Access to Confluent Cloud <https://www.confluent.io/confluent-cloud/>`__
    - :ref:`cloud-limits`


Step 1: Create Kafka Cluster in |ccloud|
----------------------------------------

.. important:: This step is for |ccloud| users only. |ccloud-ent| users can skip to :ref:`cloud-cli-install`.

#.  Log into |ccloud| at `https://confluent.cloud <https://confluent.cloud>`_.

#.  Click **Create cluster**.

    .. image:: ../images/cloud-create-topic.png

#.  Specify a cluster name, choose a cloud provider, and click **Continue**. Optionally, you can specify read and
    write throughput, storage, region, and durability.  

    .. image:: ../images/cloud-pay-launch.png

#.  Confirm your cluster subscription details, payment information, and click **Save and launch cluster**.

    .. image:: ../images/cloud-enter-credit.png


.. _cloud-cli-install:

Step 2: Install and Configure the |ccloud| CLI
----------------------------------------------

After you have a working Kafka cluster in |ccloud|, you can use the |ccloud| command line tool to interact with your
cluster from your laptop. This quick start assumes your are configuring |ccloud| for Java clients. You can also use
|ccloud| with :ref:`librdkafka-based <ccloud-librdkafka>` clients. For more information about installing the |ccloud| CLI,
see :ref:`ccloud-install-cli`.

#.  From the **Management -> Clusters** page, click the ellipses (``...``) on the right-hand side of your cluster name and click
    **Client config**.

    .. image:: ../images/cloud-view-details.png

#.  Follow the on-screen |ccloud| installation instructions.

    .. image:: ../images/cloud-cli-config.png


Step 3: Create Topics and Produce and Consume to Kafka
------------------------------------------------------

#.  .. include:: ../cloud/includes/ccloud-topic-create.rst

    .. tip:: By default the |ccloud| CLI creates topics with a replication factor of 3.

#.  Optional: Describe the ``page_visits`` topic.

    .. include:: ../cloud/includes/ccloud-topic-describe.rst
        :start-after: code-sample

    Your output should resemble:

    .. code:: bash

        Topic:page_visits	PartitionCount:12	ReplicationFactor:3	Configs:message.format.version=1.0-IV0,max.message.bytes=2097164,min.insync.replicas=2
            Topic: page_visits	Partition: 0	Leader: 3	Replicas: 3,1,2	Isr: 3,1,2
            Topic: page_visits	Partition: 1	Leader: 0	Replicas: 0,2,3	Isr: 0,2,3
            Topic: page_visits	Partition: 2	Leader: 1	Replicas: 1,3,0	Isr: 1,3,0
            Topic: page_visits	Partition: 3	Leader: 2	Replicas: 2,0,1	Isr: 2,0,1
            Topic: page_visits	Partition: 4	Leader: 3	Replicas: 3,2,0	Isr: 3,2,0
            Topic: page_visits	Partition: 5	Leader: 0	Replicas: 0,3,1	Isr: 0,3,1
            Topic: page_visits	Partition: 6	Leader: 1	Replicas: 1,0,2	Isr: 1,0,2
            Topic: page_visits	Partition: 7	Leader: 2	Replicas: 2,1,3	Isr: 2,1,3
            Topic: page_visits	Partition: 8	Leader: 3	Replicas: 3,0,1	Isr: 3,0,1
            Topic: page_visits	Partition: 9	Leader: 0	Replicas: 0,1,2	Isr: 0,1,2
            Topic: page_visits	Partition: 10	Leader: 1	Replicas: 1,2,3	Isr: 1,2,3
            Topic: page_visits	Partition: 11	Leader: 2	Replicas: 2,3,0	Isr: 2,3,0

#.  .. include:: ../cloud/includes/ccloud-topic-alter.rst

    Your output should resemble:

    .. code:: bash

          Topic configuration for "page_visits" altered.

#.  .. include:: ../cloud/includes/ccloud-produce.rst

#.  .. include:: ../cloud/includes/ccloud-consume.rst

    Your output should show the items that you entered in ``ccloud produce``:

    .. code:: bash

        baz
        foo
        bar
        ^C
        Processed a total of 3 messages.

    The order of the consumed messages does not match the order that they were produced. This is because the producer spread
    them over the 10 partitions in the ``page_visits`` topic and the consumer reads from all 10 partitions in parallel.

Step 4: Run Java Examples
-------------------------

In this step you clone the `Examples repository <https://github.com/confluentinc/examples>`_ from GitHub and run |ccloud|
Java examples. The examples repository contains demo applications and code examples for |cp| and Apache Kafka.

#.  Clone the |ccloud| examples repository from GitHub.

    .. code:: bash

        git clone https://github.com/confluentinc/examples.git

#.  Navigate to the ``/examples/clients/cloud/java`` directory.

#.  Build the client examples.

    .. code:: bash

         mvn clean package

#.  Run the producer

    .. code:: bash

         mvn exec:java -Dexec.mainClass="io.confluent.examples.clients.ProducerExample" \
          -Dexec.args="$HOME/.ccloud/config page_visits 10"

#.  Run the Kafka consumer application to read the records that were just published to the Kafka cluster, and to display
    the records in the console.

    #.  Run the client examples.

        .. code:: bash

             mvn clean package

    #.  Run the consumer.

        .. code:: bash

             mvn exec:java -Dexec.mainClass="io.confluent.examples.clients.ConsumerExample" \
              -Dexec.args="$HOME/.ccloud/config page_visits"


        Hit ``Ctrl+C`` to stop.

#.  .. include:: ../cloud/includes/ccloud-topic-delete.rst

    Your output should resemble:

    .. code:: bash

        Topic "page_visits" marked for deletion.


Next Steps
----------

- :ref:`Connect your components and data to Confluent Cloud <cloud-connect>`
- Learn more about |ccloud| in the :ref:`documentation <cloud-home>`