Potential issue with default Tutor configuration in MacOS

Site Operators
1

Current setup:

  • Tutor v16.0.2
  • Mac OS Ventura 13.4.1
  • Docker Desktop for Mac 4.21.1 (Docker Engine 24.0.2, Compose 2.19.1)

What’s the issue?

My tutor setup was working fine, and I was experimenting with custom plugins, when I ran into an unusual issue whilst running the tutor images build all command, in which I inexplicably kept running into the following error:

ERROR: failed to solve: process "/bin/sh -c openedx-assets themes     && openedx-assets collect --settings=tutor.assets     && rdfind -makesymlinks true -followsymlinks true /openedx/staticfiles/" did not complete successfully: exit code: 1

Error: Command failed with status 1: docker buildx build --tag=docker.io/overhangio/openedx:16.0.2 --output=type=docker --cache-from=type=registry,ref=docker.io/overhangio/openedx:16.0.2-cache /Users/myusername/Library/Application Support/tutor/env/build/openedx

I couldn’t help but notice the space between the words Application and Support in the path. Typically, one would wrap the entire path in quotes. I have suspicions that the complex web of scripts handling tutor is not accounting for potential spaces in the path.

How did this come to be?

Let’s rewind a little bit.

When creating a plugin, the Tutor documentation says to create a directory for the tutor plugins, based on the output of tutor plugins printroot:

$ mkdir -p "$(tutor plugins printroot)"

In the case of Mac OS, this defaults to the Application Support folder, which unfortunately has a space in the name.

$ echo "$(tutor plugins printroot)" results in Users/myusername/Library/Application Support/tutor-plugins

Likewise, the output of $ echo "$(tutor config printroot)" is Users/myusername/Library/Application Support/tutor

How did I resolve this issue?

I scoured the forum and stumbled across this useful post, which encourages modifying the default environmental variables:

In my case, I created a dev folder in my home folder (you’re obviously welcome to use any other name, but please avoid using spaces):

cd; mkdir dev; cd dev

Then, making sure I had only one terminal window open, I ran the following commands, as specified in the post referenced above.

Note: my system uses zsh, but yours may use bash or another shell, in which case you’ll have to change .zshrc to .bashrc, .bash_profile, or something else.

echo "export TUTOR_ROOT=$(pwd)/tutor" >> ~/.zshrc
echo "export TUTOR_PLUGINS_ROOT=$(pwd)/tutor-plugins" >> ~/.zshrc

Afterwards, be sure to reload your shell to make sure those variables are stored properly. Check them like this:

echo "$(tutor plugins printroot)"
echo "$(tutor config printroot)"

My results:
TUTOR_ROOT = /Users/myusername/dev/tutor
TUTOR_PLUGINS_ROOT = /Users/mysername/dev/tutor-plugins

To summarize, I was able to resolve the issue by changing the tutor defaults to use a path without spaces in the name. To ensure this wasn’t forgotten by the system, I added those customizations to my shell profile.

The results work!

Afterwards, I ran the tutor build images all command and had no issues whatsoever.

Moving forward

I’m hoping the great team at Tutor will either:

  1. update the tutor code to fully support paths with spaces, or
  2. update the documentation to ensure people using Mac OS don’t run into the same issues.