Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CI codecov

OpenStax CMS

Built using Wagtail CMS on top of Django Framework. All installation instructions assume you already have Homebrew installed. If you are not running on MacOSX or a Linux distribution, see the hyperlinks for dependencies.


brew install postgresql
brew install python3


Verify you have Python ≥ 3.6 installed:

python --version
python3 --version

Start PostgreSQL:

brew services start postgresql

This will also make sure PostgreSQL service starts on boot.

Create a database (this is also a shell script), which is named as oscms_prodcms. However, it can be renamed as long as the change is reflected on the appropriate field in openstax/settings/

createdb oscms_prodcms

Now we can install the repository. Run the following commands line by line:

git clone
cd openstax-cms/
pip3 install -r requirements/dev.txt

After all the modules in requirements are installed, run the migration script:

python3 migrate

Now, create a super user. Run the following command and then proceed with the instructions:

python3 createsuperuser

Finally, start the server:

python3 runserver


To test OpenStax CMS on a local device, you need to overwrite some settings. This can be streamlined by introducing in openstax/settings/. Any changes on or additions to will overwrite settings. Make copy of and rename it to

cd openstax/settings/

Start the server:

python3 test --liveserver=localhost:8001

SQLite Support

SQLite is supported as an alternative to PostgreSQL. In order to switch to SQLite, change the DATABASES setting in openstax/settings/ to use 'django.db.backends.sqlite3', and set NAME to be the full path of your database file, as you would with a regular Django project.


To run the CMS in Docker containers:

docker-compose up

The CMS code directory from your host machine is mounted in the app container at /code. To drop into a bash terminal in the app container:

docker-compose exec -e DJANGO_SETTINGS_MODULE=openstax.settings.docker app bash

This command has been wrapped in a tiny script:


From within the bash shell, you can run the tests:

python3 test --keepdb

or pound on a specific test:

python3 test --keepdb books.tests.BookTests.test_can_create_book

The --keepdb option reuses the test database from run to run so you don't have to wait for it to recreate the database and run the migrations every time.

To debug tests, you can insert the normal import pdb; pdb.set_trace() lines in your code and test runs from the bash environment will show you the debugger.

API Endpoints

View the Wiki Page for the list of all available API endpoints and their descriptions.