fix: require at least 4 GB RAM on macOS for 'local quickstart' only

Limits the memory chek to the 'local quickstart' command, makes error
handling more accurate and adds warning messages for some conditions.
Also adds a mention of this in troubleshooting.rst.

CHANGELOG.md

@@ -7,7 +7,7 @@ Note: Breaking changes between versions are indicated by "💥".
 ## v12.1.5 (2021-10-25)
 
 - 💥[Improvement] Change the `settheme` command such that, by default, a custom theme is assigned to the LMS and the CMS, both in production and development mode.
-- [Bugfix] Check Docker memory allocation on macOS when running tutor local commands (#463)
+- [Bugfix] Change the `local quickstart` command to check for adequate Docker memory allocation on macOS (#463)
 
 ## v12.1.4 (2021-10-11)
 

docs/troubleshooting.rst

@@ -62,7 +62,9 @@ If the above command does not work, you should fix your Docker installation. Som
 "Running migrations... Killed!" / "Command failed with status 137: docker-compose"
 ----------------------------------------------------------------------------------
 
-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 Docker for Mac OS, by default, containers are allocated at most 2 GB of RAM. 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.
+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.
 
 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

@@ -37,7 +37,6 @@ def docker_compose(root: str, config: Config, *command: str) -> int:
 @click.pass_obj
 def local(context: Context) -> None:
     context.docker_compose_func = docker_compose
-    utils.check_macos_memory()
 
 
 @click.command(help="Configure and run Open edX from scratch")
@@ -45,6 +44,8 @@ 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()
+
     if tutor_env.needs_major_upgrade(context.obj.root):
         click.echo(fmt.title("Upgrading from an older release"))
         context.invoke(

tutor/utils.py

@@ -253,27 +253,44 @@ def check_macos_memory() -> None:
     if sys.platform != "darwin":
         return
 
-    try:
-        settings_path = (
-            "{}/Library/Group Containers/group.com.docker/settings.json".format(
-                os.path.expanduser("~")
-            )
+    settings_path = "{}/Library/Group Containers/group.com.docker/settings.json".format(
+        os.path.expanduser("~")
+    )
+
+    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:
-            data = json.load(fp)
-    except Exception as e:
-        # Ignore any IO and JSON parse errors
+            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
 
-    if "memoryMiB" not in data or not isinstance(data["memoryMiB"], int):
-        # Ignore absent / erratic values (Docker creates the file with the default setting of 2048 explicitly
-        # written in, so we shouldn't need to assume a default value here).
-        return
-
-    if data["memoryMiB"] < 4096:
+    if memory_mib < 4096:
         raise exceptions.TutorError(
             (
-                "Docker must be allocated at least 4 GB of memory on macOS (found {} MB). "
+                "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(data["memoryMiB"])
+            ).format(memory_mib)
         )