Add Tutor Op & Dev Quickstarts

sarina · sarina · commit 038d13f9f574 · 2025-07-04T15:28:36.000-04:00
Add pointers to common task instructions

Add Tutor MFE dev quickstart

Add warning about using ChatGPT for Tutor help

Small fixes

Apply suggestions from code review

Co-authored-by: Taylor Payne &lt;taylor.payne@wgu.edu&gt;

Apply suggestions from code review
diff --git a/source/developers/concepts/tutor.rst b/source/developers/concepts/tutor.rst
@@ -7,6 +7,16 @@ What is Tutor?
 
 This video, by Edly Academy, explains the basic concepts of Tutor.
 
+.. warning::
+
+   LLMs, like ChatGPT, generate answers based on patterns in large-scale public content.
+   Since Open edX and Tutor have relatively small footprints in that data, answers from
+   these models are often incorrect. We recommend you
+   only follow instructions about Tutor from pages on https://docs.openedx.org
+   or https://docs.tutor.edly.io/. For help, search for answers on the `Open edX
+   Forums`_ and feel free to make your own post if you do not find the answer
+   you are searching for.
+
 .. youtube:: BzNcrmyFpw4
 
 .. seealso::
@@ -15,6 +25,8 @@ This video, by Edly Academy, explains the basic concepts of Tutor.
 
    :ref:`qs Dev First PR`
 
+.. include:: /links.txt
+
 **Maintenance chart**
 
 +--------------+-------------------------------+----------------+--------------------------------+
diff --git a/source/developers/quickstarts/tutor_quickstart_dev.rst b/source/developers/quickstarts/tutor_quickstart_dev.rst
@@ -3,7 +3,7 @@
 Tutor Quickstart (Developer)
 #############################
 
-.. tags:: site operator, quickstart
+.. tags:: developer, quickstart
 
 .. admonition:: tutor main vs tutor local
 
@@ -14,12 +14,95 @@ Tutor Quickstart (Developer)
    instance. See :ref:`Tutor QS (Operator)` if you wish to deploy an Open edX
    instance.
 
+   Also, it is helpful to first watch the video on the :ref:`Tutor Concept
+   (Dev)` page before embarking on your Tutor journey.
+
+
+Tutor was designed to make it easy for everyone to run the latest Open edX
+release, either for development or production environments. In this Quickstart
+we will walk you through how to set up Tutor Main for development on "master"
+(the latest code being developed for the next named release). This Quickstart
+walks through the basics of setting up Tutor for edx-platform development. For MFE development, you will want
+to continue on to :ref:`Tutor for MFE QS`.
+
+Requirements
+*************
+
+* Supported OS: Tutor runs on any 64-bit, UNIX-based OS. It has also been reported to
+  work on Windows (with `WSL 2
+  <https://docs.microsoft.com/en-us/windows/wsl/install>`__).
+* Architecture: Both AMD64 and ARM64 are supported.
+* Required software:
+
+  * `Docker <https://docs.docker.com/engine/installation/>`__: v24.0.5+ (with BuildKit 0.11+)
+
+  * `Docker Compose <https://docs.docker.com/compose/install/>`__: v2.0.0+ (installed by default with Docker Desktop)
+
+.. warning::
+
+    Do not attempt to simply run ``apt-get install docker docker-compose`` on older Ubuntu platforms,
+    such as 16.04 (Xenial), as you will get older versions of these utilities.
+
+
+* Hardware:
+
+  * Minimum configuration: 4 GB RAM, 2 CPUs, 8 GB disk space
+  *    Recommended configuration: 8 GB RAM, 4 CPUs, 25 GB disk space
+
+.. note::
+
+    On Mac OS, by default, containers are allocated 2 GB of RAM, which is not enough.
+    You should follow `these instructions from the official Docker documentation <https://docs.docker.com/desktop/settings-and-maintenance/settings/#resources>`__
+    to allocate at least 4-5 GB to the Docker daemon. If the deployment fails because
+    of insufficient memory during database migrations, check the `relevant section in
+    the troubleshooting guide <https://docs.tutor.edly.io/troubleshooting.html#migrations-killed>`_.
+
+Set Up Tutor for Development
+************************************
+
+
+#. Fork the `edx-platform GitHub repo
+   <https://github.com/openedx/edx-platform>`_ and clone it locally. Then run
+   ``git switch master`` to ensure you are on the master branch. If you
+   already have a fork, first sync it to the current upstream version.
+
+#. Set up a `new virtual environment
+   <https://docs.python.org/3/tutorial/venv.html>`_ for your Tutor environment
+   and activate it:
+
+   .. code-block:: bash
+
+      python -m venv /path/to/new/virtual/environment
+      source /path/to/new/virtual/environment/bin/activate
+
+#. Follow the instructions to `install Tutor Main <https://docs.tutor.edly.io/tutorials/main.html>`_.
+
+#. Follow the instructions to `have Tutor use your local fork
+   <https://docs.tutor.edly.io/dev.html#first-time-setup>`_. Continue to follow
+   the instructions to build the images and launch Tutor using ``tutor dev
+   launch``.
+
+#. Next, review the `common Tutor tasks
+   <https://docs.tutor.edly.io/local.html#common-tasks>`_ for commands used to
+   create superusers, import the "Open edX Demo Course", and set themes.
+
+Congratulations! You are now running Tutor, on the master branch, in dev mode!
+
+See the `Tutor tutorial about working on edx-platform`_ for more details on
+what's going on behind the scenes.
+
 .. seealso::
 
