(DOCSP-23128) Tutorial Updates for Sandbox Changes (#33)

Author: biniona-mongodb

snooty.toml

@@ -36,6 +36,7 @@ java-se = "Java Platform, Standard Edition"
 jconsole = "JConsole"
 jconsole_command = "jconsole"
 kafka_api_docs_base = "https://kafka.apache.org/32/"
-
 write-exception-version="1"
 write-concern-exception-version="1"
+mongodb-port-mapping="35001"
+jmx-port-mapping="35000"

source/includes/tutorials/docker-success.rst

@@ -0,0 +1,9 @@
+.. code-block:: shell
+   :copyable: false
+
+   Creating mongo1    ... done
+   Creating zookeeper ... done
+   Creating broker       ... done
+   Creating mongo1-setup ... done
+   Creating connect      ... done
+   Creating shell        ... done

source/includes/tutorials/port-mapping-note.rst

@@ -0,0 +1,9 @@
+.. note:: Port Mappings
+
+   The sandbox maps the following services to ports on your host
+   machine:
+
+   - The sandbox MongoDB server maps to port ``{+mongodb-port-mapping+}`` on your host machine
+   - The sandbox {+kc+} JMX server maps to port ``{+jmx-port-mapping+}`` on your host machine
+
+   These ports must be free to start the sandbox.

source/includes/tutorials/quickstart-clone-commands-versioned.rst

@@ -1,26 +1,42 @@
-After you complete this tutorial, you can free resources by stopping the
-tutorial Docker containers and MongoDB data. Navigate to the tutorial
-directory "mongodb-kafka-base" that you created in the setup step and run the
-following command:
+After you complete this tutorial, free resources on your computer
+by stopping or removing Docker assets. You can choose to remove
+both the Docker containers and images, or exclusively the
+containers. If you remove the containers and images, you must
+download them again to restart your {+mkc+} development environment,
+which is approximately {+pipeline-size+} in size. If you
+exclusively remove the containers, you can reuse the images and avoid
+downloading most of the large files in the sample data pipeline.
+
+.. tip:: More Tutorials
+
+   If you plan to complete any more {+mkc+} tutorials,
+   consider removing only containers. If you don't plan
+   to complete any more {+mkc+} tutorials, consider
+   removing containers and images.
+
+Select the tab that corresponds to the removal task you want to run.
 
 .. tabs::
 
-   .. tab:: Linux or Mac OS
-      :tabid: shell
+   .. tab:: Remove Containers and Images
+      :tabid: remove-containers-and-images
 
-      .. code-block:: none
-         :copyable: true
+      Run the following shell command to remove the Docker containers and
+      images for the development environment:
 
-         sh stop.sh
+      .. code-block:: shell
 
-   .. tab:: Windows
-      :tabid: powershell
+         docker-compose -p mongo-kafka down --rmi all
 
-      .. code-block:: none
-         :copyable: true
+   .. tab:: Remove Containers
+      :tabid: remove-containers
 
-         powershell ./stop.ps1
+      Run the following shell command to remove the Docker containers but
+      keep the images for the development environment:
+
+      .. code-block:: shell
+
+         docker-compose -p mongo-kafka down
 
 To restart the containers, follow the same steps required to start them
 in the :ref:`Tutorial Setup <tutorial-setup-run-environment>`.
-

source/includes/tutorials/robwma-m1-arch.txt

@@ -141,7 +141,7 @@ Example - Monitor the Quick Start
 ---------------------------------
 
 The sample environment provided in the Quick Start exposes metrics
-on your host machine at the URI ``localhost:35000``.
+on your host machine at the URI ``localhost:{+jmx-port-mapping+}``.
 
 To view these metrics with {+jconsole+}, perform the following actions:
 
@@ -174,7 +174,7 @@ To view these metrics with {+jconsole+}, perform the following actions:
 
          .. step:: Enter your JMX Server URI.
 
-            Enter the URI ``localhost:35000`` into the :guilabel:`Remote Process`
+            Enter the URI ``localhost:{+jmx-port-mapping+}`` into the :guilabel:`Remote Process`
             text input box in the {+jconsole+} interface.
 
          .. step:: Click :guilabel:`Connect`.

source/includes/tutorials/stop-containers.rst

@@ -51,7 +51,10 @@ To download the sandbox, clone the tutorial repository to your development
 environment. Then navigate to the directory that corresponds to the quickstart
 tutorial. If you use bash or a similar shell, use the following commands:
 
-.. include:: /includes/tutorials/quickstart-clone-commands-versioned.rst
+.. code-block:: bash
+
+   git clone https://github.com/mongodb-university/kafka-edu.git
+   cd kafka-edu/docs-examples/mongo-kafka-base
 
 Start the Sandbox
 -----------------
@@ -67,7 +70,7 @@ To start the sandbox run the following command from the tutorial directory:
 
 .. code-block:: shell
 
-   docker-compose -p quickstart up -d
+   docker-compose -p mongo-kafka up -d
 
 When you start the sandbox, Docker downloads any images it needs to run.
 
@@ -76,16 +79,9 @@ When you start the sandbox, Docker downloads any images it needs to run.
 After Docker downloads and builds the images, you should see the following
 output in your development environment:
 
-.. code-block:: shell
-   :copyable: false
-
-   Creating mongo1    ... done
-   Creating zookeeper ... done
-   Creating broker       ... done
-   Creating mongo1-setup ... done
-   Creating connect      ... done
-   Creating shell        ... done
+.. include:: /includes/tutorials/docker-success.rst
 
+.. include:: /includes/tutorials/port-mapping-note.rst
 
 Add Connectors
 --------------
@@ -100,14 +96,14 @@ your Docker container using the following command:
 
 .. code-block:: shell
 
-   docker exec -it shell /bin/bash
+   docker exec -it mongo1 /bin/bash
 
 After your shell session starts, you should see the following prompt:
 
 .. code-block:: none
    :copyable: false
 
-   [MongoDB Kafka Connector Quick Start]
+   MongoDB Kafka Connector Sandbox $ 
 
 .. _kafka-quick-start-source-connector-section:
 
@@ -320,7 +316,7 @@ Select the tab that corresponds to the removal task you want to run.
 
       .. code-block:: shell
 
-         docker-compose -p quickstart down --rmi 'all'
+         docker-compose -p mongo-kafka down --rmi all
 
    .. tab:: Remove Containers
       :tabid: remove-containers
@@ -330,7 +326,7 @@ Select the tab that corresponds to the removal task you want to run.
 
       .. code-block:: shell
 
-         docker-compose -p quickstart down
+         docker-compose -p mongo-kafka down
 
 Next Steps
 ----------

source/monitoring.txt

@@ -27,38 +27,24 @@ Explore Change Streams
 
    .. step:: Connect to the Docker Container
 
-      .. include:: /includes/tutorials/robwma-m1-arch.txt
-
       Create two interactive shell sessions on the tutorial Docker
       Container, each in a separate window.
 
-      .. tabs::
-
-         .. tab:: Intel Processors
-            :tabid: intel-cpu
-
-            .. code-block:: bash
-               :caption: This command starts an interactive shell called ChangeStreamShell1
+      Run the following command from a terminal to start an interactive shell.
 
-               docker run --rm --name ChangeStreamShell1 --network mongodb-kafka-base_localnet -it robwma/mongokafkatutorial:latest bash
-
-            .. code-block:: bash
-               :caption: This command starts an interactive shell called ChangeStreamShell2
+      .. code-block:: bash
 
-               docker run --rm --name ChangeStreamShell2 --network mongodb-kafka-base_localnet -it robwma/mongokafkatutorial:latest bash
+         docker exec -it mongo1 /bin/bash
 
-         .. tab:: Apple M1 Processors
-            :tabid: apple-m1-cpu
+      We will refer to this interactive shell as **ChangeStreamShell1** throughout this tutorial.
 
-            .. code-block:: bash
-               :caption: This command starts an interactive shell called ChangeStreamShell1
+      Run the following command in a second terminal to start an interactive shell:
 
-               docker run --platform='linux/arm64' --rm --name ChangeStreamShell1 --network mongodb-kafka-base_localnet -it robwma/mongokafkatutorial:latest bash
+      .. code-block:: bash
 
-            .. code-block:: bash
-               :caption: This command starts an interactive shell called ChangeStreamShell2
+         docker exec -it mongo1 /bin/bash
 
-               docker run --platform='linux/arm64' --rm --name ChangeStreamShell2 --network mongodb-kafka-base_localnet -it robwma/mongokafkatutorial:latest bash
+      We will refer to this interactive shell as **ChangeStreamShell2** throughout this tutorial.
 
    .. step:: Open a Change Stream
 

source/quick-start.txt

@@ -44,27 +44,13 @@ Migrate a Collection to a Time Series Collection
 
    .. step:: Generate Sample Data
 
-      .. include:: /includes/tutorials/robwma-m1-arch.txt
-
-      Run the following command to start a Docker container that generates
+      Run the following command to start a script in your Docker environment that generates
       a sample collection containing fabricated stock symbols and their prices
       in your tutorial MongoDB replica set:
 
-      .. tabs::
-
-         .. tab:: Intel Processors
-            :tabid: intel-cpu
-
-            .. code-block:: bash
-
-               docker run --rm --network mongodb-kafka-base_localnet -it robwma/stockgenmongo:1.0 -c "mongodb://mongo1" -db Stocks -col PriceData
-
-         .. tab:: Apple M1 Processors
-            :tabid: apple-m1-cpu
-
-            .. code-block:: bash
+      .. code-block:: bash
 
-               docker run --platform='linux/arm64' --rm --network mongodb-kafka-base_localnet -it robwma/stockgenmongo:1.0 -c "mongodb://mongo1" -db Stocks -col PriceData
+         docker exec -ti mongo1 /bin/bash -c "cd /stockgenmongo/ && python3 stockgen.py -db Stocks -col PriceData"
 
       Once the data generator starts running, you should see the generated
       data that resembles the following:
@@ -80,26 +66,13 @@ Migrate a Collection to a Time Series Collection
 
    .. step:: Configure the Source Connector
 
-      Create an interactive shell session on the tutorial Docker container
-      downloaded for the Tutorial Setup using the following command:
-
+      In a seperate terminal window, create an interactive shell session on the
+      tutorial Docker container downloaded for the Tutorial Setup using
+      the following command:
 
-      .. tabs::
-
-         .. tab:: Intel Processors
-            :tabid: intel-cpu
-
-            .. code-block:: bash
-
-               docker run --rm --name TimeSeriesTutorial --network mongodb-kafka-base_localnet -it robwma/mongokafkatutorial:latest bash
-
-
-         .. tab:: Apple M1 Processors
-            :tabid: apple-m1-cpu
-
-            .. code-block:: bash
+      .. code-block:: bash
 
-               docker run --platform='linux/arm64' --rm --name TimeSeriesTutorial --network mongodb-kafka-base_localnet -it robwma/mongokafkatutorial:latest bash
+         docker exec -it mongo1 /bin/bash
 
       Create a source configuration file called ``stock-source.json`` with the
       following command: