Skip to content

Home

Jump to bottom Edit New page
Omar Al-Ithawi edited this page Oct 29, 2017 · 13 revisions

Introduction to Edraak Platform

This document should help you to get started with Open edX and the Edraak fork of Open edX. Mainly it focuses as a pointer to the different documents that we have at Edraak, and to guide you when you need to make an open-source contribution to Open edX.

What is Open edX

The Open edX platform is a free--and open source--course management system (CMS) that was originally developed by edX. The Open edX platform is used all over the world to host Massive Open Online Courses (MOOCs) as well as smaller classes and training modules.

Learn more at the Open edX Portal.

Open edX Releases

From now on, you'll hear a lot about edX versions. For a start you should try Ficus, or more precisely the open-release/ficus.3 version. For more info please check this page about the releases.

What is the Edraak Platform?

The Edraak platform is a fork (i.e. same code with some customization) of the Open edX platform. This document provides an overview of those features with links to the available documents, although not comprehensive.

I Want to Code!

Usually it's better to ask someone in the team to guide you through the process. However, assuming that you're alone, the Edraak Rampup Process should help you.

What to Learn?

Learning Open edX may seem like a maze, this section is dedicated to make it easier. Since there's no one linear way to learn Open edX, the subsections below tackles the problem from different aspects.

The Edraak Rampup Process

The list below is meant to help senior full-stack software engineers to know about the various technologies that are used in Open edX and Edraak. This is usually too much for someone who's just starting their career, so you should ask for guidance from other team members when you feel lost.

  • Read Chapters 1-10 of Python - From Novice to Professional
  • Read Chapters 1-7, 12, 15, 18 of Django - The Definitive Guide
  • Setup edX locally use this guide
  • Read edX architecture documentation
  • Learn what the XBlocks are and how to write one
  • Learn basic and advanced Sass.
  • Learn Bi-App-Sass for writing LTR/RTL SaSS, and explore how it's being used at Open edX (example).
  • Learn Git very well and identify development workflows:
  • Learn Ansible:
  • Get Familiar with the edx-configuration project
  • Understand the different components that make up Edraak (check the rest of this document)
  • Get a feel for the underlying fundamental data models (and database tables): users, courses etc..
  • Get Familiar with AWS and all AWS services including, EC2, RDS, Elasticache, Cloudfront etc..
  • Understand Edraak's production setup on AWS (a team member should give you a walkthrouhg)
  • Configure local machine to be able to tunnel through SSH to be able to manage servers (again, someone at Edraak should help you with this)
  • Get familiar with the different application setups on each server, including file system hierarchy, administrative scripts, logs etc..
    • Mainly learn what's inside the /edx/ directory
  • Take the NewRelic training course
  • Familiarize yourself with application/server monitoring on New Relic
  • Fix your first bug locally, and verify all is well
  • Merge change back into master
  • Get familiar with deploying to QA environment
  • Learn to deploy to production environment and all necessary steps including AWS and application tasks

Join the Community

Become an edX Contributor

So you'd like to contribute to Open edX (and you should, this is part of the job!). Be sure to checkout the links below:

We also maintain a page that tracks the pull requests that Edraak have issued to edX.

What the Jenkins?

Jenkins is an open source automation server, it's designed to help you to build, deploy and automate any project. Mainly we (and edX) use it to run the automated tests for Open edX.

You may love or hate Jenkins. Regardless, it's your best ally to catch bugs before the users do.

Here are few things that I recommend to do with Jenkins:

  • If the Jenkins build fail, it's usually your fault!
  • There are some cases where it's really not your fault, but Jenkins refuses to run a test. We skip those, but these are very rare cases that should not become a habit! Examples of skipped tests.
  • Be patient, a 45 minute build could seem like ages. However, all the 280+ Open edX contributors have handled it, I'm sure you can do the same!
  • Code quality matters, every bit of it! Otherwise you'll end up with a code that neither you can understand.
  • Create tests when developing at Edraak, just like you would do at when contributing to edX. It's painful at first, but it gets easier with practice.