-   :ref:`Tutor Concept (Operator)`
+   :ref:`Tutor Concept (Dev)`
 
    :ref:`qs Dev First PR`
 
+   `Tutor tutorial about working on edx-platform`_
+
+   :ref:`Tutor for MFE QS`
+
+.. _Tutor tutorial about working on edx-platform: https://docs.tutor.edly.io/tutorials/edx-platform.html
+
 **Maintenance chart**
 
 +--------------+-------------------------------+----------------+--------------------------------+
diff --git a/source/developers/quickstarts/tutor_quickstart_mfe.rst b/source/developers/quickstarts/tutor_quickstart_mfe.rst
@@ -0,0 +1,40 @@
+.. _Tutor for MFE QS:
+
+Tutor Quickstart (MFE Development)
+##################################
+
+.. tags:: developer, quickstart
+
+.. note::
+
+   You should go through the :ref:`Tutor QS (Dev)` to set up the basics of Tutor
+   before moving on to this Quickstart.
+
+#. Review the `Tutor documentation on Tutor plugins <https://docs.tutor.edly.io/plugins/intro.html>`_.
+
+#. `Install the tutor-mfe plugin
+   <https://github.com/overhangio/tutor-mfe?tab=readme-ov-file#installation>`_.
+   Follow the "Usage" section to enable the plugin (note this is installed
+   already in the default Tutor installation).
+
+#. Read the `tutor-mfe documentation on MFE development
+   <https://github.com/overhangio/tutor-mfe?tab=readme-ov-file#mfe-development>`_
+   to learn how to run an MFE in development mode and how to mount a local fork.
+
+.. seealso::
+
+   :ref:`Tutor Concept (Operator)`
+
+   :ref:`Tutor QS (Dev)`
+
+   `tutor-mfe plugin <https://github.com/overhangio/tutor-mfe>`_
+
+   :ref:`qs Dev First PR`
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
++--------------+-------------------------------+----------------+--------------------------------+
+|              |                               |                |                                |
++--------------+-------------------------------+----------------+--------------------------------+
diff --git a/source/site_ops/concepts/tutor.rst b/source/site_ops/concepts/tutor.rst
@@ -7,6 +7,16 @@ What is Tutor?
 
 This video, by Edly Academy, explains the basic concepts of Tutor.
 
+.. warning::
+
+   LLMs, like ChatGPT, generate answers based on patterns in large-scale public content.
+   Since Open edX and Tutor have relatively small footprints in that data, answers from
+   these models are often incorrect. We recommend you
+   only follow instructions about Tutor from pages on https://docs.openedx.org
+   or https://docs.tutor.edly.io/. For help, search for answers on the `Open edX
+   Forums`_ and feel free to make your own post if you do not find the answer
+   you are searching for.
+
 .. youtube:: BzNcrmyFpw4
 
 .. seealso::
diff --git a/source/site_ops/quickstarts/tutor_quickstart_ops.rst b/source/site_ops/quickstarts/tutor_quickstart_ops.rst
@@ -12,12 +12,42 @@ Tutor Quickstart (Operator)
    ``tutor main`` should be used by developers when writing code for the
    master/main branches. See :ref:`Tutor QS (Dev)` if you are developing code.
 
+   Also, it is helpful to first watch the video on the :ref:`Tutor Concept
+   (Operator)` page before embarking on your Tutor journey.   
+
+
+.. admonition:: Which version of Tutor to use?
+
+   Find out what the latest release of Tutor is, and ensure you are using that
+   version. The Open edX project only supports one release at a time, so running
+   an older release will mean you don't have the latest features, bugfixes, and
+   security fixes.
+
+   See the `versioning section of the Tutor docs <https://docs.tutor.edly.io/tutor.html#versioning>`_
+   for more about versioning. The `releases section of the Tutor docs <https://docs.tutor.edly.io/install.html#running-older-releases-of-open-edx>`_
+   will show which version is the latest. You can also check out the
+   `Open edX Releases Homepage <https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4191191044/Open+edX+Releases+Homepage>`_
+   to learn more about the latest and upcoming Open edX release.
+
+#. Follow the `instructions for installing Tutor`_.
+
+#. Next, review the `common Tutor tasks
+   <https://docs.tutor.edly.io/local.html#common-tasks>`_ for commands used to
+   create superusers, import the "Open edX Demo Course", and set themes.
+
+Congratulations! You are now running Tutor, on the latest named release.
+
 .. seealso::
 
-   :ref:`Tutor Concept (Dev)`
+   :ref:`Tutor Concept (Operator)`
 
    :ref:`Site Operator QS`
 
+   `Instructions for installing Tutor`_
+
+
+.. _Instructions for installing Tutor: https://docs.tutor.edly.io/install.html
+
 **Maintenance chart**
 
 +--------------+-------------------------------+----------------+--------------------------------+
