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.

Dependencies

• PostgreSQL (≥ 13)

brew install postgresql

• Python (≥ 3.11)
• PIP

brew install python3

Installation

Verify you have Python ≥ 3.11 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/base.py:

createdb oscms_prodcms

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

git clone https://github.com/openstax/openstax-cms
cd openstax-cms/
pip3 install -r requirements/dev.txt

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

python3 manage.py migrate

If you've made changes to Django models and need to create a new migration:

python3 manage.py makemigrations

Note: If you encounter import errors when running makemigrations, you may need to create a local settings file first:

cp openstax/settings/local.py.example openstax/settings/local.py

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

python3 manage.py createsuperuser

Finally, start the server:

python3 manage.py runserver

Testing

To test OpenStax CMS on a local device, you need to overwrite some settings. This can be streamlined by introducing local.py in openstax/settings/. Any changes on or additions to local.py will overwrite settings. Make copy of local.py.example and rename it to local.py: Alternatively, and maybe more conveniently, use a .env file in the project root to set environmental variables.

cd openstax/settings/
cp local.py.example local.py

Run the tests:

python3 manage.py test --settings=openstax.settings.test

Postman API Testing

To test the API, use can request access to the OpenStax Postman account.
The collection is available here.

SQLite Support

SQLite is supported as an alternative to PostgreSQL. In order to switch to SQLite, change the DATABASES setting in openstax/settings/base.py 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.

Docker

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:

./docker/bash

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

python3 manage.py test --keepdb

or pound on a specific test:

python3 manage.py 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.

Documentation

• CMS Editing Documentation
• CMS Branching and Releases
• CMS Pull Requests