Arrange Multiple Courses on Disk

Course Builder supports multitenancy. You should create and run all your courses through the Admin page. This page discusses staging your multiple courses on disk before deploying to Google App Engine. This method is for older Course Builder versions (before 1.3.0) or those who are creating their course(s) on disk.

  1. Make sure the courses can be run on the same instance.
  2. Create or copy unshared files to appropriate directories.
  3. Let Course Builder know about the multiple courses.
  4. (Only for CB 1.0 applications) Modify each course’s views to use relative URLs.

Make sure the courses can be run on the same instance.

When you host multiple courses in one instance, all of those courses must share most of their code.

Specifically, assume that APPPATH is the directory containing Course Builder. Multiple courses that run in one GAE instance must share all files and code except what is in the APPPATH/assets, APPPATH/data, and APPPATH/views directories.

If you have existing courses that you want to consolidate into one instance, first check that they share the correct code. If this is not the case, stop here. You cannot host the courses on the same instance.

Create or copy unshared files to appropriate directories.

Instead of using the top-level assets, data, and views directories, when multiple courses share an instance, they use a new top-level directory, APPPATH/courses.

This directory contains a separate subdirectory for each course. Each of those subdirectories contains assets, data, and views directories and the course.yaml file for that one course.

For example, assume that you have two courses, Algebra and Calculus. You would have files and directories such as the following:

APPPATH/app.yaml
...
APPPATH/courses/
APPPATH/courses/algebra/
APPPATH/courses/algebra/course.yaml
APPPATH/courses/algebra/assets/...
APPPATH/courses/algebra/data/...
APPPATH/courses/algebra/views/...
...
APPPATH/courses/calculus/
APPPATH/courses/calculus/course.yaml
APPPATH/courses/calculus/assets/...
APPPATH/courses/calculus/data/...
APPPATH/courses/calculus/views/...
...
APPPATH/models/models.py
...

All files and directories outside of APPPATH/assets, APPPATH/data, and APPPATH/views remain the same.

If you consolidate existing courses, make a copy of one entire APPPATH tree. Move the top-level assets, data, and views directories and course.yaml files in that copy into an appropriately named subdirectory for that course. Then create other subdirectories for your other courses and copy their assets, data, and views directories and course.yaml files into the new tree.

Let Course Builder know about the multiple courses.

Add URL routing

Once you have your files in the appropriate directory structure, you need to configure Course Builder to know where to find the courses and what URLs to use to refer to them. You do this by setting the GCB_COURSES_CONFIG environment variable in APPPATH/app.yaml.

In our example, assume that you plan to use http://www.example.com/index.html as the home page that lists all of your courses, http://www.example.com/algebra101 for the Algebra course, and http://www.example.com/calculus202for the Calculus course. In this situation, you would add the following section to app.yaml.

...
env_variables:
  GCB_COURSES_CONFIG: 'course:/algebra101:/courses/algebra, course:/calculus202:/courses/calculus'
...

GCB_COURSES_CONFIG is a comma-separated list of rules. Each rule has three parts, separated by colons:

  • Type of entry: Every rule must start with the word course. (This allows for future expansion of configuration rules.)
  • URL prefix: Specifies the URL to use for this portion of the site. In the example, the home page is accessible as http://www.example.com/ and the second unit of the Algebra course is accessible as http://www.example.com/algebra101/unit?unit=2.
  • File system location for course files: Specifies where to find the files associated with each course. In the example, the views files for Algebra 101 are stored under APPPATH/courses/algebra/views/.

GAE namespaces

When you run multiple courses in a single GAE instance, Course Builder needs a way to separate information that belongs to different courses. For example, each of your courses has a Unit 1. Course Builder needs to know which information corresponds to Unit 1 in Algebra 101 and which corresponds to Unit 1 in Calculus 202. For this purpose, it uses GAE namespaces. A namespace is a method for disambiguating collections of information.

All of your courses run in a single GAE instance, but each course runs in separate namespace. Course Builder creates the name of the namespace using the course’s file system location. Course Builder replaces slashes in the location with dashes and gives the namespace a prefix of gcb-. So in the example, the Algebra course uses the namespace name gcb-courses-algebra, based on its file system location of /courses/algebra.

(Only for CB 1.0 applications) Modify each course’s views to use relative URLs.

If you originally developed your courses using Course Builder 1.0, there’s a final step involved to run multiple courses from the same application instance. This step does not apply if you originally developed your courses with Course Builder 1.1.

In Course Builder 1.0, by default, many of the files in views/ referred to other Course Builder files using absolute URLs. An absolute URL starts with http://, https://, or /. For example, http://www.example.com/index.html and /index.html are absolute URLs. A URL that does not start with http://, https://, or / is a relative URL; for example, index.html is a relative URL. An absolute URL describes precisely where the page lives, in “absolute” terms. A relative URL describes where the page lives, relative to the current directory. For example, in CB 1.0 views/base.html contained the following line:

<link href="/assets/css/main.css" rel="stylesheet">

When you run Course Builder for only one application, /assets/css/main.css refers to APPPATH/assets/css/main.css. When you run it for multiple applications, what /assets/css/main.css refers to depends on the routing defined by GCB_COURSES_CONFIG.

To fix the URLs, first add the base tag to views/base.html and views/base_registration.html. Add the following line to both of those files, as the first line in the <head> section.

<base href="{{ gcb_course_base }}" />

This tag tells the browser where to start looking for relative URLs.

Next, check all URLs in your Course Builder 1.0 courses to make sure they’re ok.

  • Absolute URLs that start with either http:// or https:// do not change.
  • Absolute URLs that start with / (slash) probably become relative. In most cases, you change URLs pointing to files that live in a views directory. In these situations, you can simply remove the initial /. For example, change /assets/css/main.css to assets/css/main.css.