Generally you'll have the Jenkins running on https://build.edraak.org/, but you can build your own build your own with this Jenkins Guide.

It is also important to know the secret sauce behind Jenkins, it's the Jenkinsfile.

This file is written (and to be updated each release) based on generic-ci-tests.sh. Pay attention to the shard numbers, test suites and test commands.

The Edraak Platform Components

Although all the Edraak changes are documented with pull requests, and most of those PRs have their tasks. This page provides an overview of the most notable code changes that Edraak (ficus) has over edX (ficus).

The current https://www.edraak.org consists of multiple components, the most notable ones are listed below:

Sooo, Why Do We Have a Fork? Can't We Use edX's Version?

This is a valid question. Mostly it is because edX doesn't support modular plugins that much, and integration tests for those modules are tricky.

The list below answers the question by highlighting the most important of the changes that has been done at Edraak. It is a cleaned diff with ficus.master(1). The comments before each line (or group of lines) provides and overview of the changes.

# Makes Honor the default enrollment mode
common/djangoapps/course_modes/tests

# This app provides i18n customizations to Edraak. Mainly make the Arabic
# the default language and
common/djangoapps/edraak_i18n

# More permissive rate limit and show the limits in the Admin
common/djangoapps/edraak_ratelimit

# General tests for miselenous Edraak changes that doesn't fall into a specific application.
common/djangoapps/edraak_tests

# Enable the Arabic MathJax
common/static/common/js/discussion/mathjax_include.js
common/static/sass/edraak/_arabic-mathjax.scss
common/templates/mathjax_arabic_config.html
common/templates/mathjax_include.html

# Here's where the Edraak translation lives, after being pulled from Transifex
conf/locale/ar/LC_MESSAGES/

# Pull course details from the marketings site
lms/djangoapps/course_api/tests/test_edraak_customizations.py

# The infamous Edraak PDF certificates
lms/djangoapps/edraak_certificates

# The Edraak Single-Sign-On integration with http://forus.jo
lms/djangoapps/edraak_forus

# Used to have some tests, but now it should be removed!
lms/djangoapps/edraak_lms_tests

# The amazing 2 weeks university integration project that made everyone happy!
lms/djangoapps/edraak_university

Edraak University App

This probably the most well documented app at Edraak. Here's the specs document.

The Arabic MathJax

Although it has its own repo https://github.com/Edraak/arabic-mathjax, but its only being used inside the edX Platform. Here's a presentation on what does it do. A video is also available, a very quick one however!

Edraak ForUs App (for KAFD.jo)

Despite the cumbersome, this is a very well documented project.

Other Edraak Apps

The rate limits and the i18n customization are notable example.

Edraak PDF Certificates App

Historically this was done quickly to fix a terrible in-browser HTML-to-PNG engine, but for some reasons it continued to be used till now!

edX Platform supports multiple types of certificates. However, for historical reasons and the lack of Arabic support, Edraak have developed it's own PDF certificate engine. This engine mainly provides an easy way for course authors to have an Edraak branded certificate with minimum effort. It also allows students to issue certificates on-demand without having to wait for the long queue for certificates generation.

Unfortunately, the Edraak PDF certificates have not had any form of verification. Although verification is something that can be done, it wasn't.

This is probably the most well known feature at Edraak, so no further documentation will be done.

The Transifex Repoistory

Although this is not strictly a software engineering thing, but we do maintain our transifex repoistory.

The steps to update the translations are:

  1. Send the latest translations to Transifex
$ git checkout master
$ git pull  # Update your code
$ paver i18n_robot_push  # Send the latest translations to Transifex

  1. Go to Transifex and make sure all the strings are translated and reviewed.

  2. Update the code with the latest translations from Transifex:

$ git checkout master
$ git pull
$ paver i18n_robot_push
$ git push

Other Documents

  1. The actual command $ git diff --name-only 35389f open-release/ficus.master where was on master September 13th, 2017.
Add a custom footer
Add a custom sidebar
Clone this wiki locally