Skip to content

Onboarding Getting Started

Jump to bottom
Armando Fox edited this page Jun 7, 2023 · 15 revisions

#0. From 10,000 feet (or, From 3,048 meters)

  • We operate a campus server confusingly named cbt-dev.berkeley.edu where you can login with CalNet credentials; that is where students go to do homeworks/take exams on PL.

  • Your course team will do all your authoring in a GitHub repo, which you periodically sync to that server. You will not use the server for authoring. You can run PL locally on your own computer and do your authoring that way, then commit the results to GitHub.

  • One-time setup for a new course involves (1) creating a new course repo, (2) creating a team of people who have access to it, (3) creating the course on the PL server and linking it to the repo. These are steps we do with information from you.

  • Once a course is set up, you can add/remove course staff from the team as needed, and you can sync your course to the server any time things change.

  • There's essentially two "levels" of authoring PL content. "Basic level" means you use PL's built-in elements to author questions. An element is a prebuilt chunk of a question, and there's lots and lots of them: see the official docs. To use elements, you are just authoring basic HTML mixed in with "element markup", but you don't have to write any code. (Though with some elements, writing a small amount of code can greatly enhance what the element can do, such as generating random parameters for a question rather than having the question content be completely static.) For some information on how to go beyond the basic examples in the official docs, check the wiki page on Question writing for the impatient.

  • "Advanced level" means you are creating your own interactive questions that either combine elements in a novel way, or require interactive functionality not provided by any existing element. Perhaps you do this by creating your own one-off questions, or perhaps you do it by creating a new element type that others can then use in the future to create similar questions. Either way, depending on the functionality and complexity of your question, you will be writing server-side code in Python and possibly client-side code in JavaScript.

1. Get connected to teams

Who's Who: Make sure the current "Personnel" tab of this spreadsheet includes your contact info, course affiliation, faculty advisor, etc.

Slack access: Make sure you're part of the berkeley-private channel on the PrairieLearn Slack. If not, email Prof. Fox and he'll add you.

If possible, please use your real name and a real photo on both Slack and Github so we know who you are. We understand if there are historical or other reasons you prefer not to reveal your identity on Github, but with a lot of users, it's getting hard to know who's who.

It is safe to use the berkeley-private channel to discuss "semi-confidential" private topics, e.g. QG content, as UIUC generally doesn't monitor that channel. If you're unable to get your questions answered within berkeley-private, use the pl-help channel to ask (polite, well-formed, concise) questions about general QG development, using PL, etc., and the pl-dev channel specifically about developing new Elements or contributing to core PL development.

GitHub access: All onboarded developers are given read access to the pl-ucb-csxxx repo, which includes example questions and other useful stuff. To get access to the repo for the course you're working on, find an owner/admin of that repo and ask them to add you to the appropriate team. Repo names are pl-school-course, eg pl-ucb-cs61b, pl-csulb-cecs303, and so on. Team names are based on repo names but begin with pl-dev- rather than just pl-, e.g. pl-dev-ucb-cs61b.

2. Get PrairieLearn running locally

  1. Install the free Docker Community Edition on your Mac, Windows, or Linux computer. Windows users note: You want the Community Edition, not the Toolbox. Windows Home Edition doesn’t support running this, but Windows 10 Pro or Edu does. Anyone with a CalNet ID can get Windows 10 Edu from software.berkeley.edu.

  2. If you are developing course content only and not planning to modify PL itself, the simplest install is by pointing Docker at the PL repo. If you plan to modify PL itself (and if so, please let a faculty member know, since changes to PL must be carefully coordinated), you can Install PrairieLearn onto your local Docker. Either way, follow the instructions carefully and methodically. Be particularly careful about punctuation, spaces, etc. as the Docker command lines are quite elaborate. (HINT: wherever an example suggests using $PWD to expand to the full path of the current working directory, if using Windows remember that the equivalent Windows-ism is %cd%) The first time you run PL, it will take up to 30 minutes to download and install a whole bunch of stuff, so you can do other work in the background meanwhile. NOTE: If you're having problems with PL, make sure you're on the latest released version by running docker pull prairielearn/prairielearn when PL is not running locally.

  3. Start PL locally (instructions still in that same doc) and visit http://localhost:3000/pl to access PL. In the top navbar click "Load from Disk" to load some test courses into PL. (In the future, you’ll instead be loading up your own courses and assessments.)

The usual way to start PL locally is as follows, assuming /path/to/your/course is the FULL path name to a git repo representing your course. Such Git repos live in the ace-lab GitHub org and have names beginning with pl-ucb-, as in ace-lab/pl-ucb-cs10.

docker run -it --rm -p 3000:3000 -v /path/to/your/course:/course prairielearn/prairielearn

For example, if your PL repo is pl-ucb-123 then this is how you would start PL locally. First, cd into the pl-ucb-123 directory. Next, run one of the following commands based on your operating system:

  • For Mac and Linux users:
docker run -it --rm -p 3000:3000 -v $PWD:/course prairielearn/prairielearn
  • For Windows users:
docker run -it --rm -p 3000:3000 -v %cd%:/course prairielearn/prairielearn

This tells Docker to make the directory /path/to/your/course available as /course from PL's point of view. If you are working with several different course repos, you can give additional -v options but you must specify /course2, /course3, etc. as the PL mount point. (Up to 9 are allowed.)

  1. Once the load-from-disk sequence finishes, click PrairieLearn (top left) to return to main PL view. Under Course Instances (NOT Courses), click one of the courses, and start clicking around to look at the different questions, to get a sense of what is possible. (Or just click on Questions in the top navbar.)

3. IMPORTANT: Advance notice needed when running assessments

If you're planning to run an exam or have a homework due date that is likely to generate any nontrivial surge on PL (more than about 30 students submitting simultaneously), you must give a minimum of 24 hours heads up on the #berkeley-cbt-ops slack channel, so that it gets added to the CBT Ops calendar and the ops staff can provision accordingly. If you fail to do this, you may have technical problems during an exam, and there is no "on-call help". You will probably have no choice but to stop and reschedule your exam, and nobody wants that.

Clone this wiki locally