France Université Numérique introduces an alternative Docker
approach to
install a complete and customized version of Open edX.
The idea is to handcraft a Dockerfile
, in order to make the project simpler,
more flexible and fully operable by developers.
We hope this kind of Docker
configuration can soon be included in the
edx-platform repository itself.
This project builds a docker image that is ready for production.
At France Université Numérique, we are deploying Open edX Docker to OpenShift, for many customers and in multiple environments using Arnold:
- The Open edX settings were polished to unlock powerful configuration management features: sensible defaults, flexible overrides using YAML files and/or environment variables, secure credentials using Ansible Vault and PGP keys,
- We focused on a best practice installation of
edxapp
, the core Open edX application. You can build you own image by adding specific Xblocks or Django apps in aDockerfile
inheriting from this one (see https://github.com/openfun/fonzie for an example).
Docker compose is only used for development purposes so that we can code locally and see our changes immediately:
- sources and configuration files are mounted from the host,
- the Docker CMD launches Django's development server instead of
gunicorn
, - ports are opened on the application containers to allow bypassing
nginx
.
Docker compose also allows us to run a complete project in development, including database services which in production are not run on Docker. See the docker-compose file for details on each service:
- mysql: the SQL database used to structure and persist the application data,
- mongodb: the no-SQL database used to store course content,
- memcached: the cache engine,
- lms: the Django web application used by learners,
- cms: the Django web application used by teachers,
- nginx: the front end web server configured to serve static/media files and proxy other requests to Django.
- mailcatcher the email backend
Concerning Redis, it is possible to run a single redis instance (the default choice)
or to run redis with sentinel to simulate a HA instance.
To use Redis sentinel you have to set the REDIS_SERVICE
environment variable
to redis-sentinel
:
$ export REDIS_SERVICE=redis-sentinel
To switch back to the single redis instance, unset this environment variable:
$ unset REDIS_SERVICE
Make sure you have a recent version of Docker and Docker Compose installed on your laptop:
$ docker -v
Docker version 17.12.0-ce, build c97c6d6
$ docker-compose --version
docker-compose version 1.17.1, build 6d101fb
Docker Compose
version 1.19 is not supported because of a bug (see
docker/compose#5686). Please downgrade to 1.18 or
upgrade to a higher version.
First, you need to choose a release/flavor of OpenEdx versions we support. You
can list them and get instructions about how to select/activate a target release
using the bin/activate
script. An example output follows:
$ bin/activate
Select an available release to activate:
[1] master/bare (default)
[2] hawthorn/1/bare
[3] hawthorn/1/oee
Your choice: 3
# Copy/paste hawthorn/1/oee environment:
export EDX_RELEASE="hawthorn.1"
export FLAVOR="oee"
export EDX_RELEASE_REF="open-release/hawthorn.1"
export EDX_DEMO_RELEASE_REF="open-release/hawthorn.1"
# Or run the following command:
. ${HOME}/Work/openedx-docker/releases/hawthorn/1/oee/activate
# Check your environment with:
make info
Once your environment is set, start the full project by running:
$ make bootstrap
You should now be able to view the web applications:
- LMS served by
nginx
at: http://localhost:8073 - CMS served by
nginx
at: http://localhost:8083
See other available commands by running:
$ make --help
If you intend to work on edx-platform or its configuration, you'll need to compile static files in local directories that are mounted as docker volumes in the target container:
$ make dev-assets
Now you can start services development server via:
$ make dev
You should be able to view the web applications:
- LMS served by Django's development server at: http://localhost:8072
- CMS served by Django's development server at: http://localhost:8082
To work on a particular theme, we invite you to use the paver watch_assets
command; e.g.:
$ make dev-watch
Troubleshooting: if the command above raises the following error:
OSError: inotify watch limit reached
Then you will need to increase the host's fs.inotify.max_user_watches
kernel setting (for reference, see https://unix.stackexchange.com/a/13757):
# /etc/sysctl.conf (debian based)
fs.inotify.max_user_watches=524288
The aim of this project is to prepare several flavors of images, the docker
files and settings of which are living in their own directory (see
releases/
)
Release paths on the current repository are of the form:
{release name}/{release number}/{flavor}
With:
- release name: OpenEdx release name (e.g.
hawthorn
) - release number: OpenEdx release number (e.g.
1
) - flavor: the release flavor (e.g.
bare
for standard OpenEdx release andoee
for OpenEdx Extended release).
We are pushing to DockerHub
only images that are the result of a tag
respecting the following pattern:
{release}(-{flavor})-x.y.z
The release
(e.g. hawthorn.1
) typically includes the release name
(e.g. hawthorn
) and the release number
(e.g. 1
). The flavor is
optional.
Here are some valid examples:
dogwood.3-1.0.3
hawthorn.1-oee-2.0.1
This project also provides extra, optional companion images that can be used
along with edxapp
.
The classical way to handle and serve static files in a Django application is
to collect them (using the collectstatic
management command) and post-process
them using an appropriate storage back end that uses cache-busting techniques
to avoid old versus new static files collisions (e.g.
ManifestStaticFilesStorage
).
Depending on the edx-platform
release, some files may not benefit from a
cache busting md5 hash, leading to unexpected side effects during deployment.
To prevent such behavior, for each new openedx-docker
release, we will also
release an
edxapp-nginx
image with the same Docker tag. This image is an OpenShift-ready nginx
image with embedded
edxapp
's static files. You are supposed to use this image to serve your
static files, media and reverse proxy to the version-matching edxapp
instance.
If what you're looking for is a quick 1-click installation of the complete Open edX stack, you may take a look at Régis Behmo's work here.
The code in this repository is licensed under the GNU AGPL-3.0 terms unless otherwise noted.
Please see LICENSE
for details.