From 66b14a5b162a1551c82027cecb517ceb9bb6a8b4 Mon Sep 17 00:00:00 2001
From: Braden MacDonald <braden@opencraft.com>
Date: Thu, 10 Oct 2024 14:02:42 -0700
Subject: [PATCH] docs: update the README with an easy way to run the MFE on
 your host (#1364)

---
 .env             |  1 +
 .env.development |  1 +
 .env.test        |  1 +
 README.rst       | 83 +++++++++++++++++++++++++++++++++---------------
 package.json     |  1 +
 5 files changed, 61 insertions(+), 26 deletions(-)

diff --git a/.env b/.env
index ec000feba0..343e480ea5 100644
--- a/.env
+++ b/.env
@@ -1,3 +1,4 @@
+APP_ID='course-authoring'
 NODE_ENV='production'
 ACCESS_TOKEN_COOKIE_NAME=''
 BASE_URL=''
diff --git a/.env.development b/.env.development
index 1cc8f24da6..b25d3e3677 100644
--- a/.env.development
+++ b/.env.development
@@ -1,3 +1,4 @@
+APP_ID='course-authoring'
 NODE_ENV='development'
 ACCESS_TOKEN_COOKIE_NAME='edx-jwt-cookie-header-payload'
 BASE_URL='http://localhost:2001'
diff --git a/.env.test b/.env.test
index 7c591ff68e..5b3769bfbd 100644
--- a/.env.test
+++ b/.env.test
@@ -1,3 +1,4 @@
+APP_ID='course-authoring'
 ACCESS_TOKEN_COOKIE_NAME='edx-jwt-cookie-header-payload'
 BASE_URL='http://localhost:2001'
 CREDENTIALS_BASE_URL='http://localhost:18150'
diff --git a/README.rst b/README.rst
index 4588f3c5e3..61015ad949 100644
--- a/README.rst
+++ b/README.rst
@@ -18,51 +18,82 @@ Getting Started
 Prerequisites
 =============
 
-The `devstack`_ is currently recommended as a development environment for your
-new MFE.  If you start it with ``make dev.up.lms`` that should give you
-everything you need as a companion to this frontend.
-
-Note that it is also possible to use `Tutor`_ to develop an MFE.  You can refer
-to the `relevant tutor-mfe documentation`_ to get started using it.
-
-.. _Devstack: https://github.com/openedx/devstack
+`Tutor`_ is currently recommended as a development environment for the Authoring
+MFE. Most likely, it already has this MFE configured; however, you'll need to
+make some changes in order to run it in development mode. You can refer
+to the `relevant tutor-mfe documentation`_ for details, or follow the quick
+guide below.
 
 .. _Tutor: https://github.com/overhangio/tutor
 
 .. _relevant tutor-mfe documentation: https://github.com/overhangio/tutor-mfe#mfe-development
 
-Configuration
-=============
 
-All features that integrate into the edx-platform CMS require that the ``COURSE_AUTHORING_MICROFRONTEND_URL`` Django setting is set in the CMS environment and points to this MFE's deployment URL. This should be done automatically if you are using devstack or tutor-mfe.
+Cloning and Setup
+=================
+
+1. Clone your new repo:
+
+.. code-block:: bash
+
+    git clone https://github.com/openedx/frontend-app-authoring.git
+
+2. Use node v20.x.
 
-Cloning and Startup
-===================
+  The current version of the micro-frontend build scripts supports node 20.
+  Using other major versions of node *may* work, but this is unsupported.  For
+  convenience, this repository includes an ``.nvmrc`` file to help in setting the
+  correct node version via `nvm <https://github.com/nvm-sh/nvm>`_.
 
+3. Stop the Tutor devstack, if it's running: ``tutor dev stop``
 
-1. Clone the repo:
+4. Next, we need to tell Tutor that we're going to be running this repo in
+   development mode, and it should be excluded from the ``mfe`` container that
+   otherwise runs every MFE. Run this:
 
-  ``git clone https://github.com/openedx/frontend-app-course-authoring.git``
+.. code-block:: bash
 
-2. Use node v18.x.
+    tutor mounts add /path/to/frontend-app-authoring
 
-   The current version of the micro-frontend build scripts support node 18.
-   Using other major versions of node *may* work, but this is unsupported.  For
-   convenience, this repository includes an .nvmrc file to help in setting the
-   correct node version via `nvm use`_.
+5. Start Tutor in development mode. This command will start the LMS and Studio,
+   and other required MFEs like ``authn`` and ``account``, but will not start
+   the Authoring MFE, which we're going to run on the host instead of in a
+   container managed by Tutor. Run:
 
-3. Install npm dependencies:
+.. code-block:: bash
 
-  ``cd frontend-app-course-authoring && npm install``
+    tutor dev start lms cms mfe
 
+Startup
+=======
 
-4. Start the dev server:
+1. Install npm dependencies:
+
+.. code-block:: bash
+
+  cd frontend-app-authoring && npm ci
+
+2. Start the dev server:
+
+.. code-block:: bash
+
+  npm run dev
+
+Then you can access the app at http://apps.local.openedx.io:2001/course-authoring/home
+
+Troubleshooting
+---------------
 
-  ``npm start``
+If you see an "Invalid Host header" error, then you're probably using a different domain name for your devstack such as
+``local.edly.io`` or ``local.overhang.io`` (not the new recommended default, ``local.openedx.io``). In that case, run
+these commands to update your devstack's domain names:
 
+.. code-block:: bash
 
-The dev server is running at `http://localhost:2001 <http://localhost:2001>`_.
-or whatever port you setup.
+  tutor dev stop
+  tutor config save --set LMS_HOST=local.openedx.io --set CMS_HOST=studio.local.openedx.io
+  tutor dev launch -I --skip-build
+  tutor dev stop authoring  # We will run this MFE on the host
 
 
 Features
diff --git a/package.json b/package.json
index 27bc40d4b7..b59524e96b 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,7 @@
     "snapshot": "TZ=UTC fedx-scripts jest --updateSnapshot",
     "start": "fedx-scripts webpack-dev-server --progress",
     "start:with-theme": "paragon install-theme && npm start && npm install",
+    "dev": "PUBLIC_PATH=/course-authoring/ MFE_CONFIG_API_URL='http://localhost:8000/api/mfe_config/v1' fedx-scripts webpack-dev-server --progress --host apps.local.openedx.io",
     "test": "TZ=UTC fedx-scripts jest --coverage --passWithNoTests",
     "test:ci": "TZ=UTC fedx-scripts jest --silent --coverage --passWithNoTests",
     "types": "tsc --noEmit"