fix: Change memory allocation error into a warning in 'local quickstart'

docs/troubleshooting.rst

@@ -64,7 +64,7 @@ If the above command does not work, you should fix your Docker installation. Som
 
 Open edX requires at least 4 GB RAM, in particular to run the SQL migrations. If the ``tutor local quickstart`` command dies after displaying "Running migrations", you most probably need to buy more memory or add swap to your machine.
 
-On macOS, by default, Docker allocates at most 2 GB of RAM to containers. ``quickstart`` refuses to start if it detects an allocation of less than 4 GB. You should follow `these instructions from the official Docker documentation <https://docs.docker.com/docker-for-mac/#advanced>`__ to allocate at least 4-5 Gb to the Docker daemon.
+On macOS, by default, Docker allocates at most 2 GB of RAM to containers. ``quickstart`` tries to check your current allocation and outputs a warning if it can't find a value of at least 4 GB. You should follow `these instructions from the official Docker documentation <https://docs.docker.com/docker-for-mac/#advanced>`__ to allocate at least 4-5 GB to the Docker daemon.
 
 If migrations were killed halfway, there is a good chance that the MySQL database is in a state that is hard to recover from. The easiest way to recover is simply to delete all the MySQL data and restart the quickstart process. After you have allocated more memory to the Docker daemon, run::
 

tutor/commands/local.py

@@ -8,6 +8,7 @@ from .. import env as tutor_env
 from .. import fmt
 from ..types import get_typed, Config
 from .. import utils
+from .. import exceptions
 from . import compose
 from .config import save as config_save_command
 from .context import Context
@@ -44,7 +45,18 @@ def local(context: Context) -> None:
 @click.option("-p", "--pullimages", is_flag=True, help="Update docker images")
 @click.pass_context
 def quickstart(context: click.Context, non_interactive: bool, pullimages: bool) -> None:
-    utils.check_macos_memory()
+    try:
+        utils.check_macos_memory()
+    except exceptions.TutorError as e:
+        fmt.echo_alert(
+            """Could not verify sufficient RAM allocation in Docker:
+    {}
+Tutor may not work if Docker is configured with < 4 GB RAM. Please follow instructions from:
+    https://docs.tutor.overhang.io/install.html
+            """.format(
+                str(e)
+            )
+        )
 
     if tutor_env.needs_major_upgrade(context.obj.root):
         click.echo(fmt.title("Upgrading from an older release"))

tutor/utils.py

@@ -248,49 +248,46 @@ def check_output(*command: str) -> bytes:
 
 def check_macos_memory() -> None:
     """
-    Try to assert that the RAM allocated to the Docker VM on macOS is at least 4 GB.
+    Try to check that the RAM allocated to the Docker VM on macOS is at least 4 GB.
     """
     if sys.platform != "darwin":
         return
 
-    settings_path = "{}/Library/Group Containers/group.com.docker/settings.json".format(
-        os.path.expanduser("~")
+    settings_path = os.path.expanduser(
+        "~/Library/Group Containers/group.com.docker/settings.json"
     )
 
-    def warn(msg: str) -> None:
-        t = (
-            "Warning: could not check Docker RAM size from {} ({}). Tutor may not "
-            + "work if Docker is configured with < 4 GB RAM."
-        )
-        click.echo(fmt.alert(t.format(settings_path, msg)))
-
     try:
         with open(settings_path) as fp:
-            try:
-                data = json.load(fp)
-                memory_mib = int(data["memoryMiB"])
-            except json.JSONDecodeError as e:
-                warn("invalid JSON: {}:{} {}".format(e.lineno, e.colno, e.msg))
-                return
-            except (TypeError, ValueError, OverflowError) as e:
-                warn("unexpected data: {}".format(str(e)))
-                return
-            except KeyError:
-                # Value is absent (Docker creates the file with the default setting of 2048 explicitly
-                # written in, so we shouldn't need to assume a default value here.)
-                warn("key 'memoryMiB' not found")
-                return
-    except ValueError as e:
-        warn("possible encoding error when opening file: {}".format(str(e)))
-        return
-    except OSError:
-        # File not present or accessible
-        return
+            data = json.load(fp)
+            memory_mib = int(data["memoryMiB"])
+    except OSError as e:
+        raise exceptions.TutorError(
+            "Error accessing {}: [{}] {}".format(settings_path, e.errno, e.strerror)
+        ) from e
+    except json.JSONDecodeError as e:
+        raise exceptions.TutorError(
+            "Error reading {}: invalid JSON: {} [{}:{}]".format(
+                settings_path, e.msg, e.lineno, e.colno
+            )
+        ) from e
+    except (ValueError, TypeError, OverflowError) as e:
+        # ValueError from open() indicates an encoding error
+        raise exceptions.TutorError(
+            "Text encoding error or unexpected JSON data: in {}: {}".format(
+                settings_path, str(e)
+            )
+        ) from e
+    except KeyError as e:
+        # Value is absent (Docker creates the file with the default setting of 2048 explicitly
+        # written in, so we shouldn't need to assume a default value here.)
+        raise exceptions.TutorError(
+            "key 'memoryMiB' not found in {}".format(settings_path)
+        ) from e
 
     if memory_mib < 4096:
         raise exceptions.TutorError(
-            (
-                "Docker must be allocated at least 4 GiB of memory on macOS (found {} MiB). "
-                + "Please follow instructions from https://docs.tutor.overhang.io/install.html"
-            ).format(memory_mib)
+            "Docker is configured to allocate {} MiB RAM, less than the recommended {} MiB".format(
+                memory_mib, 4096
+            )
         )