Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

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

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”:

    image-20240625-153906.png

  • 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.

Known issues & wishes

Axim engineers, as you encounter things about the sandboxes that you wish could be improved, add them here. For items that seem like bugs, also ping in #grove-pr-watcher.

  • More access

    • to application logs (Need to have)

    • to the box itself via ssh (Nice to have)

  • Better status communication

    • Always fail loudly. That is: when you request a sandbox, something should happen. Either you should get a sandbox, or get a failure notification. No ghosting! 👻 This is true about 80% of the time now, but that 20% is enough to shake our confidence in the system as a whole.

      • Note: We used to have comments for this, but turned them off because they were too noisy. Would there be a less noisy way of notifying?

      • Idea: Use the GitHub checks system rather than bot comments

      • Idea: Configurable notification levels

      • Idea: Use one comment, and amend it to the update the status over time

    • Dashboard of existing sandboxes.

  • More examples in the docs on how to do complex configuration, including

    • MFE config

    • Waffle flags

    • Custom MFEs

    • Using branches/tags of Tutor plugins

    • Site configuration (broken link in tutor-contrib-grove)

  • More controls

    • Ability to fully destroy and recreate the sandbox without using the remove-label-wait-and-put-it-back workaround described above.

    • Ability to force a redeploy without pushing a commit. This can be desirable when a change is pushed to a dependency other than the PR itself (e.g. a Tutor branch).

  • Auto-provisioned data

    • openedx-demo-course, with configuration fork/branch

    • openedx-test-course, with configuration fork/branch

  • Auto-deploy from a tag or branch without having to have a PR

    • master

    • release branches

    • (This was an old action item. It seems unnecessary now that we have Adolfo’s openedx.io sandboxes, unless he wants to stop having to manually manage those)

  • No labels