Axim engineers can deploy “sandbox” Open edX sites on certain pull requests in the openedx GitHub organization in order help test changes. These sandboxes are managed by OpenCraft using the Grove PR watcher.

Table of contents:

Links & References

• Slack channel : #grove-pr-watcher

• Grove PR watcher docs

• Grove PR watcher source code, on GitLab

• Tutor plugin for Grove, on GitLab

• [internal] Axim<->OpenCraft contract materials

Getting a sandbox on a PR

This guide is for Axim engineers. If you’re a contributor and you’d like to use this system for your PR, talk to your Axim POC (for funded contributions) or file an Axim request (all others). If we have the capacity, we may be able to set you up with one.

• Prerequisite: The PR’s target repository must be openedx/edx-platform or openedx/frontend-app-*

• The PR author can be anyone.

• Ensure that the target repository has the pr-sandboxes-enabled topic. Anyone with admin access to the repo can edit topics by going to the repo home page and clicking the gear next to “About”:

  Open

  

   

• Optionally, add a **Settings** and/or **Tutor Requirements** section to the PR’s description in order to customize the sandbox. Details here.

• Add the create-sandbox label to the PR

• Wait 30 minutes. One of three things should happen:

  1. open-craft-grove will tell you “Sandbox deployment successful “

  2. open-craft-grove will tell you “Sandbox deployment failed “

     1. Check out the linked Grove logs-- they may or may not help you figure out the problem. Unfortunately, the app logs are not available to us.

  3. nothing

• In case (b) or (c), join the #grove-pr-watcher Slack channel and ping Kaustav with a link to the PR.

Notes on sandbox behavior

• The admin username is openedx and the password is the same. If you want to secure your sandbox’s data against public access, then change the admin password. You should also be able to create unprivileged user accounts as necessary.

• The sandbox will redeploy every ~15 minutes if either of the following conditions are met:

  • The PR’s latest commit hash has changed

  • The PR’s Settings or Tutor Requirements sections have changed

• The sandbox will be destroyed after ~15 minutes if either of the following conditions are met:

  • The create-sandbox label has been removed

  • The PR is merged or closed

• When the sandbox redeploys, its database is preserved. To fully destroy and recreate with a fresh db, you will need a workaround:

  • Remove the create-sandbox label

  • Wait ~15 minutes

  • Check that the sandbox has been destroyed by going to the LMS. You should see a message like “This site is being provisioned”.

  • Put the create-sandbox label back

• If your edx-platform branch (or the configured EDX_PLATFORM_VERSION) has migration changes that are incompatible with migrations that have already been applied to the sandbox’s db, then you will need to fully destroy and recreate with a fresh db (see above). A couple ways this can happen: force-pushing a modified migration; switching the base branch from master to <release>.master or vice-versa.

• Idle sandboxes will be destroyed after weeks of inactivity. You can bring them back to life by pushing a new commit or rebasing your PR.

• We have a usage budget for about 30 running instances. OpenCraft will let us know if we’re bumping up against that.

• PRs to master/main will use Tutor Nightly. PRs to named release branches will use the latest patch release of the corresponding Tutor version (e.g., Quince → tutor>=17,<18). The Tutor version can be overridden using the Tutor Requirements section, as explained in the docs.

Scope for PR sandbox improvement discovery (Jan 2025)

In priority order, here are the PR sandbox improvements Axim is interested in having scoped out:

1. Better status communication (via GitHub checks?)

   • We need to be immediately notified when a sandbox rebuild has been triggered.

     • By corollary, a developer should understand that if NOTHING HAPPENS, then no sandbox is building, and no sandbox will build.

     • This should all be true even if the code or the sandbox configuration is completely messed up. Fail quickly and loudly!

   • At the same time, we do not want to overwhelm folks who are subscribed to the PR with notifications. 3 GitHub comments per push is not acceptable.

   • Proposed solution: As a replacement to the current PR comment… have the PR sandbox build create a GitHub status check, which shows the status of the build (pending, in progress, failed, success) and links out to a status page which includes:

     • the deployment logs,

     • links the deployment config, and

     • If successful, links to LMS, Studio, LMS admin and CMS admin.

     • [Stretch/Nice-to-have] Buttons to (a) update the sandbox and (b) destroy and recreate the sandbox. We realize that this may be significantly higher scope than the other items in the list… if so, then please do not spend too much discovery time on this rather than items 2-5.

     • Examples like the proposed solution: Netlify, Vercel

   • Whatever you come up with, we will want to continue to be able to view a list of existing sandboxes. Today, we can do this easily by searching the openedx org for the create-sandbox label. If the label remains, then this task is a no-op. If you get rid of the label, then we would need an alternative approach.

2. More access

   • We need access to application logs.

   • We would like certain Axim engineers to be able to have SSH access to the boxes.

3. Easier installation of Tutor plugins

   • Installing or modifying Tutor plugins is a very common use-case. One problem right now is that specifying the “Tutor requirements” list in the PR description will wholesale replace the default Tutor requirements, thus leaving the sandbox broken if the user doesn’t know to specify the right base requirements (tutor-contrib-grove, tutor-contrib-s3, etc.)

   • Example…

     • The user of this PR’s sandbox wanted just to install a patched version of Tutor:

       • git+https://github.com/brian-smith-tcril/tutor.git@nightly-node18-patched

     • In order to get the sandbox working, they had to repeatedly edit the requirements list via trial-and-error until they finally got a working box by specifying:

       • git+https://github.com/brian-smith-tcril/tutor.git@nightly-node18-patched git+https://github.com/overhangio/tutor-mfe.git@nightly git+https://gitlab.com/opencraft/dev/tutor-contrib-grove.git@main git+https://github.com/hastexo/tutor-contrib-s3.git@main git+https://github.com/overhangio/tutor-forum.git@nightly

   • Ideas:

     • Make the “Tutor requirements” list act as a list of requirement overrides and additions rather than a wholesale replacement of the default requirements list.

     • Have a consolidated single “tutor-contrib-pr-sandbox” requirement which transitively installs tutor, grove, s3, and anything else that the sandbox needs.

     • As a last resort… make the docs extremely clear and up-to-date regarding which base requirements need to be included.

4. More examples in the docs

   • Grove configuration is very powerful, but it can be confusing how to interact with the different layers (Grove, Tutor, Open edX) and accomplish various common tasks. Particularly, we need an example of a PR or PRs which:

     • Overrides a Waffle flag

     • Overrides a value in MFE_CONFIG

     • Enables a new custom micro-frontend

     • Points to a fork/branch of an existing micro-frontend

     • Adds a custom Tutor plugin

     • Point to a fork/branch of an existing Tutor plugin

     • Uses site configuration

     • Uses a custom brand

5. Auto-provisioned data

   • We’d like each instance to be pre-provisioned with:

     • A list of course runs to import, each specified by:

       • an Org, Course, and Run

       • a URL to a tar.gz file

       • By default, this list should include one item:

         • - org: OpenedX course: DemoX run: DemoCourse url: https://github.com/openedx/openedx-test-course/blob/master/dist/test-course.tar.gz

     • A user instructor@openedx.org (PW=instructor) who is an instructor in all courses

     • A user learner@openedx.org (PW=learner) who is enrolled in all courses

     • Note: We do not necessarily need the demo library to be imported.