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.
- Make sure the courses can be run on the same instance.
- Create or copy unshared files to appropriate directories.
- Let Course Builder know about the multiple courses.
- (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/calculus202
for 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 ashttp://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://
orhttps://
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
toassets/css/main.css
.