diff --git a/source/community/release_notes/dogwood.rst b/source/community/release_notes/dogwood.rst index f23b68ba4..7742ee562 100644 --- a/source/community/release_notes/dogwood.rst +++ b/source/community/release_notes/dogwood.rst @@ -117,7 +117,7 @@ enhancement also gives system administrators the ability to configure a list of file types that learners cannot upload. For more information, see -Configuring ORA2 to Prohibit Submission of File Types. +:ref:`Configuring ORA2 to Prohibit Submission of File Types`. Certificates ============ diff --git a/source/developers/references/developer_guide/links.rst b/source/developers/references/developer_guide/links.rst deleted file mode 100644 index e69de29bb..000000000 diff --git a/source/developers/references/developer_guide/process/code-considerations.rst b/source/developers/references/developer_guide/process/code-considerations.rst index 01a2baa1f..51dd0b695 100644 --- a/source/developers/references/developer_guide/process/code-considerations.rst +++ b/source/developers/references/developer_guide/process/code-considerations.rst @@ -101,4 +101,4 @@ back to you with questions. .. _Open edX Release Planning: https://openedx.atlassian.net/wiki/spaces/COMM/pages/13205845/Open+edX+Release+Planning -.. include:: ../links.rst +.. include:: /links.txt diff --git a/source/developers/references/developer_guide/process/contributor.rst b/source/developers/references/developer_guide/process/contributor.rst index 4543cf0b3..3245d3a61 100644 --- a/source/developers/references/developer_guide/process/contributor.rst +++ b/source/developers/references/developer_guide/process/contributor.rst @@ -62,4 +62,4 @@ link to a WIP pull request in any discussion threads you start. .. _Open edX Product Working Group: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3449028609/Product+Working+Group .. _Product Roadmap: https://github.com/orgs/openedx/projects/4 -.. include:: ../links.rst \ No newline at end of file +.. include:: /links.txt \ No newline at end of file diff --git a/source/developers/references/developer_guide/process/overview.rst b/source/developers/references/developer_guide/process/overview.rst index 401d089fa..1ae8256e1 100644 --- a/source/developers/references/developer_guide/process/overview.rst +++ b/source/developers/references/developer_guide/process/overview.rst @@ -35,4 +35,4 @@ questions or concerns. * :ref:`Accessibility Guidelines` * :ref:`analytics` -.. include:: ../links.rst +.. include:: /links.txt diff --git a/source/developers/references/developer_guide/testing/github-actions.rst b/source/developers/references/developer_guide/testing/github-actions.rst index f711a6c2d..9bf6f3b1e 100644 --- a/source/developers/references/developer_guide/testing/github-actions.rst +++ b/source/developers/references/developer_guide/testing/github-actions.rst @@ -98,4 +98,4 @@ changes. .. _.github repo: https://github.com/openedx/.github/tree/master/.github/workflows .. _fix Transifex resource names: https://github.com/openedx/openedx-translations/blob/main/.github/workflows/fix-transifex-resource-names.yml .. _workflow dispatch: https://github.com/openedx/openedx-translations/blob/cf313a06ebf8c3a792e67174dfcba7607da2d61f/.github/workflows/fix-transifex-resource-names.yml#L5-L13 -.. include:: ../links.rst \ No newline at end of file +.. include:: /links.txt \ No newline at end of file diff --git a/source/developers/references/running_pr_tests.rst b/source/developers/references/running_pr_tests.rst index b58061669..4aedbc2d2 100644 --- a/source/developers/references/running_pr_tests.rst +++ b/source/developers/references/running_pr_tests.rst @@ -97,5 +97,6 @@ PRs, and follow them to be notified of when the fix has been applied (and then do the rebase). You could even try submitting a PR yourself to fix the failing tests! -.. _Open edX Forums: https://discuss.openedx.org/ .. _openedx.org/cla: http://openedx.org/cla + +.. include:: /links.txt \ No newline at end of file diff --git a/source/documentors/index.rst b/source/documentors/index.rst index 082072499..b57a39464 100644 --- a/source/documentors/index.rst +++ b/source/documentors/index.rst @@ -1,3 +1,5 @@ +.. _Documentor's Home: + Open edX Documentors #################### diff --git a/source/educators/concepts/exercise_tools/about_OpenResponseAssessments.rst b/source/educators/concepts/exercise_tools/about_OpenResponseAssessments.rst index 1bc13fbbc..cb56b67be 100644 --- a/source/educators/concepts/exercise_tools/about_OpenResponseAssessments.rst +++ b/source/educators/concepts/exercise_tools/about_OpenResponseAssessments.rst @@ -693,7 +693,7 @@ you cannot specify these file types. This set of file name extensions is provided as the default for Open edX installations. Open edX system administrators can update this list. For more -information, see `Configuring ora2 to prohibit submission of file types`_. +information, see :ref:`Configuring ora2 to prohibit submission of file types`. .. list-table:: :widths: 15 75 diff --git a/source/educators/how-tos/configure_certificate_timing.rst b/source/educators/how-tos/configure_certificate_timing.rst index 8a80137b6..328469037 100644 --- a/source/educators/how-tos/configure_certificate_timing.rst +++ b/source/educators/how-tos/configure_certificate_timing.rst @@ -10,8 +10,8 @@ Configure Certificate Availability and Timing Before you can issue certificates, the administrator for your instance of Open edX must configure the platform to allow course teams to generate and issue certificates. For more information, see - `Enable Automatic Certificate Generation`_ and - `Enable Certificates`_ in *Installing, Configuring, and + :ref:`Enable Automatic Certificate Generation` and + :ref:`Enable Certificates` in *Installing, Configuring, and Running the Open edX Platform*. The platform can automatically generate certificates for both self-paced courses and @@ -64,7 +64,7 @@ Allow Learners to Receive Early Certificates ******************************************** If the administrator has configured the site correctly (see -`Enable Automatic Certificate Generation`_ in +:ref:`Enable Automatic Certificate Generation` in *Installing, Configuring, and Running the Open edX Platform*), self-paced courses issue certificates to learners as soon as learners have completed enough of the course, with a high enough grade, to earn diff --git a/source/educators/navigation/learner_engagement_communication.rst b/source/educators/navigation/learner_engagement_communication.rst index 4fba23702..a15a2de8d 100644 --- a/source/educators/navigation/learner_engagement_communication.rst +++ b/source/educators/navigation/learner_engagement_communication.rst @@ -44,6 +44,8 @@ Bulk Emails ../references/communication/compose_email_message.rst ../how-tos/communication/email_task_history_report.rst +.. _Automatic Emails: + Automatic Emails ******************************************************* diff --git a/source/links.txt b/source/links.txt index 97db0c27a..d9bf7a4ef 100644 --- a/source/links.txt +++ b/source/links.txt @@ -6,8 +6,6 @@ .. _VirtualEnvWrapper: http://virtualenvwrapper.readthedocs.io/en/latest -.. _Configuring ORA2 to Prohibit Submission of File Types: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/ora2/ora2_blacklist.html - .. _edx-platform: https://github.com/openedx/edx-platform .. _init file: https://github.com/openedx/edx-ora2/blob/a4ce7bb00190d7baff60fc90fb613229565ca7ef/openassessment/fileupload/backends/__init__.py @@ -174,10 +172,6 @@ .. _app_label: https://docs.djangoproject.com/en/1.8/ref/models/options/#app-label -.. _Enable Certificates: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/enable_certificates.html - -.. _Enable Automatic Certificate Generation: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/enable_certificates.html#enable-automatic-certificate-generation - .. _Media formats supported by the HTML audio and video elements: https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#MP4_H.264_(AAC_or_MP3) .. _editing object metadata: http://docs.aws.amazon.com/AmazonS3/latest/UG/EditingtheMetadataofanObject.html @@ -212,10 +206,134 @@ .. _Time and Date Time Zone Converter: http://www.timeanddate.com/worldclock/converter.html -.. _Installing, Configuring, and Running the Open edX Platform: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/index.html - .. _Tree of Math: http://www.onemathematicalcat.org/MathJaxDocumentation/TeXSyntax.htm .. _MathJax Documentation: http://docs.mathjax.org/en/latest/index.html .. _Mathematics meta: http://meta.math.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference + +.. _Open edX Release Schedule: https://openedx.atlassian.net/wiki/spaces/COMM/pages/3613392957/Open+edX+Release+Schedule + +.. _Open edX Releases Wiki page: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/4191191044/Open+edX+Releases+Homepage + +.. _The migrate.sh script: https://github.com/openedx/configuration/blob/named-release/dogwood.rc/util/vagrant/migrate.sh + +.. _The upgrade.sh script: https://github.com/openedx/configuration/blob/master/util/vagrant/upgrade.sh + +.. _forum migration described on the Open edX wiki: https://openedx.atlassian.net/wiki/display/TNL/Migrating+the+Discussion+Forums+to+Support+Teams+Discussion+Filtering + +.. _Native Installation to Tutor forum post: https://discuss.openedx.org/t/upgrade-from-native-to-tutor/9252 + +.. _this second Native to Tutor post: https://discuss.overhang.io/t/migrating-from-native-install-to-tutor-juniper-tutor-10-x/1533 + +.. _Open edX Installation options: https://openedx.atlassian.net/wiki/x/wwCXAw + +.. _Open edX Native 12.04 Installation: https://openedx.atlassian.net/wiki/x/bgCXAw + +.. _Legacy Open edX Native Installation: https://openedx.atlassian.net/wiki/x/g4G6C + +.. _Koa Open edX Native Installation: https://openedx.atlassian.net/wiki/x/lIJjdQ + +.. _Django Forms: https://docs.djangoproject.com/en/1.8/ref/forms/ + +.. _example CSS file for drag and drop problems: https://github.com/openedx/xblock-drag-and-drop-v2/blob/master/drag_and_drop_v2/public/themes/apros.css + +.. _custom_form_app: https://github.com/open-craft/custom-form-app + +.. _GitHub: http://github.com + +.. _EdX Search: https://github.com/openedx/edx-search/ + +.. _edX Automated Communication Engine: http://edx-ace.readthedocs.io/en/latest + +.. _IMS LTI 1.1 Consumer Launch: http://www.imsglobal.org/developers/LTI/test/v1p1/lms.php + +.. _password_policy_validators: https://github.com/openedx/edx-platform/blob/master/common/djangoapps/util/password_policy_validators.py + +.. _Python SAML Toolkit: https://github.com/onelogin/python-saml + +.. _random and highly secure password: https://github.com/openedx/edx-platform/blob/46d69eba/common/djangoapps/third_party_auth/pipeline.py#L392-L410 + +.. _OID: https://en.wikipedia.org/wiki/Object_identifier + +.. _URN: https://en.wikipedia.org/wiki/Uniform_Resource_Name + +.. _eduPersonPrincipalName: https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html#eduPersonPrincipalName + +.. _eduPersonEntitlement: https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html#eduPersonEntitlement + +.. _eduPerson Object Class Specification: https://www.internet2.edu/media/medialibrary/2013/09/04/internet2-mace-dir-eduperson-201203.html + +.. _Google Developers Console: https://console.developers.google.com/project/_/apiui/apis/library + +.. _Facebook for Developers: https://developers.facebook.com/apps/?action=create + +.. _LinkedIn Developers: https://www.linkedin.com/secure/developer + +.. _Microsoft Sign In: https://account.live.com + +.. _Azure account creation: https://azure.microsoft.com/en-us/pricing/free-trial + +.. _Azure sign in: https://portal.azure.com + +.. _AWS template file: https://github.com/openedx/edx-platform/blob/b3462e5b1c3cc45ad8673f3f12e84fa17ffa6b64/lms/envs/aws.py#L586-L596 + +.. _Font Awesome: http://fortawesome.github.io/Font-Awesome/icons/ + +.. _Elastic MapReduce: http://aws.amazon.com/elasticmapreduce/ + +.. _default EC2 role for Amazon EMR: http://docs.aws.amazon.com/ElasticMapReduce/latest/DeveloperGuide/emr-iam-roles-defaultroles.html#emr-iam-roles-defaultec2 + +.. _Default IAM Roles for Amazon EMR: https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-iam-role-for-ec2.html + +.. _a single public subnet: http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Scenario1.html + +.. _example configuration scenario: http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Scenario2.html + +.. _Open edX Forums: https://discuss.openedx.org/ + +.. _submission_mixin.py: https://github.com/openedx/edx-ora2/blob/a4ce7bb00190d7baff60fc90fb613229565ca7ef/openassessment/xblock/submission_mixin.py + +.. _official Google instructions: https://developers.google.com/identity/protocols/oauth2 + +.. _python-social-auth supported backend: http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends + +.. _list of python-social-auth backends: https://github.com/omab/python-social-auth/tree/master/social/backends + +.. _python-social-auth documentation: http://python-social-auth.readthedocs.io/en/latest/index.html + +.. _OAuth backends supported by python-social-auth v0.2.12: http://python-social-auth.readthedocs.io/en/latest/backends/index.html#social-backends + +.. _the default value in the aws.py file: https://github.com/openedx/edx-platform/blob/b3462e5b1c3cc45ad8673f3f12e84fa17ffa6b64/lms/envs/aws.py#L586-L596 + +.. _YouTube Data API v3: https://developers.google.com/youtube/v3/ + +.. _instructions for obtaining authorization credentials: https://developers.google.com/youtube/registering_an_application + +.. _Query string syntax: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax + +.. _Ansible: https://docs.ansible.com/ + +.. _configuration: https://github.com/openedx/configuration + +.. _Virtual Environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/ + +.. _VirtualEnv Installation: https://virtualenv.pypa.io/en/latest/installation.html + +.. _VirtualEnvWrapper: http://virtualenvwrapper.readthedocs.io/en/latest + +.. _spot pricing market: http://aws.amazon.com/ec2/purchasing-options/spot-instances/ + +.. _edX Managing the Full Stack: https://github.com/openedx/configuration/wiki/edX-Managing-the-Full-Stack + +.. _edX Enrollment API: https://docs.openedx.org/projects/edx-platform/en/latest/references/lms_apis.html#get--enrollment-v1-course-course_id + +.. _edx-analytics-configuration: https://github.com/openedx/edx-analytics-configuration + +.. _AWS Command Line Interface: http://aws.amazon.com/cli/ + +.. _edX Analytics Installation: https://openedx.atlassian.net/wiki/display/OpenOPS/edX+Analytics+Installation + +.. _retirement: https://user-retirement-guide.readthedocs.io/en/latest/index.html + +.. _AWS Documentation: http://aws.amazon.com/documentation/ \ No newline at end of file diff --git a/source/other/getting_help.rst b/source/other/getting_help.rst index 941981078..dfe8d68c1 100644 --- a/source/other/getting_help.rst +++ b/source/other/getting_help.rst @@ -6,8 +6,7 @@ Getting Help If you are unable to find what you need here or need more help than the documentation provides, we'd love to hear about it via the :doc:`feedback`. -To get more help we recommend checking out the `Open edX Forums -`_. Make sure to search the forums before posting a +To get more help we recommend checking out the `Open edX Forums`_. Make sure to search the forums before posting a new question in case others have had the same question as you. The community also has a `slack workspace @@ -20,3 +19,5 @@ responses. The Open edX community has agreed upon a shared `code of conduct `_, please be sure to review it. + +.. include:: /links.txt \ No newline at end of file diff --git a/source/site_ops/index.rst b/source/site_ops/index.rst index 27c5477d2..51ac879e9 100644 --- a/source/site_ops/index.rst +++ b/source/site_ops/index.rst @@ -3,8 +3,7 @@ Open edX Site Operators .. note:: - This area is still under active development. You can find the old - documentation here: `Installing, Configuring, and Running the Open edX Platform`_ + This area is still under active development. For information about the latest release of the Open edX Platform, you can check out the :doc:`/community/release_notes/index` @@ -12,6 +11,7 @@ Open edX Site Operators .. toctree:: :glob: + install_configure_run_guide/index quickstarts/index how-tos/index concepts/index diff --git a/source/site_ops/install_configure_run_guide/Images/Analytics_AWS_Deployment.png b/source/site_ops/install_configure_run_guide/Images/Analytics_AWS_Deployment.png new file mode 100644 index 000000000..50bae2509 Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/Analytics_AWS_Deployment.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/Analytics_Pipeline.png b/source/site_ops/install_configure_run_guide/Images/Analytics_Pipeline.png new file mode 100644 index 000000000..436310f7f Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/Analytics_Pipeline.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/add_office365_provider_config.png b/source/site_ops/install_configure_run_guide/Images/add_office365_provider_config.png new file mode 100755 index 000000000..2d8922dcc Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/add_office365_provider_config.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/course_enable_anonymous_courseware_access.png b/source/site_ops/install_configure_run_guide/Images/course_enable_anonymous_courseware_access.png new file mode 100644 index 000000000..051b087af Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/course_enable_anonymous_courseware_access.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/course_reviews.png b/source/site_ops/install_configure_run_guide/Images/course_reviews.png new file mode 100644 index 000000000..37b528f04 Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/course_reviews.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/enable_anonymous_courseware_access.png b/source/site_ops/install_configure_run_guide/Images/enable_anonymous_courseware_access.png new file mode 100644 index 000000000..95d633b5a Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/enable_anonymous_courseware_access.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/lti_test_auth.png b/source/site_ops/install_configure_run_guide/Images/lti_test_auth.png new file mode 100644 index 000000000..87f5020ae Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/lti_test_auth.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/tpa-idp-create-non-personal-account.png b/source/site_ops/install_configure_run_guide/Images/tpa-idp-create-non-personal-account.png new file mode 100644 index 000000000..5a58d99de Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/tpa-idp-create-non-personal-account.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/tpa-idp-create-non-personal-account.svg b/source/site_ops/install_configure_run_guide/Images/tpa-idp-create-non-personal-account.svg new file mode 100644 index 000000000..7e9355e98 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/Images/tpa-idp-create-non-personal-account.svg @@ -0,0 +1,460 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + Learners can enter non-identifying information in their edX profiles, after the IdP directs them to the edX site. The opaque identifier sent by the IdP remains associated with the edX learner profile. + + + + + + Non-personal identifieruri://1234@some.edu + + No personally identifying information transmitted to edX site + + username: MyEdxAliasEmail: myedxalias@othermail.comuri://1234@some.edu + + EdX site + + + EdX site third-party authentication service + + Learner Institution + + + Identity Provider (IdP) service + + + + Personally identifying information held by institution only + + Name: Jean SmithEmail: jsmith@institution.eduIdentifier: 5391395224 + + + + + + diff --git a/source/site_ops/install_configure_run_guide/Images/tpa-institution-associate-edx-id-with-personal-id.png b/source/site_ops/install_configure_run_guide/Images/tpa-institution-associate-edx-id-with-personal-id.png new file mode 100644 index 000000000..91f296f73 Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/tpa-institution-associate-edx-id-with-personal-id.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/tpa-institution-associate-edx-id-with-personal-id.svg b/source/site_ops/install_configure_run_guide/Images/tpa-institution-associate-edx-id-with-personal-id.svg new file mode 100644 index 000000000..5dce8a156 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/Images/tpa-institution-associate-edx-id-with-personal-id.svg @@ -0,0 +1,725 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + EdX site Learner Institution + + + + + + + + + GET edX username:MyEdxAlias + + + + Return non-personal identifieruri://1234@some.edu + + + + + REST API client + + + Third-party authentication ID mapping REST API + + + + Course score foredX username:MyEdxAlias + + + + + Course grade report + The third-party authentication ID mapping API returns the opaque, non-personal identifier that matches an edX username. Edx usernames are not known by the institution that maintains personal learner data, such as university grades. + + Match the edX username to a non-personal identifier, then use the IdP service to match the non-personal identifier to institution records for a learner. + + + IdP service + + Name: Jean SmithNon-personal identifier:uri://1234@some.eduIdentifier: 5391395224 + + + + Institution grade records + + Name: Jean Smithjsmith@institution.eduIdentifier: 5391395224 + + + + diff --git a/source/site_ops/install_configure_run_guide/Images/tpa_inst_list.png b/source/site_ops/install_configure_run_guide/Images/tpa_inst_list.png new file mode 100644 index 000000000..a4411aae9 Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/tpa_inst_list.png differ diff --git a/source/site_ops/install_configure_run_guide/Images/tpa_signin.png b/source/site_ops/install_configure_run_guide/Images/tpa_signin.png new file mode 100644 index 000000000..0cf0a9bce Binary files /dev/null and b/source/site_ops/install_configure_run_guide/Images/tpa_signin.png differ diff --git a/source/site_ops/install_configure_run_guide/analytics/index.rst b/source/site_ops/install_configure_run_guide/analytics/index.rst new file mode 100644 index 000000000..aa47183fa --- /dev/null +++ b/source/site_ops/install_configure_run_guide/analytics/index.rst @@ -0,0 +1,39 @@ +.. _Open edX Analytics Options: + +Open edX Analytics Options +########################## + +As of the Sumac release, the Open edX community supports the +following Analytics solutions: + +Aspects +******* + +`Open edX Aspects `_ +is an optional implementation of analytics for the Open edX LMS. It is the combined solution +of Cairn by Overhang.io and the OARS project developed by Axim Collaborative with a huge amount +of help from the Open edX community. Primarily it is intended to be a "batteries included" set +of configurations and plugins to combine 3rd party tools into a powerful and flexible system for +learner analytics. + +Cairn +***** + +`Cairn `_ is a Tutor plugin that you install on top of an +Open edX instance and that gives you access to a powerful, full-blown analytics stack. + +Unsupported Analytics solutions +******************************* + +edX Insights +============ + +Insights is `deprecated `_ and no +longer supported by the Open edX community. The last supported release was Quince (2023). + +Figures +======= + +`Figures `_ is no longer under active development and +is not recommended for use. + diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/drag_and_drop_problem_styling.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/drag_and_drop_problem_styling.rst new file mode 100644 index 000000000..b592f4aec --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/drag_and_drop_problem_styling.rst @@ -0,0 +1,85 @@ +.. _styling_drag_and_drop_problems: + +############################################ +Styling Drag and Drop Problems (deprecated) +############################################ + +You can customize the appearance of drag and drop problems in your Open edX +site using custom Cascading Style Sheet (CSS) files. The style that you +configure applies to all drag and drop problems in all courses. + +The following two methods apply CSS styling to drag and drop problems. + +* You can apply CSS styles to drag and drop problems by creating a theme for + your site and updating the Syntactically Awesome Style Sheet (Sass) files + that produce the CSS files. For more information, see :ref:`Creating a + Theme`. + +* You can apply CSS styles to drag and drop problems by adding a Python + programming language module that includes a CSS file to your Open edX site. + For more information, see the instructions in this section. + +.. note:: This section provides information about styling the drag and drop + problem type that was added to the edX platform in 2016. This drag and drop + problem type replaced an earlier drag and drop problem type. You should use + the latest drag and drop problem type for all new course problems. + +.. note:: + Course teams can also style the background and text colors of the draggable + items in an individual drag and drop problem, without adding CSS files or + configuring a Python module. + +To customize the style of drag and drop problems by adding a CSS file in a +Python module, follow these steps. + +#. Create a custom CSS style sheet that applies styles to the drag and drop + problem user interface. You can base your style sheet on the `example CSS + file for drag and drop problems`_ that is included in the drag and drop + problem module. + +#. Create a Python module that includes your custom CSS style sheet. For + example, the following Python module files include a CSS style sheet. + + .. code-block:: shell + + ./my_drag_and_drop_style + ./my_drag_and_drop_style/css + ./my_drag_and_drop_style/css/my_drag_and_drop_style.css + ./my_drag_and_drop_style/__init__.py + ./setup.py + + For more information about creating and installing Python modules, see the + documentation for the Python programming language. + +#. Install your Python module on the LMS server as the ``edxapp`` user. + + .. code-block:: shell + + pip install /path/to/my/module + + +#. Edit the ``lms.yml`` file for your LMS server. Add the ``drag-and- + drop-v2`` object to the ``XBLOCK_SETTINGS`` object. Include the content + shown in the following example. + + .. code-block:: none + + "XBLOCK_SETTINGS":{ + "drag-and-drop-v2": { + "theme": { + "package": "my_drag_and_drop_style", + "locations": ["css/my_drag_and_drop_style.css"] + } + } + + Enter the name of your Python module in the value of the ``package`` object. The value in the example above is ``my_drag_and_drop_style``. + + Enter the path to your CSS style sheet file in the value of the + ``locations`` object. The value in the example above is + ``css/my_drag_and_drop_style.css``. The path must be relative to your Python + module installation directory. You can include more than one path in the + ``locations`` array, separated by commas. + +#. Restart the LMS. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/index.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/index.rst new file mode 100644 index 000000000..51a2c4f28 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/index.rst @@ -0,0 +1,16 @@ +.. _Changing the Way Open edX Looks: + +###################################################### +Changing the Appearance of Open edX Sites +###################################################### + +This section describes how you can customize your Open edX sites to change the +way they look. + +.. toctree:: + :maxdepth: 1 + + theming/index + drag_and_drop_problem_styling + +.. For more information about how you set up sites, see :ref:`Configuring Open edX Sites`. diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/compiling_theme.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/compiling_theme.rst new file mode 100644 index 000000000..511102f0f --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/compiling_theme.rst @@ -0,0 +1,93 @@ +.. _Compiling a Theme: + +####################### +Compiling a Theme +####################### + +To update a theme, you compile the Sass files to create the CSS files that +style your UI when you apply the theme. + +.. contents:: + :local: + :depth: 1 + +************************************* +Update a Theme for the LMS or Studio +************************************* + +To update a theme for Studio or the LMS, follow these steps. + +#. Log in to the Open edX machine as the ``edxapp`` user. + +#. Change to the ``/edx/app/edxapp/edx-platform`` directory. + +#. Execute the ``npm run compile-sass`` command to update all themes. + + If you want to update specific themes, use the arguments described in the + following table. + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Argument + - Description + * - ``--theme-dirs`` + - Provide a space-separated list of the theme directories that you want + to update. Only files in the theme directories that you include + are updated. + * - ``--themes`` + - Provide a space-separated list of the themes that you want to update. + Only the themes that you include are updated. + +****************************************** +Update a Theme for the E-commerce Service +****************************************** + +For the E-commerce service, commands are available for you to update +all themes at once, or to update only the themes you specify. + +To update a theme for the E-commerce service, follow these steps. + +#. Log in to the server for the E-commerce service as the ``ecommerce`` user. + +#. Change to the ``/edx/app/ecommerce/ecommerce`` directory. + +#. To update all themes, execute one of these commands. + + * ``make migrate`` + + * ``python manage.py update_assets`` + +#. To specify a theme or set of themes to update, or to include optional + arguments, execute ``python manage.py update_assets`` with the options + described in the following table. + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Argument + - Description + * - ``--settings`` + - Provide the name of a Django `settings module `_ + in Python package syntax. For example, + ``--settings=ecommerce.settings.production``. + * - ``--themes`` + - Provide a space-separated list of the themes that you want to update. + Only the themes that you include are updated. + * - ``--output-style`` + - Defines the coding style for the compiled CSS files. Possible values + are ``nested``, ``expanded``, ``compact``, and ``compressed``. The + default value is ``nested``. + * - ``--skip-system`` + - Disables Sass file compilation for the default Sass files provided in + the Open edX software. Use this option if you have only updated the + Sass files in your theme. + * - ``--skip-collect`` + - Only compile the Sass files and do not deploy the resulting CSS files. + * - ``--enable-source-comments`` + - Include the location of the source file as comments in the resulting + CSS files. Enabling this argument can be useful when you are testing a + theme. + diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/create_theme.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/create_theme.rst new file mode 100644 index 000000000..10529233c --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/create_theme.rst @@ -0,0 +1,113 @@ +.. _Creating a Theme: + +################ +Creating a Theme +################ + +To create a theme, you add a theme directory to the installation-wide themes +directory that you added when you enabled theming for your Open edX +installation. Then, you copy default UI files into your theme directory and +update them to change the appearance of the Open edX site or sites that will +use that theme. + +.. contents:: + :local: + :depth: 1 + +For more information about the themes directory, see +:ref:`enable_theming`. + +.. _understanding_themeable_ui_files: + +****************************************** +Understanding Which UI Files to Customize +****************************************** + +You can customize the default images, Sass files, and web application template +files for the Open edX components in your installation. + +* To replace an image, you can override any of the images in the + ``static/images`` directories for the components you are theming. + +* For the LMS and Studio, you can customize any of the Sass files in the + ``static/sass`` directories. + +* For the E-commerce service, you can customize any of the Sass files in the + ``static/sass/partials`` directory. + + .. note:: Do not customize Sass files in the ``static/sass/base`` directory. + +* You can override any of the HTML templates in the ``lms/templates`` or + ``cms/templates`` directories for the components that you want to apply a + theme to. + +UI files for the LMS are stored in the directories shown in the following +example theme directory. You can examine the default UI files in the source +repository of the component that you want to apply the theme to. + +.. code-block:: none + + /my-open-edx-themes/edx-platform/my-theme/lms/static/images + /my-open-edx-themes/edx-platform/my-theme/lms/static/sass + /my-open-edx-themes/edx-platform/my-theme/lms/templates + +*********************************** +Example File Path for a Theme File +*********************************** + +The default Open edX theme includes an image file named ``logo.png`` that +appears in the header of most LMS pages. The file path of that image in the +``edx-platform`` repository is ``lms/static/images/logo.png``. + +The following example shows an absolute file path of the LMS logo image in a +theme directory. The file path after +``/my-open-edx-themes/edx-platform/my-theme/`` matches +the relative file path of that image in the default directory for the LMS UI. + +.. code-block:: none + + /my-open-edx-themes/edx-platform/my-theme/lms/static/images/logo.png + +*************************** +Naming a Theme Directory +*************************** + +The name of the directory that you create to hold your versions of the image, +theme, and Sass styling files identifies the theme. As a result, if you want to +create a theme named ``my-theme``, the name of the directory within your +installation-wide themes directory must be ``my-theme``. + +.. note:: + + If you add more than one site-specific theme directory, make sure that each + of the directory names is unique. The Open edX installation looks for a + theme with a certain name, and selects the first one that matches. + +Because the UI files for the LMS and Studio are located together in the +edx-platform repository, you can create one theme that applies to both the LMS +and Studio. If you want to create a theme for the E-commerce service, you must +add a separate theme directory for its files. + +The theme directory holds the UI files that override the corresponding +default files. + +For example, if the themes directory for your site is ``/my-open-edx-themes``, +the files in the following example create a theme named ``my-theme``. + +.. code-block:: none + + /my-open-edx-themes/edx-platform/my-theme/lms/static/images/logo.png + /my-open-edx-themes/edx-platform/my-theme/lms/static/sass/partials/base/_variables.scss + /my-open-edx-themes/edx-platform/my-theme/lms/templates/navigation.html + /my-open-edx-themes/edx-platform/my-theme/cms/static/images/studio-logo.png + /my-open-edx-themes/edx-platform/my-theme/cms/static/images/logo.png + /my-open-edx-themes/edx-platform/my-theme/cms/templates/login.html + +Because the theme directory includes UI files in both the ``lms`` and ``cms`` +subdirectories, you can apply the theme to both the LMS and Studio. + +.. note:: + + After you create or make changes to a theme, you must update the theme. + Updating a theme compiles Sass files to create the CSS files that style + your UI. For more information, see :ref:`Compiling a Theme`. diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/enable_themes.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/enable_themes.rst new file mode 100644 index 000000000..14c9fe384 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/enable_themes.rst @@ -0,0 +1,169 @@ +.. _enable_theming: + +############################## +Enabling and Applying Themes +############################## + +You must enable the use of themes for your Open edX installation before you can +apply themes to your Open edX sites. If your installation has only one site, +you apply a theme to that default site. + +For more information about Open edX sites, see :ref:`Configuring Open edX +Sites`. + +.. contents:: + :local: + :depth: 1 + +*************** +Enable Themes +*************** + +To enable the use of themes for your Open edX installation, follow these steps. + +#. Create an installation-wide themes directory to hold the customized UI files + for all of the themes that you create. This directory will hold + subdirectories for each theme. Your Open edX installation will look in the + directory to find the themes you apply to sites. + + You can create this directory at any location on a file system that is + accessible to your Open edX installation. For example, you might place it at + the root of the file system in a directory named ``/my-open-edx-themes``. + +#. Set the file permissions on the themes directory, and all of its + subdirectories, to enable read+write permissions for the Ubuntu user. + + For example, to allow the devstack ``edxapp`` user for the LMS and Studio to + read and write files in the themes directory, you might use the following + commands. + + .. code-block:: bash + + sudo chown -R edxapp:edxapp /my-open-edx-themes + sudo chmod -R u+rw /my-open-edx-themes + + On fullstack and native installations the Ubuntu user is ``www-data``. + +#. For each Open edX component that you want to theme, set the + ``ENABLE_COMPREHENSIVE_THEMING`` configuration property to ``true``. + + The specific method that you use to configure Open edX components depends on + the type of environment you are using. For example, you can set the + configuration property in the following files. + + * For the LMS, you edit ``/edx/app/edxapp/lms.yml`` to set + ``"ENABLE_COMPREHENSIVE_THEMING": true``. + + * For Studio, you edit ``/edx/app/edxapp/studio.yml`` to set + ``"ENABLE_COMPREHENSIVE_THEMING": true``. + + * For the E-commerce service, you edit ``/edx/etc/ecommerce.yml`` to set + ``ENABLE_COMPREHENSIVE_THEMING: true``. + + If any of these files do not exist, you can add them to define this + configuration setting. + +#. For each Open edX component that you want to apply a theme to, add the + absolute path of the themes directory to the ``COMPREHENSIVE_THEME_DIRS`` + configuration property. + + The specific method that you use to configure Open edX components depends on + the type of environment you are using. For example, you can set the + configuration property in the following files. + + * For Studio, add the path to ``COMPREHENSIVE_THEME_DIRS`` in + ``/edx/app/edxapp/studio.yml``. + + .. code-block:: none + + "COMPREHENSIVE_THEME_DIRS": [ + "/my-open-edx-themes/edx-platform" + + ], + + * For the LMS, add the path to ``COMPREHENSIVE_THEME_DIRS`` in + ``/edx/app/edxapp/lms.yml``. + + .. code-block:: none + + "COMPREHENSIVE_THEME_DIRS": [ + "/my-open-edx-themes/edx-platform" + ], + + * For the E-commerce service, add the path to ``COMPREHENSIVE_THEME_DIRS`` + in ``/edx/etc/ecommerce.yml``. + + .. code-block:: none + + COMPREHENSIVE_THEME_DIRS: ["/my-open-edx-themes/ecommerce"] + +#. Restart all servers. + +.. note:: + + You can create more than one themes directory for your Open edX + installation. To use multiple themes directories, include the path to each + directory in the ``COMPREHENSIVE_THEME_DIRS`` configuration property. The + following example shows the configuration for multiple themes directories. + + .. code-block:: none + + "COMPREHENSIVE_THEME_DIRS": [ + "/my-open-edx-themes/edx-platform", + "/my-other-open-edx-themes/edx-platform" + ], + +**************************************** +Example Settings for Comprehensive Theme +**************************************** + +For the following file structure: + +.. code-block:: none + + edx + └── my-themes + └── my-theme-red + ├── cms + └── lms + └── static + └── templates + +set these in lms.yml and studio.yml: + +.. code:: json + + "COMPREHENSIVE_THEME_DIRS": [ + "/edx/my-themes", + ], + "THEME_NAME": "my-theme-red" + + +************************ +Apply a Theme to a Site +************************ + +To apply a theme to an Open edX site, follow these steps. + +#. Make sure that you have enabled theming for your Open edX installation and + that you have configured an installation-wide themes directory. For more + information, see :ref:`enable_theming`. + +#. Make sure that you have created a theme and that you know the identifier of + the theme. The identifier of a theme is the name of the directory for that + theme, within your installation-wide themes directory. For more information, + see :ref:`Creating a Theme`. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. Select **Site themes**. + +#. Select **Add site theme**. + +#. From the **Site** menu, select the site you want to apply a theme to. + +#. In the **Theme dir name** field, enter the identifier of the theme. + +#. Select **Save**. + diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/index.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/index.rst new file mode 100644 index 000000000..7c7e7849d --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/index.rst @@ -0,0 +1,37 @@ +.. _Theming Open edX: + +##################################### +Changing Themes for an Open edX Site +##################################### + +The theme for a website defines the appearance of its user interface (UI): the +logo, the color scheme, and the links in the page headers and footers are +examples of different aspects of an Open edX site that are defined by its +theme. + +Open edX provides a default theme that is defined by page templates, CSS +styling, and assets such as images that are provided in the Open edX code. You +can change the appearance of the following parts of an Open edX site. + +* The Studio UI, which is used by course teams. + +* The learning management system (LMS) UI, which is used by learners and course + teams. + +* The UI of the E-commerce service, which is used by course offering and order + managers. + +The topics in this section describe how you can change the way an Open edX +site looks, without changing how it works. + +.. toctree:: + :maxdepth: 2 + + overview_themes + theme_directories + create_theme + enable_themes + compiling_theme + +In addition, an `example theme `_ is +available for review. diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/overview_themes.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/overview_themes.rst new file mode 100644 index 000000000..d97d92638 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/overview_themes.rst @@ -0,0 +1,21 @@ +.. _Theming Overview: + +################### +Themes Overview +################### + +After you configure one or more sites for your Open edX installation, including +their domain and platform names, you can set up a theme to use for each site. + +To override the files that constitute the default Open edX theme, you create +replacements for one or more of those files, place them in file paths that are +constructed and named in parallel to the default file locations, +configure your Open edX instance to use the files in your theme's directories +instead of the default locations, and then compile the theme. + +EdX first looks for files in your theme directories, and uses any file that +matches the exact file path and file name of a default UI file. If matching +files are not found, then Open edX looks in the default location. + +For more information about Open edX sites, see :ref:`Configuring Open edX +Sites`. diff --git a/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/theme_directories.rst b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/theme_directories.rst new file mode 100644 index 000000000..3ef324871 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/changing_appearance/theming/theme_directories.rst @@ -0,0 +1,60 @@ +.. _Themes Root Directories: + +################################# +Root Directories for Theme Files +################################# + +Themes are located outside of the Open edX source directories, in any location +you like. For example, you might make a directory called +``/my-open-edx-themes``. + +Within that directory, you create a separate directory for each Open edX +repository that you want to create a theme for, such as ``edx-platform`` +and ``ecommerce``. + +Within each of those directories, you create another directory and name it for +your theme, such as ``my-theme``. You can create a number of themes, each with +their own name. Within each theme directory, you create directories and files +to parallel the structure in the corresponding Open edX repository. + +After you create these directories, you might have a structure like this one. + +.. code:: + + my-open-edx-themes + ├── ecommerce + │   └── my-theme + └── edx-platform + └── my-theme + ├── cms + └── lms + +You must give the files that you create for a theme the same relative file +paths and file names as the default files that they override. Different root +directories for the relative paths apply to Studio, the LMS, and the E-commerce +service. + +* For Studio and the LMS, relative file paths are from the root directory of + the local clone of the ``edx/edx-platform`` repository in your installation + directory. + +* For the E-commerce service, relative file paths are from the ``ecommerce`` + directory of the local clone of the ``edx/ecommerce`` repository in your + installation directory. + +For example, the root directory for the relative file paths of your theme files +might be at one of the following file paths. + +* For the LMS UI or Studio UI, ``/edx/app/edxapp/edx-platform``. + +* For the UI of the E-commerce service, + ``/edx/app/ecommerce/ecommerce/ecommerce``. + +The following subdirectories hold the UI files that you can override. + +* ``static`` holds media files such as images and styling resources such as + Syntactically Awesome Style Sheet (Sass) files that produce Cascading Style + Sheet (CSS) files. + +* ``templates`` holds Python web application page templates that produce the + HTML for UI pages. diff --git a/source/site_ops/install_configure_run_guide/configuration/config_allowed_regis_emails.rst b/source/site_ops/install_configure_run_guide/configuration/config_allowed_regis_emails.rst new file mode 100644 index 000000000..246a1a04f --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/config_allowed_regis_emails.rst @@ -0,0 +1,69 @@ +.. _Configure Allowed Registration Email Patterns: + +################################################ +Specifying Allowed Registration Email Patterns +################################################ + +This topic describes how to restrict registration on your site by specifying +which email address patterns are allowed in registration emails. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +By default, all email addresses are accepted when learners register for an +account on your Open edX site. You have the option of restricting registrations +to learners who use an allowed email address pattern. Doing so can be useful in +cases where you want to allow only learners who are members of a school, +organization, or corporation to register and access your courses. + +.. note:: Configuring your site using the procedure below only restricts + registration to learners whose email addresses match the specified patterns. + It does not hide courses from any learners, or prevent access to pages on + your site that can be accessed without registration. + + +********************************* +Configure Allowed Email Patterns +********************************* + +To specify the email patterns that are allowed for registration, follow these steps. + +#. Locate the ``lms.yml`` and ``studio.yml`` files, which are located + one level above the ``edx-platform`` directory. You make the same changes + to both files. + +#. In the ``lms.yml`` and ``studio.yml`` files add the + ``REGISTRATION_EMAIL_PATTERNS_ALLOWED`` setting. + + .. code-block:: none + + "REGISTRATION_EMAIL_PATTERNS_ALLOWED": null + + + If the value for this setting is ``null``, there are no restrictions, and all + email addresses are accepted for registration. + +#. Use one or more Python regular expressions to specify the email domains that + allowed email addresses must match. + + The following example allows email addresses using the pattern + ``example.com`` or ``any.example.com`` to register. It also allows + ``school.tld`` addresses, but only if those addresses have a ``.`` before + the ``@`` symbol. + + .. code-block:: none + + "REGISTRATION_EMAIL_PATTERNS_ALLOWED" = [ + + "^.*@(.*\\.)?example\\.com$", + "(^\\w+\\.\\w+)@school\\.tld$" + ] + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +#. Restart your ``edxapp`` instances. diff --git a/source/site_ops/install_configure_run_guide/configuration/configure_milestone_app.rst b/source/site_ops/install_configure_run_guide/configuration/configure_milestone_app.rst new file mode 100644 index 000000000..3bb591a5b --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/configure_milestone_app.rst @@ -0,0 +1,18 @@ + +.. for reuse, not in TOC, excluded from build list + +************************************ +Configure the Milestones Application +************************************ + +#. Set the value of ``MILESTONES_APP`` in the ``lms.yml`` and + ``studio.yml`` files to ``True``. + + .. code-block:: none + + # Milestones application flag + 'MILESTONES_APP': True, + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +#. Run database migrations. diff --git a/source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst b/source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst new file mode 100644 index 000000000..517444fa1 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/customize_registration_page.rst @@ -0,0 +1,67 @@ +.. _Customize Registration Page: + +############################################# +Adding Custom Fields to the Registration Page +############################################# + +This topic describes how to add custom fields to the registration page for your +instance of Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +By default, the registration page for each instance of Open edX has fields that +ask for information such as a user's name, country, and highest level of +education completed. You can add custom fields to the registration page for +your own Open edX instance. These fields can be different types, including +text entry fields and drop-down lists. + +********************************************* +Add Custom Fields to the Registration Page +********************************************* + +Before you add a custom field to the registration page, you must make sure that +the combined sign-in and registration form is enabled for your Open edX +instance. To do this, open the ``lms.yml`` and ``studio.yml`` files, and +set the ``ENABLE_COMBINED_LOGIN_REGISTRATION`` feature flag to True. These +files are located one level above the ``edx- platform`` directory. + +To add custom fields to the registration page, follow these steps. + +#. Start and sign in to your instance of Open edX. + +#. Use Python to create a Django form that contains the fields that you want to + add to the page, and then create a Django model to store the information + from the form. + + For more information about how to create Django forms, see `Django Forms`_ + on the `Django website`_. + +#. In the ``lms.yml`` file, add the app for your model to the + ``ADDL_INSTALLED_APPS`` array. + +#. In the ``lms.yml`` file, set the ``REGISTRATION_EXTENSION_FORM`` + setting to the path of the Django form that you just created, as a dot- + separated Python string. + + For example, if your form is named "ExampleExtensionForm" and is located at + "path/to/the_form.py", the value of the setting is + ``path.to.the_form.ExampleExtensionForm``. + +#. Run database migrations. + +#. Restart the LMS and verify that the new fields appear on your registration + form. + +.. note:: + + For an example app for custom forms, see the OpenCraft `custom_form_app`_ + page in `GitHub`_. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/deprecated_add_course_talk_widget.rst b/source/site_ops/install_configure_run_guide/configuration/deprecated_add_course_talk_widget.rst new file mode 100644 index 000000000..e577f378e --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/deprecated_add_course_talk_widget.rst @@ -0,0 +1,58 @@ +.. _Add CourseTalk (Deprecated): + +############################################# +Adding the CourseTalk Widget +############################################# + +This topic describes how to add `CourseTalk`_ widgets to your instance of Open +edX. When you add the CourseTalk widget, it is visible for all courses. + +.. Note:: + + This feature has been deprecated and is unavailable in Lilac and onwards. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +The CourseTalk widget allows learners to write reviews of your course and see +reviews that other learners have written. Learners can write reviews on the +course **Course** page, and the reviews are visible both in the course, and on +the course **About** page. Only learners who are enrolled in the course can +leave reviews of a course. + +.. image:: ../Images/course_reviews.png + :width: 250 + :alt: Examples of course reviews on a course's About page. + +********************************************* +Add the CourseTalk Widget +********************************************* + +To add the CourseTalk widget, follow these steps. + +#. Sign in to the Django administration console for your base URL. For example, + go to ``http://{your_URL}/admin``. +#. In the navigation pane, locate **Coursetalk**, and then select **Course talk + widget configurations**. +#. On the **Select course talk widget configuration to change** page, select + **Add course talk widget configuration**. +#. On the **Add course talk widget configuration** page, select the + **Enabled** check box, enter a value in the **Platform key** field, and then + select **Save**. + + .. note:: + You can use any text that you want as your platform key. EdX recommends + that you use your domain name, or part of your domain name. + +#. In the LMS, open the **Course** page for any of your Open edX courses. Verify that the **Reviews** link in the sidebar opens the CourseTalk widget. +#. Sign out of your instance of Open edX and view the About page for any + course. +#. In the right pane, verify that the CourseTalk widget appears below the + course information panel. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/edx_search.rst b/source/site_ops/install_configure_run_guide/configuration/edx_search.rst new file mode 100644 index 000000000..1eee479d9 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/edx_search.rst @@ -0,0 +1,193 @@ +.. _Enable edX Search: + +######################### +Enabling Open edX Search +######################### + +You can add a search feature to your Open edX site so that prospective learners +can find courses more easily. When a learner searches for a key word or words, +the search feature returns a list of the courses that are currently open for +enrollment and that match the entered key words. + +This section describes how to enable search in your instance of Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +`EdX Search`_ is a Django application that provides access to search services +from within edX Platform applications. Searching is accomplished by creating an +index of documents, and then searching within that index for matching +information. + +When you install the Open edX devstack, edX search is enabled by +default. You must enable this feature to use it with Open edX fullstack. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +********************************** +Search Engines and edX Search +********************************** + +By default, edX Search uses MockSearchEngine for testing and ElasticSearch +Engine for production. You can configure edX Search to use a different search +engine. + +================= +MockSearchEngine +================= + +MockSearchEngine is a simple implementation using a JSON file for index +storage. It has no specific requirements, but it does not scale well and should +only be used for testing. + +==================== +ElasticSearchEngine +==================== + +ElasticSearchEngine is a ElasticSearch back-end implementation. It uses same +ElasticSearch version that is already part of Open edX Platform. The current +version is v1.5.2. The ElasticSearch Python client is the latest 1.x version. + +************************ +EdX Search Requirements +************************ + +EdX Search requires the following applications. + +* Django (edX Platform version) +* pyMongo (edX Platform version) +* pytz +* Django elasticsearch (0.4.5) + +************************* +Install edX Search +************************* + +EdX Search is included in Open edX Platform GitHub requirements and is +installed automatically when you install the Open edX Platform. + + +***************** +Enable Indexing +***************** + +You enable course indexing by setting the ``ENABLE_COURSEWARE_INDEX`` flag. + +You enable library indexing by setting the ``ENABLE_LIBRARY_INDEX`` flag. + +Indexing is done from Studio as a Celery task. Every publish event triggers the +reindex procedure. + +You can also reindex the course manually through the **Reindex** button in the +**Course Overview** page. + +.. note:: The search feature only returns results for courses that are + currently open for enrollment. Course teams can set the enrollment start and + end dates for their courses in Studio. For more information, see + :ref:`Guidelines for Start and End Dates` in the *Building + and Running an Open edX Course* guide. + +============================== +Which Data Gets Indexed +============================== + +Which data gets indexed is determined by the module ``index_dictionary()`` +function implementation. Modules supporting this method are ``Sequence``, +``Vertical``, ``Video``, and ``HTML Block``. You can add support to any module +type. + +Course metadata, including the name, description, and start and end dates are +also indexed. + +*************** +Supported Flags +*************** + +The following flags are supported in the CMS and LMS applications. + +=== +CMS +=== + +* ``ENABLE_COURSEWARE_INDEX``: Enables and disables courseware content and + course info indexing. + +* ``ENABLE_LIBRARY_INDEX``: Enables and disables library content indexing. + +* ``SEARCH_ENGINE``: Sets the search engine to use. There are two predefined + values. + + * ``"search.elastic.ElasticSearchEngine"`` + * ``"search.tests.mock_search_engine.MockSearchEngine"`` + +* ``ELASTIC_FIELD_MAPPINGS``: Sets any additional field mappings that elastic + search should be aware of. For example, the following code includes the + course start date. + + .. code-block:: none + + ELASTIC_FIELD_MAPPINGS = { + "start_date": { + "type": "date" + } + } + +=== +LMS +=== + +* ``ENABLE_COURSEWARE_SEARCH``: Enables and disables Courseware Search feature + (in course searching). + +* ``ENABLE_DASHBOARD_SEARCH``: Enables and disables Dashboard Search feature + (in enrolled courses searching). + +* ``ENABLE_COURSE_DISCOVERY``: Enables and disables Course Discovery feature + (over courses searching and facet filtering). + +* ``COURSE_DISCOVERY_FILTERS``: If provided, overrides the list of facets that + are used in the Course Discovery feature to filter the results. By default, + all facets will be displayed. The list of available facets includes: + + * Course organization: ``"org"`` + * Course type: ``"modes"`` + * Course language: ``"language"`` + +* ``SEARCH_ENGINE``: Sets the search engine to use. The following values are + predefined. + + * ``"search.elastic.ElasticSearchEngine"`` + * ``"search.tests.mock_search_engine.MockSearchEngine"`` + +* ``SEARCH_INITIALIZER``: Used to set custom SearchInitializer. + SearchInitializer provides an extension to achieve masquerade and other + presearch environmental settings. + + * default: ``SearchInitializer`` + * LMS implementation: + ``lms.lib.courseware_search.lms_search_initializer.LmsSearchInitializer`` + +* ``SEARCH_RESULT_PROCESSOR``: Used to set custom SearchResultProcessor. + SearchResultProcessor does post processing and data manipulation on a result + set returned by SearchEngine. + + * default: ``SearchResultProcessor`` + * LMS implementation: + ``lms.lib.courseware_search.lms_result_processor.LmsSearchResultProcessor`` + +* ``SEARCH_FILTER_GENERATOR``: Used to set custom SearchFilterGenerator. + SearchFilterGenerator sets filters defined by current active user. Basic + implementation sets only course start date filter. + + * default: ``SearchFilterGenerator`` + * LMS implementation: + ``lms.lib.courseware_search.lms_filter_generator.LmsSearchFilterGenerator`` + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_ccx.rst b/source/site_ops/install_configure_run_guide/configuration/enable_ccx.rst new file mode 100644 index 000000000..2fd191445 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_ccx.rst @@ -0,0 +1,32 @@ +.. _Enable CCX: + +#################################### +Enabling Custom Courses +#################################### + +To enable designated users to create custom courses (CCX) on your instance of +Open edX, you must configure the ``server-vars.yml`` file in the edX platform. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +#. Stop the LMS server. + +#. Create or update the file ``/edx/app/edx_ansible/server-vars.yml`` to + include the CCX feature flag. + + .. code-block:: yaml + + EDXAPP_FEATURES: + CUSTOM_COURSES_EDX: true + +#. Run the command ``/edx/bin/update``. + + .. code-block:: bash + + sudo /edx/bin/update edx-platform + +#. Restart the LMS server. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_certificates.rst b/source/site_ops/install_configure_run_guide/configuration/enable_certificates.rst new file mode 100644 index 000000000..ec17997b0 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_certificates.rst @@ -0,0 +1,403 @@ +.. _Enable Certificates: + +############################ +Enabling Course Certificates +############################ + +This topic describes how to enable and configure course certificates in your +instance of Open edX. + +For information about configuring program certificates, refer to documentation +in the `edx/credentials`_ GitHub repository. + +.. contents:: + :local: + :depth: 1 + +**************************** +Course Certificates Overview +**************************** + +Organizations and course teams can choose to generate certificates for learners +who pass a course. Learners can view, print, or share their certificates. + +For additional information about certificates, see +:ref:`Manage Course Certificates` in the *Building and Running an +Open edX Course* guide or :ref:`Print a Web Certificate` in the +*Open edX Learner's Guide*. + +To enable course certificates on your instance of Open edX, you must enable a +feature flag in both Studio and the Learning Management System and complete the +configuration tasks described in this topic. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +************************************************ +Enable Course Certificates in Studio and the LMS +************************************************ + +To enable certificates, modify the ``lms.yml`` and ``studio.yml`` +files, which are located one level above the ``edx-platform`` directory. + +#. In the ``lms.yml`` and ``studio.yml`` files, set the value of + ``CERTIFICATES_HTML_VIEW`` within the ``FEATURES`` object to ``true``. + + .. code-block:: none + + "FEATURES": { + ... + 'CERTIFICATES_HTML_VIEW': true, + ... + } + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +#. If it does not exist already, create the folder ``/tmp/certificates`` owned + by the user and group ``www-data``. Depending on your configuration, this + folder might not survive reboots, and so might need to be created by a + script. + +#. Run database migrations. + + +***************************************** +Configuring Course Certificates in Studio +***************************************** + +Within Studio, course team members with the Admin role can create and edit a +certificate configuration that is used to generate certificates for their +course, including adding signatories and images for organization logo and +signature images for signatories. For details, :ref:`Manage Course +Certificates` in *Building and Running an Open edX Course*. + + +******************************************************** +Configure Course Certificates for Your Open edX Instance +******************************************************** + +#. Access the LMS Django Administration website for your instance of Open edX. + To do this, go to ``https:///admin``. + For example, this might be ``https://courses.YourOrganization.com/admin``. + +#. Under **Site Administration** > **Certificates**, add an HTML View + Configuration, and select **Enabled**. + +#. Set the following certificates-related parameters for your Open edX + instance. + + * ``platform_name`` + * ``company_about_url`` + * ``company_privacy_url`` + * ``company_tos_url`` + * ``company_verified_certificate_url`` + * ``logo_src`` + * ``logo_url`` + + For each course mode for which you want to offer certificates (such as + "honor" or "verified"), define these parameters. + + * ``certificate_type`` + * ``certificate_title`` + * ``document_body_class_append``. + + Make sure the mode name matches your course mode name exactly. An example + follows. + + For more information about course modes, also called enrollment modes + or enrollment tracks, see :term:`Enrollment track`. + + .. code-block:: none + + { + "default": { + "accomplishment_class_append": "accomplishment-certificate", + "platform_name": "YourPlatformName", + "company_about_url":"https://www.YourOrganization.com/about-us", + "company_privacy_url": "https://www.YourOrganization.com/our-privacy-policy", + "company_tos_url": "https://www.YourOrganization.com/our-terms-service", + "company_verified_certificate_url": "https://www.YourOrganization.com/about_verified_certificates", + "logo_src": "/static/certificates/images/our_logo.svg", + "logo_url": "www.YourOrganization.com" + }, + "honor": { + "certificate_type": "honor", + "certificate_title": "Honor Certificate", + "document_body_class_append": "is-honorcode" + }, + "verified": { + "certificate_type": "verified", + "certificate_title": "Verified Certificate", + "document_body_class_append": "is-idverified" + }, + "base": { + "certificate_type": "base", + "certificate_title": "Certificate of Achievement", + "document_body_class_append": "is-base" + } + } + +#. Save the configuration parameters. + +#. Restart the Studio and LMS processes to load the updated environment + configurations. + + +.. _Discontinue Audit Certificates: + +==================================== +Discontinue Audit Track Certificates +==================================== + +Organizations that previously offered certificates to audit track learners will +no longer be able to grant certificates to these learners. Learners can +continue to audit courses, but they will not be able to earn a certificate. + +For more information about course tracks, also called enrollment modes or +enrollment tracks, see :term:`Enrollment track`. + + +***************************************************** +Customize Certificate Templates For Your Organization +***************************************************** + +Set up the templates for certificates that your organization will issue. Base +templates are included, but you must ensure that they are customized for your +organization. For example, you can change the images that appear on +certificates for each course mode that your organization supports, as well as +fonts and colors that are used on certificates. + +To issue certificates in more than one language, see :ref:`Certificates in +Additional Languages`. + +To display hours of effort on certificates, see :ref:`Display Hours of +Effort`. + +Assets for HTML certificates exist in the following locations. + +* ``lms/templates/certificates`` - this folder contains .html files for + certificates. The file ``valid.html`` is an example of a certificate file. + Files with names that start with an underscore, such as + ``_certificate_footer.html``, are partial files that can be referenced in the + main certificate .html files. + +* ``lms/static/certificates`` - subfolders of this folder contain assets used + in creating certificates, such as images, fonts, and sass/css files. + + .. note:: The organization logo on a certificate is uploaded in Studio. For + details, see :ref:`Manage Course Certificates` in *Building + and Running an Open edX Course*. + + + +.. _Certificates in Additional Languages: + +******************************************* +Enable Certificates in Additional Languages +******************************************* + +You can configure course certificates to render in a specific language. + +.. contents:: + :local: + :depth: 1 + +===================================================== +Configure Course Certificates in Additional Languages +===================================================== + +To enable generating course certificates in languages other than the +default language of your platform, follow these steps. + +.. note:: Base certificate templates already exist for English and + Spanish. If you want a course certificate that is different from the + default certificate for the organization or language, create a new + certificate template. + +#. Add the language in which you want to generate certificates to + ``EDXAPP_CERTIFICATE_TEMPLATE_LANGUAGES`` + (``edx/configuration/playbooks/roles/edxapp/defaults/main.yml``), where the + key is the language code and the value is the name of the language. + + For example, ``'fr':'français'``. + +#. In the LMS Django Administration site for your instance of Open edX, under + **Site Administration** > **Certificates** > **Certificate templates**, add + a certificate template for each additional language in which you want to + generate certificates. + +#. In each certificate template, modify the configuration parameters as + required to apply the template either to all course runs in an + organization, or to a single course run. + + + .. list-table:: + :widths: 10 35 35 + :header-rows: 1 + + * - Parameter + - To apply the template to all course runs + in the organization + - To apply the template to a specific course run + * - ``Language`` + - Select the language that you want the certificate to be generated + in. + - Select the language that you want the certificate to be generated + in. + * - ``Organization ID`` + - Enter the ID for the organization whose courses should use this + certificate template. + - Select ``None``. + * - ``Course Key`` + - Leave empty. + - Enter the course key for the course run which should use this + certificate template. + * - ``Mode`` + - (Optional) Specify the course mode for which certificates will be + generated using this template. If no mode is specified, this template + is used for all course modes. + - (Optional) Specify the course mode for which certificates will be + generated using this template. If no mode is specified, this template + is used for all course modes. + * - ``Is Active`` + - Select this checkbox to make this template active. + - Select this checkbox to make this template active. + + + .. note:: If more than one certificate template would apply to a course + run, the most specific (lowest level) template is used. For example, if + you define a certificate template for all courses in an organization and + another template for a specific course run, the template for the course + run is used. + +#. Save each certificate template. + +#. ONLY if you are enabling additional language certificates for a specific + course run, add a certificate generation course setting in LMS Django + Administration, under **Site Administration** > **Certificates**. + +#. In the **Course key** field of the certificate generation course setting, + specify the course run for which you are enabling language specific + certificate templates. + +#. Select **Language specific templates enabled**, and save the configuration. + + +.. _Display Hours of Effort: + +********************************************** +Display Hours of Effort on Course Certificates +********************************************** + + +To display hours of effort for a course run on a course certificate, follow +these steps. + +#. Log in to the Discovery service Django Administration site for your instance + of Open edX. To do this, go to ``https:///admin``. For example, this might be + ``https://discovery.YourOrganization.com/admin``. + +#. Under **Course Metadata** > **Course Runs**, locate the course run, and make + sure there are values for the following attributes. + + * Max effort + * Weeks to complete + +#. Log in to the LMS Django Administration site for your instance of Open edX. + To do this, go to ``https:///admin``. For example, this might be + ``https://courses.YourOrganization.com/admin``. + +#. Under **Site Administration** > **Certificates**, add or edit a + certificate generation course setting. + +#. Select ``Yes`` for **Include hours of effort** and save the configuration. + +#. Under **Site Administration** > **Certificates**, add or edit a certificate + template. + +#. In the certificate template, ensure that a ``div`` element exists that + includes the context variable ``hours_of_effort``. + +#. Save your edits to the certificate template. + +.. _Enable Automatic Certificate Generation: + +*************************************** +Enable Automatic Certificate Generation +*************************************** + +It is suggested that automatic certificate generation +be enabled in order to provide the best experience for learners. +Particularly in self-paced courses (see :ref:`Enable Self Paced +Courses`), your learners might not want to wait until an instructor +initiates certificate generation; instead, they would typically expect +to be able to download their certificates as soon as they achieve a +passing grade. This can be achieved by enabling *auto_certificate_generation* +as described below. + +To globally enable this functionality, you must set a `Waffle switch +`_: + +#. In the LMS Django Administration site for your instance of Open + edX, under **Django-Waffle** > **Switches**, select **Add Switch**. + +#. Name the switch ``certificates.auto_certificate_generation``. + +#. Tick the **Active** checkbox. + +#. Optionally, add a **Note** describing that the switch enables + certificate auto-generation for self-paced courses, or any other + information you consider necessary. The **Note** contents are never + shown to learners. + +#. Click **Save** to activate the switch. + +Open edX caches the value of this Waffle switch, thus the changed +setting may take several minutes to propagate in a large installation. + +In addition to this Waffle switch, automatic certificate generation +requires certain settings to be defined for the course, by a member of +the course staff. For more details, see :ref:`Allow +Learners to Receive Early Certificates` and +:ref:`Allow Learners to Download Certificates` in +*Building and Running an Open edX Course*. + +.. _Manually Generate Certificates for a Course: + +******************************************* +Manually Generate Certificates For a Course +******************************************* + +To manually generate certificates for a course, run the ``manage.py`` script +with the following settings. When the script finishes running, course certificates +will have been generated for eligible learners. + +#. Obtain the course ID for the course for which you are generating + certificates. When you view course content in your browser, the course ID + appears as part of the URL. For example, in the URL + ``http://www.edx.org/course/course-v1:edX+demoX_Demo_2015``, the course ID + is ``course-v1:edX+demoX_Demo_2015``. For some courses, the course ID + contains slashes, however it will not contain beginning or trailing slashes. + For example, a course id look like ``edX/Demox/Demo_2014``. + +#. Obtain the user IDs for any learners for whom you'd like to generate course + certificates. These can be found in the ``auth_user`` database table. + +#. Run ``manage.py`` with the following settings, replacing {UserID} with a user id + and ``{CourseID}`` with the course ID. Do not include beginning or trailing slashes. + + ``./manage.py lms --settings=production cert_generation -u {UserID} {UserID} -c {CourseID}`` + + For example, + + ``./manage.py lms --settings=production cert_generation -u 123 456 -c course-v1:edX+DemoX+Demo_Course`` + +#. You can then view the certificates in the ``certificates_generatedcertificate`` database table. + + +.. include:: /links.txt + +.. _edx/credentials: https://github.com/openedx/credentials diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_custom_course_settings.rst b/source/site_ops/install_configure_run_guide/configuration/enable_custom_course_settings.rst new file mode 100644 index 000000000..fe7d17d28 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_custom_course_settings.rst @@ -0,0 +1,25 @@ +.. _Enable Custom Course Settings: + +#################################### +Enabling Custom Course Settings +#################################### + +To enable course developers to add custom fields to a course on your instance +of Open edX, you must configure the ``studio.yml`` file in the edX platform. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +#. Stop the LMS server. + +#. Create or update the file ``studio.yml`` to include the custom course + settings feature flag. + + .. code-block:: yaml + + 'ENABLE_OTHER_COURSE_SETTINGS': true, + +#. Restart the LMS server. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_discussion_notifications.rst b/source/site_ops/install_configure_run_guide/configuration/enable_discussion_notifications.rst new file mode 100644 index 000000000..5984ac2b6 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_discussion_notifications.rst @@ -0,0 +1,63 @@ +.. _Enabling Discussion Notifications: + +########################################## +Enabling Discussion Notifications +########################################## + +You can set up notifications that learners receive the first time that anyone +adds a response to a discussion post that they have made. + +For more information, including the text of the discussion notification +message, see :ref:`Automatic Emails` and +:ref:`Receiving Discussion Notifications`. + +.. contents:: + :depth: 1 + :local: + +.. _Requirements for Discussion Notifications: + +***************************************** +Requirements for Discussion Notifications +***************************************** + +To create discussion notifications for your instance of the Open edX platform, +you need the following items. + +* edX Automated Communication Engine (ACE). For more information about how to + install and configure ACE, see `edX Automated Communication Engine`_. +* A third party email client, such as Sailthru. For information about how to + configure your email client, see the documentation for the client. + +.. _Enable Discussion Notifications: + +******************************* +Enable Discussion Notifications +******************************* + +After you have set up ACE and the third party email client, you enable +discussion notifications in the Django administration console for your instance +of Open edX. + +#. Sign in to the LMS Django administration console for your base URL. For + example, ``http://{your_URL}/admin``. + +#. On the **Site Administration** page, locate **Site_Configuration**. + +#. In the **Site_Configuration** section, next to **Site configurations**, + select **Change**. + +#. On the **Change site configuration** page, locate the **Values** field, and + then add the following value. + + :: + + { + "enable_forum_notifications":true + } + +#. Select **Save**. + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_entrance_exams.rst b/source/site_ops/install_configure_run_guide/configuration/enable_entrance_exams.rst new file mode 100644 index 000000000..6960f6475 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_entrance_exams.rst @@ -0,0 +1,50 @@ +.. _Enable Entrance Exams: + +######################## +Enabling Entrance Exams +######################## + +This topic describes how to enable entrance exams in your instance of Open +edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +Course teams can create an entrance exam for the course. Learners must pass the +entrance exam before participating in the course. + +To enable this feature on your instance of Open edX, you must enable +entrance exams in Studio and the Learning Management System. + +For information about entrance exams, see the *Building and Running an +Open edX Course* and *Open edX Learner's* guides. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +.. include:: configure_milestone_app.rst + +************************************************************************* +Enable Entrance Exams in Studio and the Learning Management System +************************************************************************* + +To enable entrance exams, you modify the ``lms.yml`` and ``studio.yml`` +files, which are located one level above the ``edx-platform`` directory. + +#. Set the value of ``ENTRANCE_EXAMS`` in the ``lms.yml`` and + ``studio.yml`` files to ``True``. + + .. code-block:: none + + # Entrance exams feature flag + 'ENTRANCE_EXAMS': True, + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_licensing.rst b/source/site_ops/install_configure_run_guide/configuration/enable_licensing.rst new file mode 100644 index 000000000..9a1bbd102 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_licensing.rst @@ -0,0 +1,53 @@ +.. _Enable Licensing: + +#################################### +Enabling Course and Video Licensing +#################################### + +This topic describes how to enable licensing in your instance of Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +Course teams can specify licensing options for course content as well as for +each video in a course. + +Course teams can select one of the following license options. + +* All Rights Reserved +* Creative Commons + +By specifying the license, course teams communicate to learners whether and how +they can reuse course content. + +To enable this feature on your instance of Open edX, you must enable licensing +in both Studio and the Learning Management System. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +***************************** +Enable Licensing in Studio +***************************** + +To enable licensing, you modify the ``lms.yml`` and ``studio.yml`` +files, which are located one level above the ``edx-platform`` directory. + +#. In the ``lms.yml`` and ``studio.yml`` files, in the ``FEATURES`` + dictionary, add ``'LICENSING':True``: + + .. code-block:: none + + FEATURES = { + 'LICENSING': True, + . . . + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_pacing.rst b/source/site_ops/install_configure_run_guide/configuration/enable_pacing.rst new file mode 100644 index 000000000..be0e498b1 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_pacing.rst @@ -0,0 +1,52 @@ +.. _Enable Self Paced Courses: + +############################# +Enabling Self-Paced Courses +############################# + +This topic describes how to enable the self-paced courses feature in your +instance of Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +By default, courses are instructor-paced. These courses run on a schedule, +typically four to eight weeks, with new content released each week and set +assignment due dates. You can configure your instance of Open edX so that it +enables self-paced courses. A self-paced course releases content all at once +and is available to complete for three to twelve months after the start date. +In a self-paced course, there are no due dates other than the course end date. + +To enable self-paced courses on your instance of Open edX, you must enable the +self-paced course feature in the Learning Management System. Then, course +teams are able to set up a course as either instructor-paced or self-paced in +Studio. + +For information about how course teams set course pacing, see the +:ref:`Set Course Schedule` topic in the +*Building and Running an Open edX Course* guide. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +************************************************************************* +Enable Self-Paced Courses in the Learning Management System +************************************************************************* + +To enable self-paced courses, follow these steps to edit the configurations, +using the Django administration console for your Open edX LMS. + + #. Log in to the Django administration console for the LMS. + #. In the **Self_Paced** section, locate **Self paced configurations**, and + then select **Add**. + #. Select the **Enabled** and **Enable course home page improvements** + checkboxes. + #. Select **Save**. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_prerequisites.rst b/source/site_ops/install_configure_run_guide/configuration/enable_prerequisites.rst new file mode 100644 index 000000000..843d12369 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_prerequisites.rst @@ -0,0 +1,52 @@ +.. _Enable Course Prerequisites: + +############################# +Enabling Course Prerequisites +############################# + +This topic describes how to enable course prerequisites in your instance of +Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +Course teams can set prerequisites for a course. Learners must complete the +prerequisite courses before participating in the course. + +To use this feature on your instance of Open edX, you must configure the +Milestones application, then enable prerequisites in Studio and the Learning +Management System. + +For information about prerequisites, see the *Building and Running an +Open edX Course* and *Open edX Learner's* guides. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +.. include:: configure_milestone_app.rst + +************************************************************************* +Enable Prerequisite Courses in Studio and the Learning Management System +************************************************************************* + +To enable prerequisite courses, you modify the ``lms.yml`` and +``studio.yml`` files, which are located one level above the ``edx-platform`` +directory. + +#. Set the value of ``ENABLE_PREREQUISITE_COURSES`` in the + ``lms.yml`` and ``studio.yml`` files to ``true``. + + .. code-block:: none + + # Prerequisite courses feature flag + 'ENABLE_PREREQUISITE_COURSES': true, + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_public_course.rst b/source/site_ops/install_configure_run_guide/configuration/enable_public_course.rst new file mode 100644 index 000000000..be7a12d04 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_public_course.rst @@ -0,0 +1,122 @@ +#################################### +Enabling Public Course Content +#################################### + +By default, learners must create an Open edX account, be signed in to the LMS, +and enroll in a course before they can see the course content. The *Public +Course Content* feature gives you the option to make either a course outline +or course content available to anyone, regardless of whether they have registered +for an Open edX account or enrolled in the course. You can decide which courses, +and which parts of those courses, that you want to make public. For example, +you can: + + * **Make just the course outline public.** The LMS displays the course outline + without any links to internal course pages, giving potential learners an + overview of what they will see when they enroll. + + * **Make the entire course public.** Anyone visiting your course outline can + follow links to visit internal course pages, and freely navigate HTML and + Video course content and handouts. + + * **Show different content blocks to public learners vs. enrolled learners.** + You can create content tailored to the public view, while still supporting + the needs of your enrolled audit and paid learners. + +**************************************** +Public Course Content and Search Engines +**************************************** + +In addition to making your course content visible to people who already use your +site, the public course content feature also allows Google and other search +crawlers to index your public course contents. People who are searching for +information about the topics you teach can then find your course through their +normal search behaviors. This can increase the visibility of your organization's +courses and boost enrollments for genuinely interested learners. + +***************************************** +Enable Public Course Content in the Admin +***************************************** + +The public course content feature is enabled in the Django LMS Admin with the +**seo.enable_anonymous_courseware_access** waffle flag. You can use this flag +in two different ways: + +* Create a normal waffle flag to enable this flag for all courses. For more + information, see the `Waffle documentation`_. + + .. image:: ../Images/enable_anonymous_courseware_access.png + :alt: Setting a waffle flag in the Django LMS Admin. + +* Create a **Waffle flag course override** with the ID of a course to enable + this flag for just that course. + + .. image:: ../Images/course_enable_anonymous_courseware_access.png + :alt: Setting a waffle flag in the Django LMS Admin. + +************************************* +Set Visibility for a Course in Studio +************************************* + +After you set the waffle flag to enable public course content in the Django +LMS Admin, you set the visibility for the course content and its About page +in Studio Advanced Settings. + +================================= +Set Course Content Visibility +================================= + +#. View your course in Studio, and navigate to the **Advanced Settings** page. + +#. Locate the **Course Visibility For Unenrolled Learners** setting. + + By default, this is set to ``"private"``, which ensures that only enrolled + learners can access your course content. + + If you change this to ``"public_outline"``, then your course outline, but not + the other course content, will be visible to everyone. + + If you change this to ``"public"``, then all of your course content, including + the course outline, will be visible to everyone. + +================================= +Set Course About Page Visibility +================================= + +If you want your course to be crawled by Google and other search engines, you +should also ensure that your course's About page is visible, and that it is +shown in the course catalog. Without these settings, only people with a link +to your course outline or specific content blocks will be able to find your +course. + +#. View your course in Studio, and navigate to the **Advanced Settings** page. + +#. Locate the **Course Visibility in Catalog** setting and set it to ``"both"``. + + +******************** +Feature Limitations +******************** + +The public course content feature is currently subject to some limitations, +including the following. + +* Anonymous or unenrolled learners are not members of any cohort, and so they + only see course blocks that are not assigned to a content group. If you want + to restrict public access to selected course blocks, you need create content + groups for your private content, and ensure that your enrolled learners are + members of a cohort that can see this content group. + +* Only Text components, Video components, and course handouts have a "public" + view. Unenrolled learners will see a message requesting that they enroll to + see more complex content types, such as discussion forums, problem blocks, + randomized content blocks, exams, Open Response Assessment, and other XBlocks. + +* Unenrolled learners will not see course completion or progress updates as + they proceed through the course, and Open edX doesn't remember where they + left off if they leave the course and come back. + +* The edX mobile apps do not support public course content. + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_socialsharing_icons.rst b/source/site_ops/install_configure_run_guide/configuration/enable_socialsharing_icons.rst new file mode 100644 index 000000000..340232516 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_socialsharing_icons.rst @@ -0,0 +1,143 @@ +.. _Enabling Social Sharing of Courses and Certificates: + +####################################################### +Enabling Social Sharing of Courses and Certificates +####################################################### + +This section describes how to configure Open edX so that learners can share +their certificates, and so course teams can enable learners to share their +courses on social media. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +You can enable learners to share courses and certificates that they earn on +social media sites such as Facebook and Twitter. + +To use this feature on your instance of Open edX, you must configure social +sharing settings. + +Optionally, you can also enable course teams to set custom URLs for social +sharing. If a course team sets a custom course URL, posts to the social sharing +site can include a link back to that URL. If you do not enable custom course +URLS, a link to the course About page in the LMS is used. + +.. note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +******************************* +Configure Social Sharing +******************************* + +To enable social sharing icons for courses, you modify the ``lms.yml`` +file, which is located one level above the ``edx-platform`` directory. + +#. In the ``lms.yml`` file, modify the ``SOCIAL_SHARING_SETTINGS`` + dictionary as needed. + + .. code-block:: none + + SOCIAL_SHARING_SETTINGS = { + 'CUSTOM_COURSE_URLS': True, + 'DASHBOARD_FACEBOOK': True, + 'CERTIFICATE_FACEBOOK': True, + 'CERTIFICATE_FACEBOOK_TEXT': None, + 'CERTIFICATE_TWITTER': True, + 'CERTIFICATE_TWITTER_TEXT': None, + 'DASHBOARD_TWITTER': True, + 'DASHBOARD_TWITTER_TEXT': None + } + + a. For each social sharing icon that you want to enable, set the value of + the setting to ``True``. + + b. If you set ``DASHBOARD_TWITTER`` or ``CERTIFICATE_TWITTER`` to ``True``, + you can also specify default text that learners will see in the Twitter + sharing dialog and that can be included in their tweet. Set the default + text in the ``DASHBOARD_TWITTER_TEXT`` and ``CERTIFICATE_TWITTER_TEXT`` + values. Learners can edit this text before they select the **Share with + Twitter** button in the LMS. + + c. If you set ``CUSTOM_COURSE_URLS`` to ``True``, you must `Enable Custom + Course URLs`_. + +#. Configure the ``SOCIAL_MEDIA_FOOTER_NAMES`` array in the ``lms.yml`` + file to set the order of links you want learners to see in the footer. + + .. code-block:: none + + SOCIAL_MEDIA_FOOTER_NAMES = [ + "facebook", + "twitter", + "youtube", + "linkedin", + "google_plus", + "reddit", + ] + +#. Configure the ``SOCIAL_MEDIA_FOOTER_DISPLAY`` dictionary in the + ``lms.yml`` file to define how you want social media icons to be + displayed. For each social media icon you enable, you define a ``title``, + ``icon``, and ``action``. + + .. code-block:: none + + "facebook": { + "title": _("Facebook"), + "icon": "fa-facebook-square", + "action": _("Like {platform_name} on Facebook") + }, + "twitter": { + "title": _("Twitter"), + "icon": "fa-twitter", + "action": _("Follow {platform_name} on Twitter") + }, + "linkedin": { + "title": _("LinkedIn"), + "icon": "fa-linkedin-square", + "action": _("Follow {platform_name} on LinkedIn") + } + } + +#. Save the ``lms.yml`` file. + +***************************************** +Enable Custom Course URLs +***************************************** + +In addition to enabling the social sharing icons, you can allow course +teams to provide a custom URL for social sharing sites to link back to. + +You must set the ``CUSTOM_COURSE_URLS`` parameter to ``True`` in both the +``lms.yml`` and ``studio.yml`` files. In the ``studio.yml`` file, this +parameter is the only social sharing setting. + +.. code-block:: none + + SOCIAL_SHARING_SETTINGS = { + 'CUSTOM_COURSE_URLS': True + } + +When finished, save the ``lms.yml`` and ``studio.yml`` files. + +================================= +Set a Custom URL for a Course +================================= + +When you enable custom course URLs in your instance of Open edX, course teams +can then set custom URLs for their courses. + +In Studio **Advanced Settings**, the course team specifies the custom course +URL in the **Social Media Sharing URL** setting. + +This URL is provided to the social sharing site for linking back to a course +location. This URL is used only if you have enabled custom URLs in your +instance of Open edX. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_timed_exams.rst b/source/site_ops/install_configure_run_guide/configuration/enable_timed_exams.rst new file mode 100644 index 000000000..31337a695 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_timed_exams.rst @@ -0,0 +1,52 @@ +############################# +Enabling Timed Exams +############################# + +This topic describes how to enable the timed exams feature in your instance of +Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +Course teams can configure course subsections to limit the amount of time that +learners have to complete problems in that subsection. + +To use this feature on your instance of Open edX, you must enable the timed +exams feature in Studio and the Learning Management System. + +For information about how course teams set up timed exams, see the +:ref:`Timed Exams` topic in *Building and Running an Open edX +Course*. For information about the learner experience, see +:ref:`taking_timed_exams` in the *Open edX Learner's Guide*. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +************************************************************************* +Enable Timed Exams in Studio and the Learning Management System +************************************************************************* + +To enable timed exams, you modify the ``lms.yml`` and +``studio.yml`` files, which are located one level above the ``edx-platform`` +directory. + +#. Set the value of ``ENABLE_SPECIAL_EXAMS`` in the + ``lms.yml`` and ``studio.yml`` files to ``true``. + + .. code-block:: none + + # Timed exams feature flag + 'ENABLE_SPECIAL_EXAMS': true, + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +#. Restart the Studio (CMS) and Learning Management System (LMS) processes so + that your updates are loaded. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/enable_weekly_learning_goals.rst b/source/site_ops/install_configure_run_guide/configuration/enable_weekly_learning_goals.rst new file mode 100644 index 000000000..e832f3f63 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/enable_weekly_learning_goals.rst @@ -0,0 +1,44 @@ +.. _Enabling the Weekly Learning Goals Feature: + +########################################## +Enabling the Weekly Learning Goals Feature +########################################## + +.. contents:: + :local: + :depth: 1 + +*************** +Overview +*************** + +The feature adds a new Weekly Learning Goal widget to the course home page. Goal setting and planning supports learner success.  It also supports learners’ time management efforts and accountability. By prompting learners to set their goals when beginning a course and subscribe to helpful reminder emails, we expect to increase engagement and completion rates. + +To use it, learners use the Weekly Learning Goal widget from the course home page to select a weekly learning goal and are automatically subscribed to goal reminder emails. The weekly reminders continue until the learner completes their course and/or their audit access ends. Learners can modify/cancel their goal and reminder settings at any time from the widget or via links in the email. + +The Weekly Learning Goals feature was discussed in this `Nutmeg blog post `_. + +.. note:: This feature is only available on the new learning micro frontend. If that is not already enabled for you, you can view `instructions here `_. + + +********************** +Enable the feature +********************** + +The following waffle flag needs to be enabled: + + ``course_experience.enable_course_goals`` + +To send goal reminder emails, you need to regularly run the following `management command `_. + +edx.org runs this command at the following cron schedule H \*/3 \* \* \* + +The script does a number of checks before sending emails. There are five main conditions that must be met in order for an email to be sent, otherwise an email will not be sent: + +1. The script will check the number of days left for a learner to successfully hit their goal compared to the learning goal selected by the learner (i.e. if the learner has chosen to learn once per week, three times per week, or five times per week) +2. If you're not actively enrolled in the course or your enrollment was this week +3. If an audit user's access expires this week, exclude them from the email since they may not be able to hit their goal anyway +4. If a user has a downloadable certificate, we will consider them as having completed the course and opt them out of receiving emails +5. We want to email users during the morning of their timezone + +.. note:: For the emails to work you will need to have at least one email channel configured within https://github.com/openedx/edx-ace diff --git a/source/site_ops/install_configure_run_guide/configuration/index.rst b/source/site_ops/install_configure_run_guide/configuration/index.rst new file mode 100644 index 000000000..6d4cab4c3 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/index.rst @@ -0,0 +1,40 @@ +.. _Configuring the Open edX Platform: + +###################################################### +Configuring the Open edX Platform +###################################################### + +The following sections provide information about Open edX Platform +configuration options. + +.. toctree:: + :maxdepth: 2 + + updating_platform + sites/index + changing_appearance/index + customize_registration_page + config_allowed_regis_emails + deprecated_add_course_talk_widget + edx_search + enable_certificates + enable_pacing + enable_public_course + enable_ccx + enable_custom_course_settings + enable_discussion_notifications + enable_entrance_exams + ora2/index + enable_prerequisites + enable_licensing + transcripts + lti/index + enable_socialsharing_icons + password + tpa/index + enable_timed_exams + youtube_api + install_xblock + static_replace/cdn + enable_weekly_learning_goals + retrieve_extended_profile_metadata diff --git a/source/site_ops/install_configure_run_guide/configuration/install_xblock.rst b/source/site_ops/install_configure_run_guide/configuration/install_xblock.rst new file mode 100644 index 000000000..f28448f7e --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/install_xblock.rst @@ -0,0 +1,46 @@ +.. _Installing an XBlock: + +########################## +Installing an XBlock +########################## + +The XBlock framework allows developers to expand the Open edX platform by +building different learning experiences and deploying them as XBlocks. Before +course teams can use an XBlock in courses running on an instance of the +Open edX platform, both of the following tasks must be completed. + +* A system administrator installs the XBlock in the instance of the Open edX + platform. + +* Course teams enable the XBlock in the specific courses that will use it. + +.. Future: link to an XBlock reference that would let people explore what's available and get both the GitHub commit string and the key. - Alison 22 Oct 2015 + +To install an XBlock, follow these steps. + +#. Obtain the GitHub location and commit, or PyPi package name and version, + for the XBlock. + +#. Run ``pip`` along with either the GitHub link to the XBlock or the PyPi + package name. + + An example of the GitHub link that installs the Oppia XBlock follows. + + .. code-block:: bash + + pip install git+https://github.com/oppia/xblock.git@9f6b95b7eb7dbabb96b77198a3202604f96adf65#egg=oppia-xblock==0.0.0 + + + An example of the PyPi package name that installs the Peer Instruction + XBlock follows. + + .. code-block:: bash + + pip install ubcpi-xblock==0.4.4 + +The course teams that want to include components that use the XBlock can then +enable the XBlock for their courses. To do so, they add the name specified in +the XBlock’s ``setup.py`` file to each course's advanced module list. For more +information, see :ref:`Enable Additional Exercises and Tools`. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/lti/authentication_options_lti.rst b/source/site_ops/install_configure_run_guide/configuration/lti/authentication_options_lti.rst new file mode 100644 index 000000000..bc96e73fc --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/lti/authentication_options_lti.rst @@ -0,0 +1,59 @@ +.. _Options for LTI Authentication and User Provisioning: + +######################################################## +Options for LTI Authentication and User Provisioning +######################################################## + +When you use your Open edX system as an LTI tool provider, data is collected by +the Open edX system for all learner activity. Each learner has a user account +on the Open edX system that is linked to the user account on the tool consumer +system, so that activity, grades, and state can be passed from one system to +the other. + +The Open edX system supports these user authentication flows for LTI. + +.. contents:: + :local: + :depth: 1 + +.. _Anonymous User Authentication: + +****************************** +Anonymous User Authentication +****************************** + +The first time a learner encounters an Open edX resource in a course, the +Open edX content is immediately launched by a POST to the URL. Without +requiring any action from the learner, the Open edX system creates a user +account and provisions it with a system-generated username, and links it to +the tool consumer user account for that learner. Learners never interact with +the Open edX system directly. + +This authentication flow presents a virtually seamless experience that +significantly reduces user error. The Open edX system passes learner data to +the tool consumer with no subsequent reconciliation of data between the +systems. + +After you :ref:`configure your edX instance as an LTI tool provider`, no further configuration is needed +on your Open edX system for this user authentication flow. + +****************************** +Open edX User Authentication +****************************** + +The first time a learner encounters an Open edX resource in a course, he is +prompted to either sign in with existing credentials or create a user account. +The Open edX system creates a user account and provisions it with the supplied +values, and links it to the tool consumer user account for that learner. The +POST to the URL then delivers the Open edX resource in the tool consumer. After +the initial sign in or account creation step, learners do not interact with the +Open edX system directly. + +In this authentication flow, learners knowingly establish or use credentials on +the Open edX system. This flow provides a smooth learner experience that can +also satisfy legal requirements or privacy concerns. + +After you configure your edX instance as an LTI tool provider, you can +:ref:`configure Open edX user authentication` between your Open edX system and the tool consumer. diff --git a/source/site_ops/install_configure_run_guide/configuration/lti/configure_lti.rst b/source/site_ops/install_configure_run_guide/configuration/lti/configure_lti.rst new file mode 100644 index 000000000..c14002411 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/lti/configure_lti.rst @@ -0,0 +1,104 @@ +.. _Configuring Credentials for a Tool Consumer: + +############################################################### +Configuring Credentials for a Tool Consumer +############################################################### + +For each external learning management system or application (external LMS) that +you want to allow access to your edX instances as an LTI tool consumer, you +create OAuth1 credentials, and then configure your edX instance to allow +access. Each external LMS that you :ref:`configure as a tool consumer +` must have separate credentials. + +.. Commenting out the following option until we understand it better, per Dave Ormsbee - Alison 8 Sep 15 + +.. While each external LMS that you configure as a tool consumer must have separate credentials, you can also choose to create and configure more than one set of credentials for each system. + +.. For example, you can configure a single set of credentials for your campus LMS, or you can configure unique credentials for every course that embeds edX content on that remote LMS. The first approach results in faster configuration time. However, the second approach can lessen the disruption and reconfiguration that might result if you have to revoke access for a single course at a later time. + +After you complete the configuration of a tool consumer on your edX system, you +can add the consumer credentials to your external LMS. For examples of how +course teams might set up a course on an external LMS as a consumer of edX +course content, see :ref:`Using Open edX as an LTI Tool +Provider` in the *Building and Running an edX Course* guide. + +.. _Configure the Tool Consumer: + +********************************* +Configure the Tool Consumer +********************************* + +To configure an LTI tool consumer to have access to your Open edX installation, +follow these steps. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. In the **LTI Provider** section, next to **LTI Consumers** select + **Add**. + +#. Enter the following information. + + - **Consumer Name**: An identifying name for the tool consumer. + + - **Consumer Key**: The console generates a unique key value for this + tool consumer. Alternatively, you can use an external application to + generate the key, and then enter it here. + + - **Consumer Secret**: The console generates a unique secret value for this + tool consumer. Alternatively, you can use an external application to + generate the secret, and then enter it here. + + .. important:: + Do not supply a value for the **Instance guid** field. The + tool consumer generates and supplies a globally unique identifier. + + - **Require User Account**: Checking this makes the content available only + for the learners who already have an account on the Open edX instance. This + is useful when learners need to be linked between different LMS systems. + + By default, :ref:`an anonymous Open edX system user` + is created and all the data is associated with that user. This flag + can be used when it is desirable to associate the data, generated + via LTI interactions, to actual learner accounts instead of an + anonymous account. When this is checked, instead of creating an + anonymous user automatically, a message requesting the learner to sign + into Open edX is displayed on the first LTI launch and the content + is presented after a successful sign in. + + .. important:: + The account linking happens only when the LTI Consumer sends the + learners' email to Open edX by setting the POST data attribute + ``lis_person_contact_email_primary`` in the LTI Launch request. + This feature has only been tested with **Canvas LMS**, with privacy + setting set to "Email Only" or "Public". + + With this flag checked, the LTI content embedded in iframes will require + the following Django configuration. + + .. code-block:: python + + # Needed for passing user session with the LTI Request + SESSION_COOKIE_SAMESITE = 'None' + SESSION_COOKIE_SECURE = True + SESSION_COOKIE_SAMESITE_FORCE_ALL = True + CSRF_COOKIE_SECURE = True + CSRF_COOKIE_SAMESITE = 'None' + + # Needed for showing pages in iframe + X_FRAME_OPTIONS = "ALLOW-FROM " + + + Caveats: + - Setting this flag only associates future interactions of the learner. + This flag cannot be used to migrate data from existing anonymous accounts + to corresponding user accounts. + - Unchecking the flag will not roll back the auto-linked users. In + situations requiring rollback of this feature, it is recommended + to create a new LTI Consumer with this flag turned off, and the + new credentials be used in the LTI consumer application. + + +#. Select **Save** at the bottom of the page. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/lti/enable_lti.rst b/source/site_ops/install_configure_run_guide/configuration/lti/enable_lti.rst new file mode 100644 index 000000000..ec9ef5c71 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/lti/enable_lti.rst @@ -0,0 +1,39 @@ +.. _Enable LTI Provider Functionality: + +################################################# +Enable LTI Provider Functionality +################################################# + +LTI provider functionality is provided in the ``lti_provider`` app, located in +``edx-platform/lms/djangoapps/lti_provider``. + +By default, the ``lti_provider`` app is not used by edX installations. To +enable this functionality throughout the platform, follow these steps. + +#. In the ``edx/app/edxapp/lms.yml`` file, edit the file so that it + includes the following line in the features section. + + .. code-block:: none + + "FEATURES" : { + ... + "ENABLE_LTI_PROVIDER": true + } + +#. Save the ``edx/app/edxapp/lms.yml`` file. + +#. Run database migrations. + +#. Restart the LMS server. + +To verify that the LTI provider functionality is enabled, you can check for the +presence of the following database tables. + +:: + + lti_provider_gradedassignment + lti_provider_lticonsumer + lti_provider_ltiuser + lti_provider_outcomeservice + +If these tables are not present, check that the migrations have run properly. diff --git a/source/site_ops/install_configure_run_guide/configuration/lti/index.rst b/source/site_ops/install_configure_run_guide/configuration/lti/index.rst new file mode 100644 index 000000000..7098fccab --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/lti/index.rst @@ -0,0 +1,29 @@ +.. _Configuring an edX Instance as an LTI Tool Provider: + +######################################################## +Configuring an edX Instance as an LTI Tool Provider +######################################################## + +You can configure your edX instance to be a learning tool interoperability +(LTI) provider to other systems and applications. You can use this LTI +capability to present content from an edX course in any application that is +configured to be a consumer of that content. After you enable your edX instance +as an LTI tool provider and configure credentials for the tool consumers, +course teams can reuse course content from the edX instance in contexts other +than the edX LMS. + +.. toctree:: + :maxdepth: 1 + + enable_lti + configure_lti + settings_lti + authentication_options_lti + tpa_lti + +For more information and examples of how course teams might set up a course on +an external LMS as a consumer of edX course content, see +:ref:`Using Open edX as an LTI Tool Provider` in the *Building +and Running an edX Course* guide. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/lti/settings_lti.rst b/source/site_ops/install_configure_run_guide/configuration/lti/settings_lti.rst new file mode 100644 index 000000000..4d8794f03 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/lti/settings_lti.rst @@ -0,0 +1,35 @@ +.. _Define Interval for Grade Aggregation: + +#################################################### +Define an Interval for Grade Aggregation (Optional) +#################################################### + +When an external LMS links to problem components in a graded edX subsection, +the edX system grades the answers to those problems, and then transfers the +grades back to the external LMS. + +* If the link is to an individual problem component on the edX system, the edX + system returns the grade for each learner immediately. + +* If the link is to a unit or subsection, you can configure an interval of time + for the edX system to delay before returning the grades. The edX system + aggregates all of the problems in the unit or subsection that the learner + answers during that interval. Aggregating grades can reduce the number of + notification messages that learners receive. + +By default, the edX system aggregates grades for units and subsections every 15 +minutes. + +To change the interval for returning aggregated grades, follow these steps. + +#. In ``edx/app/edxapp/lms.yml``, change the value for the following + parameter. + + ``LTI_AGGREGATE_SCORE_PASSBACK_DELAY = 15 * 60`` + + You specify a time value in seconds. + +#. Save the ``/lms/envs/common.py`` file. + +#. Restart the Learning Management System processes so that the + updated environment configurations are loaded. diff --git a/source/site_ops/install_configure_run_guide/configuration/lti/tpa_lti.rst b/source/site_ops/install_configure_run_guide/configuration/lti/tpa_lti.rst new file mode 100644 index 000000000..85aadbcc7 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/lti/tpa_lti.rst @@ -0,0 +1,135 @@ +.. _Configuring Open edX for LTI Authentication: + +############################################################### +Configuring Open edX User Authentication for LTI +############################################################### + +Every learner who accesses content on an Open edX system must have a user +account. The Open edX system uses the accounts to collect data for learner +interactions with course content. + +After you :ref:`configure your edX instance as an LTI tool provider`, you can configure Open edX user +authentication between your Open edX installation and an LTI tool consumer. + +For more information about the authentication flows that are available, see +:ref:`Options for LTI Authentication and User Provisioning`. + +.. contents:: + :local: + :depth: 1 + +************************************************** +Configure Open edX User Authentication for LTI +************************************************** + +To configure Open edX user authentication between your Open edX installation +and an LTI tool consumer, follow these steps. + +.. note:: A consumer key and secret are required. The Django administration + console provides a hexadecimal string for the secret, but does not provide a + hexadecimal string for the key. You must use an external tool to generate the + key. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. In the **Third_Party_Auth** section, next to **Provider Configuration + (LTI)** select **Add**. + +#. Select **Enabled**. + +#. Enter the **Name** of your Open edX system, as you want it to appear on the + registration page that is presented to learners who access Open edX content + from this LTI tool consumer. + +#. To customize the registration process for learners, you can make selections + for these optional fields. + + - **Skip Registration Form**: If you select this option, users are not asked + to confirm any user account data that is supplied for them by the LTI tool + consumer (name, email address, and so on). + + By default, this option is cleared and learners review a registration form + with the account details supplied by the tool consumer. + + - **Skip Email Verification**: If you select this option, users are not + required to confirm their email addresses, and their accounts are activated + immediately upon registration. + + By default, this option is cleared and learners receive an email message + and must select a link in that message to activate their user accounts. + +6. Enter the following information. + + - **Lti consumer key**: Enter the hexadecimal string of the key. + + - **Lti consumer secret**: The system generates a hexadecimal string value + for this field. Alternatively, you can replace it with a secret generated + by an external tool. + +7. Optionally, change the default value for the **Lti max timestamp age**. + +#. Select **Save** at the bottom of the page. + +******************************************* +Test LTI Authentication +******************************************* + +To verify the sign in process for an LTI provider configuration, follow these +steps. + +#. Have the LTI consumer key and secret for the LTI provider configuration + available. For example, use the Django administration console to open the + **Change Provider Configuration (LTI)** page. + +#. Use a separate browser window or tab to open the `IMS LTI 1.1 Consumer + Launch`_ page. + +#. As the **Launch URL**, enter your base URL followed by ``/auth/login/lti/``. + For example, ``http://{your_URL}/auth/login/lti/``. + +#. Copy the **Lti consumer key** value, and then on the IMS LTI 1.1 Consumer + Launch page paste it in as the **Key**. + +#. Copy the **Lti consumer secret** value, and then on the IMS LTI 1.1 Consumer + Launch page paste it in as the **Secret**. + +#. Optionally, change the default values in the **Launch Data** section of the + **IMS LTI 1.1 Consumer Launch** page to match the set of values that the + tool consumer is configured to supply. + +#. To test the workflow for a learner who does not yet have a user account on + your Open edX system, follow these steps. + + - Use a separate browser window or tab to make sure that you are signed out + of your Open edX LMS. + + - On the **IMS LTI 1.1 Consumer Launch** page, select **Recompute Launch + Data** and then select **Press to Launch**. + + The page that is configured for delivery to an unauthenticated user loads at + the bottom of the page. In the example that follows, the registration page + appears (that is, it was not configured to be skipped) and the learner is + prompted to complete required fields. + + .. image:: ../../Images/lti_test_auth.png + :alt: Screen shot of the IMS LTI 1.1 Consumer Launch page with the + registration page for the edX Edge loaded at the bottom. + +#. To test the workflow for a learner who already has a user account on your + Open edX system, follow these steps. + + - Use a separate browser window or tab to sign in to your Open edX LMS. + + - On the **IMS LTI 1.1 Consumer Launch** page, select **Recompute Launch + Data** and then select **Press to Launch**. + + Your Open edX user account is linked to the LTI provider configuration, and + your learner dashboard on the Open edX site loads at the bottom of the page. + To unlink your user accounts, select the arrow next to your username, and + then select **Account**. In the **Connected Accounts** section, select + **Unlink** next to the LTI provider configuration name. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/ora2/index.rst b/source/site_ops/install_configure_run_guide/configuration/ora2/index.rst new file mode 100644 index 000000000..09f5fb900 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/ora2/index.rst @@ -0,0 +1,23 @@ +.. _Configuring Open Response Assessments: + +######################################################## +Configuring Open Response Assessments +######################################################## + +You can change the default configuration for the Open Response Assessment +(ORA2) application. You can change the default file storage system or change +the default set of files that learners are prohibited from submitting. + +.. toctree:: + :maxdepth: 1 + + ora2_uploads + ora2_blacklist + +For more information and examples of how course teams might set up an open +response assessment, see :ref:`Open Response Assessments` +in the *Building and Running an Open edX Course* guide. + + +.. include:: /links.txt + diff --git a/source/site_ops/install_configure_run_guide/configuration/ora2/ora2_blacklist.rst b/source/site_ops/install_configure_run_guide/configuration/ora2/ora2_blacklist.rst new file mode 100644 index 000000000..b75c123f6 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/ora2/ora2_blacklist.rst @@ -0,0 +1,46 @@ + +.. include:: /links.txt + +.. _Configuring ORA2 to Prohibit Submission of File Types: + +############################################################### +Prohibiting Submission of Specified File Types +############################################################### + +Course teams can configure open response assessments so that learners can +upload files along with their text responses. During the peer review stage of +the assessment, other learners download the submitted file and read the +response. + +To protect learners from exposure to files with malicious content, the ORA2 +application uses a "blacklist" to identify a set of file types that learners +are not permitted to upload. + +To add or remove file types from the blacklist, follow these steps. + +#. In the ORA-2 repository, use an editor to open the `submission_mixin.py`_ + file. + +#. Locate the ``FILE_EXT_BLACK_LIST`` parameter in the file. By default, this + parameter lists the following file types. + + :: + + FILE_EXT_BLACK_LIST = [ + 'exe', 'msi', 'app', 'dmg', 'com', 'pif', 'application', 'gadget', + 'msp', 'scr', 'hta', 'cpl', 'msc', 'jar', 'bat', 'cmd', 'vb', 'vbs', + 'jse', 'ws', 'wsf', 'wsc', 'wsh', 'scf', 'lnk', 'inf', 'reg', 'ps1', + 'ps1xml', 'ps2', 'ps2xml', 'psc1', 'psc2', 'msh', 'msh1', 'msh2', 'mshxml', + 'msh1xml', 'msh2xml', 'action', 'apk', 'app', 'bin', 'command', 'csh', + 'ins', 'inx', 'ipa', 'isu', 'job', 'mst', 'osx', 'out', 'paf', 'prg', + 'rgs', 'run', 'sct', 'shb', 'shs', 'u3p', 'vbscript', 'vbe', 'workflow', + 'htm', 'html', + ] + +#. Add or remove values from this list. + +#. Save your changes to ``submission_mixin.py``. + +#. Restart the Studio (CMS) and Learning Management System (LMS) processes so + that your updates are loaded. + diff --git a/source/site_ops/install_configure_run_guide/configuration/ora2/ora2_uploads.rst b/source/site_ops/install_configure_run_guide/configuration/ora2/ora2_uploads.rst new file mode 100644 index 000000000..35c4826c1 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/ora2/ora2_uploads.rst @@ -0,0 +1,31 @@ +.. include:: /links.txt + +.. _Configuring ORA2 to Upload Files to Alternative Storage Systems: + +############################################################### +Configuring ORA2 to Upload Files to Alternative Storage Systems +############################################################### + +By default, the Open Response Assessment (ORA2) application stores files that +learners upload in an Amazon S3 bucket. + +You can configure ORA2 to store files in an alternate system. To have learners' +files stored in a system other than Amazon S3, follow these steps. + +#. In the ORA-2 repository, implement the ``BaseBackend`` class defined in the + `base.py`_ file. + + For example, the `S3.py`_ file in the same directory is an implementation of + ``BaseBackend`` for Amazon S3. You must implement the equivalent class for + the storage system you intend to use. + +#. Configure ORA2 to use your alternative storage system by modifying the value + of ``backend_setting`` in `init file`_ to point to your implementation of + ``BaseBackend``. + +#. Add code to instantiate the new implementation to the ``get_backend()`` + function in the ``init.py`` file. + +#. Configure ORA2 to use the alternative storage system by modifying the value + of ``ORA2_FILEUPLOAD_BACKEND`` in the Django settings to point to your + implementation of ``BaseBackend``. diff --git a/source/site_ops/install_configure_run_guide/configuration/password.rst b/source/site_ops/install_configure_run_guide/configuration/password.rst new file mode 100644 index 000000000..d8877038d --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/password.rst @@ -0,0 +1,107 @@ +.. _Configure Password Policy: + +############################# +Configuring a Password Policy +############################# + +This topic describes how to configure a password policy in your +instance of Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +By default, Open edX imposes a minimal password complexity policy for all +users who log in to the LMS or Studio. Under the default password complexity +policy, passwords must contain 2 to 75 characters and cannot be similar to the +user's username or email address. + +.. note:: Open edX does not store plain-text passwords, only + hashes. Since the length of a hash is independent of the length of + the original password, passwords can effectively be of unlimited + length. The 75-character default limit is rather arbitrary. Open + edX does impose an upper limit of 5,000 characters on a password, + but this should be well beyond the practical limit of password + length. + +This password policy is defined in the ``lms.yml`` configuration file, +under the ``AUTH_PASSWORD_VALIDATORS`` setting:: + + AUTH_PASSWORD_VALIDATORS: + - NAME: django.contrib.auth.password_validation.UserAttributeSimilarityValidator + - NAME: common.djangoapps.util.password_policy_validators.MinimumLengthValidator + OPTIONS: + min_length: 8 + - NAME: common.djangoapps.util.password_policy_validators.MaximumLengthValidator + OPTIONS: + max_length: 75 + +You can override these settings by modifying one of the existing +``OPTIONS``. For example, if you want to enforce a minimum password +length of 16 characters, and a maximum length of 256, +you would set:: + + AUTH_PASSWORD_VALIDATORS: + - NAME: django.contrib.auth.password_validation.UserAttributeSimilarityValidator + - NAME: common.djangoapps.util.password_policy_validators.MinimumLengthValidator + OPTIONS: + min_length: 16 + - NAME: common.djangoapps.util.password_policy_validators.MaximumLengthValidator + OPTIONS: + max_length: 256 + + +.. warning:: If your Open edX configuration :ref:`enables third-party + authentication `, the *maximum* + value you can specify for the ``MinimumLengthValidator``'s + ``min_length`` option is 25. + +You can also substitute your own password policy for the default +policy. To configure a password policy in replacement of the default +password policy, follow these steps. + +#. Create or import a new password validator. This is a Python class that defines how a + password is validated. For details about writing a password validator class, + see :ref:`Creating a Password Validator`. + +#. Add your password validator to the list in the ``AUTH_PASSWORD_VALIDATORS`` + configuration key in the ``lms.yml`` configuration file. For details, + see :ref:`Configuring a Password Validator`. + +.. _Creating a Password Validator: + +***************************** +Creating a Password Validator +***************************** + +An Open edX password validator is a Python class that specifies how user +passwords are validated. You can use whatever criteria you choose to establish +a password policy for your Open edX instance. You can create your own custom +password validator, or import one or more password validators from +`password_policy_validators`_ in the ``edx-platform`` repository on GitHub. +Those password validators include minimum length, maximum length, user +attribute similarity, minimum alphabetic, minimum numeric, minimum uppercase, +minimum lowercase, minimum punctuation, and minimum symbols. For more +information, see also the `Django password validation documentation`_. + +.. _Configuring a Password Validator: + +********************************* +Configuring a Password Validator +********************************* + +To configure your Open edX instance to use a particular password validator, +add your password validator to the list in the ``AUTH_PASSWORD_VALIDATORS`` +configuration key in the ``lms.yml`` configuration file. For example, to +add a password validator named ``MyPasswordValidator``, add a line like this +to the ``lms.yml`` configuration file. +:: + + AUTH_PASSWORD_VALIDATORS: + - NAME: path.to.module.MyPasswordValidatorClass + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/retrieve_extended_profile_metadata.rst b/source/site_ops/install_configure_run_guide/configuration/retrieve_extended_profile_metadata.rst new file mode 100644 index 000000000..8bf3827f5 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/retrieve_extended_profile_metadata.rst @@ -0,0 +1,78 @@ +.. _Retrieve_Extended_Profile_Metadata: + +##################################### +Retrieving Extended Profile Metadata +##################################### + +This topic describes how an Open edX Administrator can configure their system to +retrieve extended profile metadata stored as part of a user's profile. + +.. Note:: + Modifying the software to persist or display the extended profile metadata is + beyond the scope of this document. This section describes how to enable and + include the retrieval of extended profile metadata through the User API. + +.. contents:: + :local: + :depth: 2 + +********* +Overview +********* + +The User API has a mechanism to accept and persist extra user metadata as part +of a user's profile. This is called the *Extended Profile*. While there is no +special configuration required to enable the storage of this data, it won't be +*returned* by default. + +To enable retrieval of Extended Profile data, an Open edX Administrator must +update their instance's Site Configuration. + +Updating the Site Configuration +=============================== + +An Open edX instance's Site Configuration is managed via Django Admin. To update +the configuration properties for a site, follow these steps. + +#. Sign in to the Django administration console for your instance. For example, + ``http://{your_instance_url}/admin``. + +#. Select **Site Configurations**. + +#. From the **Site Configurations** menu, select the site you want to update. + +#. Enter a new configuration property in the **Site values** section named + ``extended_profile_fields``. Ensure that the new property is in valid + JavaScript Object Notion (JSON) format. + + Consider the following example where we want to retrieve an extended profile + field named ``occupation``. + + .. code-block:: none + + { + "PLATFORM_NAME": "Online University", + ...other_fields, + "extended_profile_fields": [ + "occupation" + ] + } + +#. Select **Save**. + +After the updated Site Configuration is saved, when making a GET request to the +User REST API, we should see the ``occupation`` field returned in our requests: + +.. code-block:: none + + { + ...other_fields, + "extended_profile": [ + { + "field_name": "occupation", + "field_value": { + "name": "Organic Farmer" + } + } + ] + } diff --git a/source/site_ops/install_configure_run_guide/configuration/sites/configure_site.rst b/source/site_ops/install_configure_run_guide/configuration/sites/configure_site.rst new file mode 100644 index 000000000..319814f46 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/sites/configure_site.rst @@ -0,0 +1,95 @@ +.. _Configuring Sites Independently: + +################################# +Configuring Sites Independently +################################# + +You can set configuration properties independently for individual sites. The +values that you define for individual sites override the default values that +are present in the ``studio.yml`` or ``lms.yml`` files. For example, you +can set the ``PLATFORM_NAME`` property to a different value for each of your +sites to indicate that the sites present courses for different organizations or +audiences. + +******************* +Configuring a Site +******************* + +To set configuration properties for a site, follow these steps. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. Select **Site Configurations** . + +#. Select **Add site configuration**. + +#. From the **Site** menu, select the site you want to configure. + +#. Enter configuration properties in the **Values** field. Structure all + properties in valid JavaScript Object Notation (JSON) format. + + The following example shows a set of configuration properties for a site. + + .. code-block:: none + + { + "course_email_from_addr":"courses@onlineu.edu", + "university":"Online University", + "PLATFORM_NAME":"Online University", + "email_from_address":"courses@onlineu.edu", + "payment_support_email":"payments@onlineu.edu", + "SITE_NAME":"onlineu.edu", + "site_domain":"onlineu.edu", + "SESSION_COOKIE_DOMAIN":"onlineu.edu" + } + + .. note:: To make courses site-specific, you set the ``course_org_filter`` + property to an organization identifier. Only that organization's courses + are available from the site. + +#. When you are ready for the configuration settings to take effect, + select **Enabled**. + + The configuration properties that you set do not affect the site + until you select **Enabled**. If needed, you can return to the **Site + configurations** screen for this site to enable the configuration properties + later. + +#. Select **Save**. + + +******************************* +Site Configuration Reference +******************************* + +An example of the properties that you define to configure a site follows. + +.. code-block:: none + + { + "ECOMMERCE_API_URL":"https://my-site.sandbox.edx.org/api/v2", + "ECOMMERCE_PUBLIC_URL_ROOT":"https://my-site.sandbox.edx.org", + "ECOMMERCE_API_SIGNING_KEY":"ecommerce-secret", + "COURSE_CATALOG_VISIBILITY_PERMISSION":"see_in_catalog", + "COURSE_ABOUT_VISIBILITY_PERMISSION":"see_about_page", + "ENABLE_COMBINED_LOGIN_REGISTRATION":true, + "ENABLE_PAID_COURSE_REGISTRATION":true, + "course_email_template_name":"my-site", + "course_email_from_addr":"my-site@example.com", + "ALLOW_AUTOMATED_SIGNUPS":true, + "domain_prefix":"my-site", + "university":"Education Programs", + "PLATFORM_NAME":"Education Programs", + "platform_name":"Education Programs", + "show_only_org_on_student_dashboard":true, + "email_from_address":"my-site@example.com", + "payment_support_email":"payments@example.com", + "SITE_NAME":"my-site.sandbox.edx.org", + "site_domain":"my-site.sandbox.edx.org", + "SESSION_COOKIE_DOMAIN":"my-site.sandbox.edx.org", + "course_org_filter":"MyOrgX", + "course_index_overlay_text":"", + "homepage_overlay_html":"", + "payment_email_signature":"Education Programs
The Digital Programs Team
my-site@example.com
101 Example Street
Example State" + } diff --git a/source/site_ops/install_configure_run_guide/configuration/sites/create_site.rst b/source/site_ops/install_configure_run_guide/configuration/sites/create_site.rst new file mode 100644 index 000000000..1c1023046 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/sites/create_site.rst @@ -0,0 +1,22 @@ +.. _Create a Site: + +############################# +Create an Open edX Site +############################# + +To create an Open edX site, follow these steps. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. Select **Sites** to open the ``http://{your_URL}/admin/sites/site`` page. + +#. Enter the domain name for the site. This is the domain name in the URL for + the site. For example, ``myuniversity.edu``. + + To make a site available on a non-default port that is entered as part of + the URL, the domain name must include the port number. For example, if an + LMS site is available at ``my-site.localhost:8000``, the domain name for + the site must be ``my-site.localhost:8000``. + +#. Select **Save**. diff --git a/source/site_ops/install_configure_run_guide/configuration/sites/index.rst b/source/site_ops/install_configure_run_guide/configuration/sites/index.rst new file mode 100644 index 000000000..902a65bc4 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/sites/index.rst @@ -0,0 +1,30 @@ +.. _Configuring Open edX Sites: + +############################# +Configuring Open edX Sites +############################# + +By default, an Open edX installation has one site for users to interact with. +You can configure multiple sites within your Open edX installation. A site +presents Open edX courses and content in an individual way. If you set up +multiple sites, you can configure them independently of each other. For +example, you can assign a different theme to each site and specify which +courses are available on each site. + +You host each site on a separate domain or subdomain from your Open edX +installation. You configure the domain name for a site in the Django admin site +when you create it. For example, you might configure one site +with the domain name ``university.edu`` and another site with the domain +name ``advancedplacement.edu``. Or you might configure one site with the domain +name ``arts.myuniversity.edu`` and another site with the domain name +``sciences.myuniversity.edu``. + + +.. toctree:: + :maxdepth: 1 + + create_site + configure_site + +For more information about themes, see :ref:`Theming Open edX`. + diff --git a/source/site_ops/install_configure_run_guide/configuration/static_replace/cdn.rst b/source/site_ops/install_configure_run_guide/configuration/static_replace/cdn.rst new file mode 100644 index 000000000..481d251f3 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/static_replace/cdn.rst @@ -0,0 +1,72 @@ +.. _Enabling a CDN for Course Assets: + +###################################### +Enabling a CDN for Course Assets +###################################### + +By default, all course assets are served directly from your Open edX instance. +For courses with large enrollments, or courses with large assets, such as high- +quality images, PDFs, or video files, this can increase not only the load on +the instance but also the time it takes for learners to load the courses on +their computers and mobile devices. + +You can configure your Open edX instance to serve assets from a content +delivery network (CDN) instead. Using a CDN offloads the work required to +deliver assets from your Open edX instance. + +.. note:: Whether you need a CDN depends on the type, and amount, of content + in your courses. Not all installations need a CDN for their course assets. + + +.. contents:: + :local: + :depth: 1 + +*************** +Overview +*************** + +A CDN, or content delivery network, is a service that places servers all around +the world, and keeps copies of content on those servers. Instead of serving +files from one location, a CDN serves them from whichever server is closest to +the end user. This results in faster download speeds and, ultimately, faster +page loads. + +******************************** +Guidelines for CDN Configuration +******************************** + +When you configure a CDN for use with your Open edX instance, you should +identify your Open edX instance as the origin server. + +Choose the cache expiration carefully: you want content to be cached long +enough to keep the load on your Open edX instance low, but not so long that +changes made to course assets are not realized within a reasonable amount of +time. As a starting point, edX recommends a cache expiration period of one +hour. + +********************** +Enable the CDN +********************** + +After you configure your CDN, follow these steps. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. In the **Static_Replace** section, next to **Asset base url configs**, + select **Add**. + +#. Select **Enabled**. + +#. Enter the hostname for your CDN provider. + + For example, if you were using CloudFront, this would look something like + ``d37djvu3ytnwxt.cloudfront.net``. + + Be sure not to include the scheme (``http://`` or ``https://``) when you + specify the hostname. + +#. Select **Save**. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/index.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/index.rst new file mode 100644 index 000000000..2728eac85 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/index.rst @@ -0,0 +1,31 @@ +.. _Enabling Third Party Authentication: + +####################################### +Enabling Third Party Authentication +####################################### + +To enhance sign in options for your users, you can enable third party +authentication, sometimes also called "third party auth", "single sign on", or +"SSO", between organizational authentication systems and the sites you define +for your implementation of the edX platform. After you enable third party +authentication, users can register and sign in to your Open edX site with their +campus or organizational credentials. + +.. toctree:: + :maxdepth: 1 + + tpa_providers + tpa_behavior + tpa_integrate_open/index + tpa_SAML_SP + tpa_advanced_features + tpa_eliminating_pii + tpa_IDmap_api + +This section includes information for teams involved in identity management at +Open edX installations, including development operations (DevOps) and +information technology (IT). + + + + diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_IDmap_api.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_IDmap_api.rst new file mode 100644 index 000000000..feb3caeba --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_IDmap_api.rst @@ -0,0 +1,116 @@ +.. _Third Party Auth ID Mapping API: + +############################### +Third Party Auth ID Mapping API +############################### + +Open edX has an API that can be used to retrieve the association between Open +edX user IDs and the unique user identifiers sent by the external platform. + +When an Open edX course is used in an on-premise environment, and SAML, LTI, or +other SSO is enabled to allow learners to authenticate to edX using their on-premise credentials, normally an on-premise identity provider (IdP) sends an +identifier. This identifier is stored in edX and linked to the edX account. +Later, when learners return from an on-premise IdP, edX can authenticate the +learner using their edX account. + +Because learners may create Open edX accounts using an alternative identity, +instructors may have difficulty identifying Open edX learners in their courses. +Grade records obtained from Open edX will only contain Open edX learner IDs, +which would be unknown to the on-premise system. + +This API can be used for mapping between the edX user ID and the ID provided by +the IdP. This API provides information that allows instructors or course +support staff to figure out the identity of the on-premise learners who are +using the edX course. It also allows grade information coming from Open edX to +be appropriately associated to on-premise learners for uploading to an +on-premise learning management system (LMS) or learner information +system (SIS). + +This API is intended to be consumed by on-premise middleware, which combines +the information from an on-premise system. The middleware communicates with the +premise system to get information about the course and enrollment, then uses +that information to control instructor access. The instructor can then perform +tasks such as obtaining the edX learner's on-premise identity, uploading grades +back to their LMS or SIS, and making groups based on on-premise activities. + +This API also helps with the issue where learners enter incorrect email +addresses and cannot activate their accounts, and then cannot authenticate with +Open edX through SSO because of the inactive accounts. With this API, +on-premise course support staff or instructors can provide the Open edX +operator with the learner's real edX username instead of the ID that the +IdP passed over to Open edX, so that the Open edX operator does not have +to manually query the tables to figure out the mapping between the source +system ID and the Open edX username. + +***************************************** +Using the Third Party Auth ID Mapping API +***************************************** + +To use the Third Party Auth ID Mapping API, follow these steps. + +#. Have one or more third party auth providers enabled, and have learners who + have link their accounts to one or more of those providers. + +#. Set up an OAuth2 client. To do this, open the Django administration panel, + select **OAuth2**, select **Client**, select **Add Client**, and then enter + the following information. + + #. For **User**, create a dedicated user for this API. + #. For **URL, Redirect URL**, enter a dummy value such as + ``http://localhost/``. The URL is not used for this API. + #. For **Client Type**, specify **Confidential**. + #. Leave other fields with the default values. + +#. Give the new client permission to this API. To do this, go to + **Third_Party_Auth**, select **Provider API Permissions**, and then select + **Add Provider API Permission**. + +#. Select the OAuth2 client that you just created, and select an external + authentication provider. This will give the new client access to query that + provider mapping. + +The API is now available at ``{LMS base +URL}/api/third_party_auth/v0/providers/{provider_id}/users``. The API client +must use OAuth2 to authenticate before that endpoint will work. The +``{provider_id}`` value uses the same format as described in :ref:`Hinted Sign +In`. + +To test the API, follow these steps. + +#. Use client credentials (from the django admin) to get the access token, as + follows. + + :: + + curl --data "client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=client_credentials" http://localhost:8000/oauth2/access_token + + Returns: {"access_token": "c1efde84445b2f256e1c80886b3f6d46339b84ee", "token_type": "Bearer", "expires_in": 31535999, "scope": ""} + +#. Use the access token to issue requests to the API, as in the following + examples. + + :: + + curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users + + curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?username=USERNAME1,USERNAME2 + + curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?username=USERNAME1&username=USERNAME2 + + curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?remote_id=REMOTE_ID1,REMOTE_ID2 + + curl --header "Authorization: Bearer ACCESS_TOKEN" http://localhost:8000/api/third_party_auth/v0/providers/{provider_id}/users?remote_id=REMOTE_ID1&remote_id=REMOTE_ID2 + +The following example shows a return value from the API. + + .. code-block:: none + + { + "page": 1, + "page_size": 200, + "count": 8, + "results": [ + {"username": "USERNAME1", "remote_id": "REMOTE_ID1"}, + {"username": "USERNAME2", "remote_id": "REMOTE_ID2"}, + ] + } diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_SAML_SP.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_SAML_SP.rst new file mode 100644 index 000000000..8ba249a33 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_SAML_SP.rst @@ -0,0 +1,168 @@ +.. _Configuring your Installation as a SAML Service Provider: + +############################################################### +Configuring your Open edX Site as a SAML Service Provider +############################################################### + +The first step in configuring your Open edX site to act as a SAML SP is +to create a credential key pair to ensure secure data transfers with identity +providers. To complete the configuration procedure, you configure your Open edX +site as a SAML SP, which creates your metadata XML file. + +.. contents:: + :local: + :depth: 1 + +After you complete this configuration, you can share your metadata file with +SAML identity providers, and configure them to assert identity and access +rights for users to your installation. For more information, see +:ref:`Integrating with a SAML Identity Provider`. + +********************************************** +Generate Public and Private Keys +********************************************** + +To generate the keys for your Open edX installation, follow these steps. + +#. On your local computer or on the server, open Terminal or a Command Prompt + and run the following command. + + ``openssl req -new -x509 -days 3652 -nodes -out saml.crt -keyout saml.key`` + +#. Provide information at each prompt. + +Two files, ``saml.crt`` and ``saml.key``, are created in the directory where +you ran the command. + +.. _Add Keys to the LMS Configuration File: + +************************************************** +Add Keys to the LMS Configuration File +************************************************** + +.. note:: Configuration settings added to the ``lms.yml`` file are reset + to their default values when you use Ansible to update edx-platform. + +To configure an Open edX site with your public and private SAML keys, follow +these steps. + +#. Open the ``edx/app/edxapp/lms.yml`` file in your text editor. + +#. In the root of the JSON, add the ``SOCIAL_AUTH_SAML_SP_PUBLIC_CERT`` key + followed by a colon (:), a space, and an empty string where you'll paste the + escaped certificate. + + .. code:: json + + "SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "", + +#. Open the ``saml.crt`` file, copy its entire contents, and then paste them + inside the quotes after the ``SOCIAL_AUTH_SAML_SP_PUBLIC_CERT`` parameter. + Replace all newlines with `\n`. + + .. code:: json + + "SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "-----BEGIN CERTIFICATE-----\nSWP6P/C1ypaYkmS...j9+hjvbBf3szk=\n-----END CERTIFICATE-----\n" + +#. Add the ``SOCIAL_AUTH_SAML_SP_PRIVATE_KEY`` key followed by a colon + (:), a space, and an empty string where you'll paste the escaped key. + + .. code:: json + + "SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "-----BEGIN CERTIFICATE-----\nSWP6P/C1ypaYkmS...j9+hjvbBf3szk=\n-----END CERTIFICATE-----\n" + "SOCIAL_AUTH_SAML_SP_PRIVATE_KEY": "" + +#. Open the ``saml.key`` file, copy its entire contents, and then paste them + inside the quotes after the ``SOCIAL_AUTH_SAML_SP_PRIVATE_KEY`` key. + Replace all newlines with `\n`. + + .. code:: json + + "SOCIAL_AUTH_SAML_SP_PUBLIC_CERT": "-----BEGIN CERTIFICATE-----\nSWP6P/C1ypaYkmS...j9+hjvbBf3szk=\n-----END CERTIFICATE-----\n" + "SOCIAL_AUTH_SAML_SP_PRIVATE_KEY": "-----BEGIN RSA PRIVATE KEY-----\nW1icmlkZN+FtM5h...s/psgLDn38Q==\n-----END RSA PRIVATE KEY-----\n" + +#. Save and close the ``lms.yml`` file. + + +************************************************** +Configure your Open edX Site as a Service Provider +************************************************** + +To configure your Open edX site as a SAML service provider, follow +these steps. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. In the **Third_Party_Auth** section, next to **SAML Configuration** select + **Add**. + + .. note:: If you want to change the configuration of an existing service + provider, next to **SAML Configuration** select **Change**, and then + select **Update** for the provider that you want to configure. + +#. Select **Enabled**. + +#. Enter the following information. + + - **Entity ID**: Enter a URI for the server. To ensure that this value + uniquely identifies your site, the naming convention that edX recommends is + to include the server's domain name. For example, + ``http://saml.mydomain.com/``. + + - **Site**: Specify the site that you are configuring to be a SAML service + provider. There can only be one SAML Service Provider per site. For more + information about Sites in Open edX, see :ref:`Configuring Open edX sites`. + + - **Organization Info**: Use the format in the example that follows to + specify a language and locale code and identifying information for your + installation. + + .. code:: json + + { + "en-US": { + "url": "http://www.mydomain.com", + "displayname": "{Complete Name}", + "name": "{Short Name}" + } + } + + - **Other config str**: Define the security settings for the IdP metadata + files. For more information about the security settings, see the + `Python SAML Toolkit`_. An example follows. + + .. code:: json + + { + "SECURITY_CONFIG": { + "signMetadata": false, + "metadataCacheDuration": "" + } + } + +#. Optionally, you can save your public and private keys in the Django + administration console. Because this procedure saves your credentials in the + database, edX recommends that you use the ``lms.yml`` file instead. + For more information, see :ref:`Add Keys to the LMS Configuration File`. + +#. Select **Save**. You can direct identity providers to + ``{your LMS URL}/auth/saml/metadata.xml`` for your metadata file. + +******************************************************* +Ensure that the SAML Authentication Backend is Loaded +******************************************************* + +By default, SAML is included as an approved data format for identity providers. +The default configuration of the ``/edx/app/edxapp/lms.yml`` file does not +explicitly include the ``THIRD_PARTY_AUTH_BACKENDS`` setting. + +If you have customized this file and added the ``THIRD_PARTY_AUTH_BACKENDS`` +setting to it, you might need to verify that the +``common.djangoapps.third_party_auth.saml.SAMLAuthBackend`` python-social-auth backend class is +specified for it. That backend is required before you can add SAML IdPs. + +To verify that the SAML authentication backend is loaded on a devstack or +fullstack installation, review the ``/edx/app/edxapp/lms.yml`` file. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_advanced_features.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_advanced_features.rst new file mode 100644 index 000000000..63a7708b2 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_advanced_features.rst @@ -0,0 +1,176 @@ +.. _Advanced Third Party Authentication Features: + +############################################ +Advanced Third Party Authentication Features +############################################ + +The Open edX Third Party Authentication feature offers many advanced +configuration options and integration points that can be used to customize the +sign in experience for learners using specific third party providers. None of +the following features are required for a typical installation, but they may be useful. + +********************** +Skip Registration Form +********************** + +When you configure an OAuth2 or SAML provider in the Django admin, there is a +boolean **Skip registration form** option for that provider. Normally, when a +new user signs in with an external provider, the information sent to Open edX is +only used to pre-fill the registration form. When **Skip registration form** is +enabled for a provider, the information sent to Open edX is also used to pre- +fill the registration form, but then the form is automatically submitted before +the user has a chance to see it. If the registration succeeds, the user will +immediately be signed in to their newly created account and can start learning +right away. However, if there is any error, such as no email address was +provided automatically (since email addresses are required) or the email +address of the student conflicts with another existing Open edX user account, +then the pre-filled registration form will still be displayed to the student, +along with an error message. The student can then fix the error and submit the +form to complete the registration process. + + +*********************** +Skip Email Verification +*********************** + +When you configure an OAuth2 or SAML provider in the Django admin, there is a +boolean **Skip email verification** for that provider. Normally, all users are +required to verify their email address by clicking a link in the verification +email that gets automatically sent to the user upon registration. When this +option is selected, Open edX trusts that the email address provided by the +external authentication provider is correct. + +If a user registering with a provider that has this option enabled, and the +user's email address matches the email address that was sent to Open edX by the +external provider, the user's email address will be marked as verified, and no +verification email will be required. (However, the email address sent by the +external provider is only used to pre-fill the registration form, and the user +has a chance to edit the email address on the registration form before creating +their account. If they edit their email address so that it no longer matches +the email address sent by the external provider, the user will still be +required to verify their email address as usual.) + +.. _Hinted Sign In: + +************** +Hinted Sign In +************** + +When you link to Open edX, you can create "hinted links" that prompt the user +to sign in using a specific provider. For example, the following link +represents a typical link to an example course. + +:: + + https://courses.example.com/courses/course-v1:OrganizationX+Course101x+1T2016/courseware/3eddbb5919544c229d34b3175debc6d6/f9900289d2d0474096d20d23a1eeed81/ + +The following link represents a hinted link to the same course. At the end of +the URL, ``?tpa_hint=oa2-google-oauth2`` has been added. + +:: + + https://courses.example.com/courses/course-v1:OrganizationX+Course101x+1T2016/courseware/3eddbb5919544c229d34b3175debc6d6/f9900289d2d0474096d20d23a1eeed81/?tpa_hint=oa2-google-oauth2 + +When users select the typical link, they go to the sign in page. When they +select the hinted link, they receive a "Would you like to sign in using your +Google credentials?" prompt that includes a large button to use Google to sign +in, as well as a small button to use other sign in options. + +The intended use case of this feature is for organizations that wish to provide +a link from an on-premise system (or a course in another LMS like Canvas) to a +course in Open edX. In that case, the organizations will want students to sign +in using the organizations' SAML providers. By using hinted links, the sign in +and/or registration process will be simpler for students, as they won't have to +select a sign in provider or enter a password. + +To create a hinted link for an OAuth2 provider, append +``?tpa_hint=oa2-providername`` to any Open edX URL, where ``providername`` is +the "Backend Name" value from the "Provider Configuration (OAuth)" section of +the Open edX Django admin. + +To create a hinted link for a SAML provider, append ``?tpa_hint=saml-idpslug`` +to any Open edX URL, where ``idpslug`` is the "Idp slug" value from the +"Provider Configuration (SAML IdP)" section of the Open edX Django admin. + +*************** +Auto-enrollment +*************** + +Open edX has a feature that allows instructors, marketing teams, and others to +create links that automatically enroll students who click the link into a +specific course. + +If you send users to ``{LMS base URL}/account/finish_auth`` and include +``course_id``, ``enrollment_action``, and optional ``course_mode`` and +``email_opt_in`` parameters, the system auto-enrolls the user in the +specified course. + +For example, the following URL would auto-enroll the user who clicks this link +into the edX Demo course (that course's ID, +``course-v1:edX+DemoX+Demo_Course``, has been url-encoded as the value of the +``course_id`` parameter). If the user is not signed in, they are auto-enrolled +after they sign in or register. + +:: + + https://courses.example.com/account/finish_auth?course_id=course-v1%3AedX%2BDemoX%2BDemo_Course&enrollment_action=enroll&email_opt_in=false + +You can include the following parameters. + +* ``enrollment_action``: This is required so that the auto-enrollment behavior + is triggered. It must be set to either ``enroll`` (for free courses) or + ``add_to_cart`` (for paid courses). If ``add_to_cart`` is used, learners + are directed to the e-commerce basket page rather than being instantly + enrolled. + +* ``course_id``: This is required. The ID of the course to enroll the user in, + or add to cart, etc. The value must be URL-encoded. + +* ``course_mode``: One of ``audit``, ``honor``, ``verified``, etc. This + parameter applies only if ``enrollment_action`` is ``enroll``. If + ``course_mode`` is not specified, and the course has more than one mode, + learners are sent to the track selection page, where they can choose which + track of the course to enroll in. If ``honor`` or ``audit`` is specified, + learners are instantly enrolled. If any other mode is specified, learners + are sent to the payment/verification flow. + +* ``email_opt_in``: Can be ``true`` or ``false``. If true, this indicates that + the user has consented to receiving marketing emails from Open edX and the + course partner. + +The auto-enrollment feature can be combined with :ref:`hinted sign in`, if you create a URL such as the following example. + +:: + + https://courses.example.com/account/finish_auth?course_id=course-v1%3AedX%2BDemoX%2BDemo_Course&enrollment_action=enroll&email_opt_in=false&tpa_hint=oa2-facebook + +******************* +Secondary Providers +******************* + +When you configure an OAuth2 or SAML provider in the Django admin, there is a +boolean option to mark the provider as a **Secondary** provider. Normally, +third party sign in providers are displayed on the Open edX sign in and +register pages. However, secondary providers are not displayed directly on the +sign in or register pages. Instead, users see a button that says "Use my +institution/campus credentials". Clicking that will bring up a separate menu +that lists all the secondary providers. + +The intended use case of this feature is to keep the sign in/register page from +being cluttered with too many buttons. + +*************************** +SAML Attribute Requirements +*************************** + +When you integrate Open edX with a SAML provider, you can allow only some users +to sign in based on some criteria. For example, organizations may not want +alumni or guest users to be able to sign in to Open edX using their SAML +provider, even though those users have valid sign in credentials for the +organization. + +Users can be filtered based on ``eduPersonEntitlement`` attributes (supported +out of the box), or other attributes (requires custom code). For details on how +this can be set up, refer to `this edx-code mailing list post +`_. diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_behavior.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_behavior.rst new file mode 100644 index 000000000..e76ce8511 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_behavior.rst @@ -0,0 +1,76 @@ +.. _SSO Behavior: + +############ +SSO Behavior +############ + +The following behavior applies to all three types of provider (OAuth, SAML, and LTI). + +************************ +New Learner Registration +************************ + +* When a user signs in by using single sign on (SSO) for the first time, their + account is not normally created automatically. Instead, the user information + sent by the provider is used to pre-fill the registration form. The user can + then edit any of the information before finalizing the creation of their + account. The user could also cancel the registration process at this point, + and no account would be created for them. + +* The user information that is passed from the external authentication provider + to Open edX varies depending on the provider. For example, Google, Facebook, + a university's SAML provider, and a corporate SAML provider may all provide + different user information. Some providers may pass the user's full name, + first name, last name, username, email address, external user ID, and more. + Other providers may pass only an opaque "user token" that can be used to + permanently and consistently identify that user, but which is not considered + personal information and does not correspond to any other public identifier. + +* After a user submits the registration form, their user account is created and + is automatically "linked" to the external provider. For more information, see + :ref:`Linking Accounts`. + +* When a user creates an account by using SSO, the password field on the + registration form is hidden. User accounts created by using SSO will have a + `random and highly secure password`_ assigned to their account. The user will + not know (or need to know) this password. However, the user can always use + the "reset password" feature to change their password, if they would also + like to be able to use a traditional password-based sign in method. + +.. important:: + No matter which type of sign in method is used, a full and independent Open + edX user account is always created for the new user, with a copy of the + user's information. As a result, if the external provider updates the user's + information (such as name or email address), that information will **not** be + automatically updated in the user's Open edX account. In other words, the use + of the external account as a reference that provides user details is a one- + time event, not an ongoing connection. + +.. _Linking Accounts: + +********************* +Linking Accounts +********************* + +* To be able to sign in by using an external provider such as Google, the + user's Open edX account must be "linked" to that provider. For example, if a + user's account is linked to Google, the user can click the **Login with + Google** button, and will be automatically signed in to their Open edX + account. + +* User accounts can be linked to zero, one, or many external providers. + +* Any provider can be linked or unlinked from an account at any time. + +* If an external provider is used to register a new account, the newly created + account will automatically be linked to that provider. + +* If a user tries to sign in by using an external provider that is not yet + linked to any Open edX account, the user will be given the following options. + + * Sign in to an existing account (using a password), which will then link + the new provider to that existing account. + + * Create a new account. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_eliminating_pii.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_eliminating_pii.rst new file mode 100644 index 000000000..908358990 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_eliminating_pii.rst @@ -0,0 +1,232 @@ +.. _eliminating_pii_third_party_authentication: + +############################################### +Eliminating PII From Third-Party Authentication +############################################### + +Open edX sites and Open edX Edge do not require any personally identifiable +information (PII) about learners during third-party authentication. PII is +information that can be used to reveal an individual's identity, such as a +name. Your identity provider (IdP) service can send only non-personal +identifiers to create Open edX site accounts for learners. If you configure +third-party authentication in this way, the Open edX site never receives PII +from your organization. + +.. contents:: + :local: + :depth: 1 + +.. note:: + The types of information that constitute PII and requirements for handling it + depend on the laws and regulations that apply to your organization. The + information in this documentation is intended to explain how Open edX sites + can be configured to handle learner data. You cannot rely on this + documentation as a source of legal guidance. + +************************************************************ +Creating Open edX Learner Accounts Without Transmitting PII +************************************************************ + +After you have configured a third-party authentication profile for an Open edX +site, the site's sign-in page will display a button for users to access your +IdP service. Learners will access your IdP service and authenticate using their +organization credentials. Your IdP service will direct learners back to the +Open edX site's sign-in screen with an authentication token. + +The IdP authentication token includes an identifying string for a learner. This +identifier serves as a link between the identifying information that your +organization maintains for a learner and the Open edX account for that learner. +The identifying string does not need to include any PII for the learner. The +identifying string is sometimes referred to as an opaque identifier because it +does not make the identity of the learner visible. + +When a learner uses third-party authentication to sign in to an Open edX site +for the first time, the Open edX site creates a learner account. The new Open +edX learner account is permanently associated with the identifying string +included in the IdP authentication token. Learners will be prompted to create +profiles by entering Open edX usernames, email addresses, and other information +in their accounts. Learners can take steps to minimize the PII in their +profiles. For more information, see +:ref:`creating_learner_accounts_without_pii`. + +The following diagram shows how an IdP can direct a learner to an Open edX site to +create a learner account, without transmitting any PII. + +.. image:: ../../Images/tpa-idp-create-non-personal-account.png + :width: 900 + :alt: A diagram showing how an identity provider (IdP) service can create a + learner account on an Open edX site without transmitting any personally + identifying information (PII). + +You can download a report containing grades for all learners in the Open edX +courses that you run. The report includes the Open edX username for each +learner enrolled in the course, but the usernames may not correspond to learner +records that your organization maintains. If you need to match the scores for +Open edX site learners to the learner records that your organization maintains, +you can use the third- party authentication ID mapping REST API to retrieve the +user ID SAML attribute and matching Open edX username for a learner. For more +information about grade reports for Open edX courses that you run, see +:ref:`Access_grades`. + +.. Organizations may be able to access learner information in other ways. Make +.. the paragraph above more general when we know of those other methods. + +The following diagram shows how an organization that uses third-party +authentication can match non-personally identifying Open edX learner usernames +with the records that the organization holds for those learners. + +.. image:: ../../Images/tpa-institution-associate-edx-id-with-personal-id.png + :width: 900 + :alt: A diagram showing how an organization that uses third-party + authentication can match non-personally identifying Open edX learner + usernames with the records that the organization holds for those + learners. + +.. TODO: Add documentation for the third-party authentication ID mapping API. + +.. _creating_learner_accounts_without_pii: + +********************************** +Minimizing PII in Account Profiles +********************************** + +When your IdP directs a learner to an Open edX site for the first time, the +learner enters information to create an Open edX site account. The basic +information required for an Open edX site account is an email address, full +name, public username, password, and country. Learners may also provide +additional personal details such as gender, year of birth, and educational +background. While course teams have access to full registration information +for learners enrolled in their courses, only public usernames are used to +identify learners in course discussions and other public-facing course +interactions. + +To minimize PII stored on an Open edX site, learners can limit the information +in their Open edX account profiles to the basic information required for an +Open edX site account. Additionally, learners may use random or nondescript +public usernames and create non-identifying email addresses to receive course +updates. + +If you want to avoid transmitting PII for the Open edX learner accounts that +use third-party authentication, you should not include personally identifying +information in the authentication token. The only piece of information that is +required in the authentication token is the user ID, which should not be +personally identifying. + +For more information about configuring the information in a third-party +authentication token, see :ref:`Configuration Options for SAML Providers`. + +**************************** +PII Considerations with SAML +**************************** + +Organizations that use SAML to integrate their IdPs with Open edX need to +understand what personal information is provided to Open edX when users sign in +using SAML. + +When a user uses SAML or Shibboleth to sign in to Open edX, the IdP +authoritatively asserts pieces of information about the user. + +Each piece of information is called a SAML attribute. Each attribute has a +name and a formal identifier that is called an object identifier (`OID`_) +uniform resource name (`URN`_). + +The following table lists some common attributes. + +.. list-table:: + :widths: 25 30 45 + + * - Name + - OID URN + - Example Value + * - User ID + - ``urn:oid:0.9.2342.19200300.100.1.1`` + - 123456789 + * - Full Name + - ``urn:oid:2.5.4.3`` + - Donna Noble + * - First Name + - ``urn:oid:2.5.4.42`` + - Donna + * - Last Name + - ``urn:oid:2.5.4.4`` + - Noble + * - Email + - ``urn:oid:0.9.2342.19200300.100.1.3`` + - dnoble@school.edu + * - eduPersonPrincipalName + - ``urn:oid:1.3.6.1.4.1.5923.1.1.1.6`` + - dnoble@school.edu + * - eduPersonEntitlement + - ``urn:oid:1.3.6.1.4.1.5923.1.1.1.7`` + - urn:mace:school.edu:confocalMicroscope + +For more information about ``eduPersonPrincipalName`` and +``eduPersonEntitlement``, see `eduPersonPrincipalName`_ and +`eduPersonEntitlement`_ on the `eduPerson Object Class Specification`_ page. + +When a new user uses SAML to sign in to Open edX, the IdP sends information +about the user to Open edX in the form of these attributes. These attributes +can be used to pre-fill the registration form. + +For example, when a user signs in, their server may provide the following +information. + +.. code-block:: python + + "urn:oid:0.9.2342.19200300.100.1.1: 123, urn:oid:2.5.4.3: John Smith, + urn:oid:0.9.2342.19200300.100.1.3: jsmith@school.edu" + +Open edX saves the user ID because it is required to match future sign-in +attempts to the correct user account. The full name (``John Smith``) and email +(``jsmith@school.edu``) is pre-filled on the registration form, but if the user +edits those, Open edX saves only the new changed version. (For example, if the +user changes the email to ``jsmith@example.com``, Open edX would record the +user's email as ``jsmith@example.com`` and would not have any record of the +``jsmith@school.edu`` address.) + + +By default, Open edX expects the standard **User ID** field +(``urn:oid:0.9.2342.19200300.100.1.1``) and uses that as the unique external +ID. Open edX can accept any set of attributes that a SAML IdP sends, as long as +one of the attributes is a unique, permanent identifier for the user being +authenticated. The URN or OID of the unique identifier must be specified in the +Open edX "Provider Configuration (SAML IdPs)" profile for the organization +(part of the Django administration console) in the **User ID Attribute** +field. + +If you want to configure Open edX to always store all of the attributes that +the external IdP sends for each user, you can enable that with a +setting, as follows. + +#. Sign in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. Go to the **SAML Configuration** page, and then select **Add SAML + Configuration**. (Do not go to the **SAML Provider Configuration** page.) + +#. In the **Other Config Str** section, add the following code. + + .. code-block:: none + + "EXTRA_DATA": [ "attributes" ] + +This setting causes all the attributes to be saved in the +``social_auth_usersocialauth`` table's ``extra_data`` column for every new SAML +user. This data is only accessible by accessing the database directly or by +going to the **User social auths** page of the Open edX LMS Django +administration console. + +For organizations that want to avoid sending any personally identifiable +information to Open edX during the SAML sign in or registration process, we +recommend that the organization configure their SAML IdP to only send a single +attribute: **a unique, permanent, opaque user identifier**. This should be a +value that uniquely identifies any learner or staff member, but is different +from their organization ID or any other identifier they may have. + +For reporting and analytics purposes when using an opaque user identifier, the +organization can use the :ref:`Third Party Auth ID Mapping API` to convert Open +edX user IDs found in reports or analytics back to these opaque organization +user identifiers. Organization partners can then convert each opaque user +identifier back to the official learner ID. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/index.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/index.rst new file mode 100644 index 000000000..1635de489 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/index.rst @@ -0,0 +1,47 @@ +.. _Integrate TPA in Open edX: + +################################################## +Integrating Third Party Authentication in Open edX +################################################## + +For the Open edX platform, you complete two steps to integrate third party +authentication. + +#. Enable the third party authentication feature. +#. Set up a provider. + +.. _Enable the Third Party Authentication Feature: + +*********************************************** +Enable the Third Party Authentication Feature +*********************************************** + +By default, third party authentication is not enabled on Open edX +installations. To enable this feature, follow these steps. + +#. In the ``edx/app/edxapp/lms.yml`` file, edit the file so that it + includes the following line in the features section. + + .. code-block:: none + + "FEATURES" : { + ... + "ENABLE_COMBINED_LOGIN_REGISTRATION": true, + "ENABLE_THIRD_PARTY_AUTH": true + } + +#. Save the ``edx/app/edxapp/lms.yml`` file. + +*********************************************** +Set Up a Third Party Authentication Provider +*********************************************** + +You can set up an OAuth or SAML provider. For information about the differences +between the two providers, see :ref:`Supported Identity Providers`. + +.. toctree:: + :maxdepth: 1 + + tpa_oauth + tpa_SAML_IdP + diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/tpa_SAML_IdP.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/tpa_SAML_IdP.rst new file mode 100644 index 000000000..8796cc573 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/tpa_SAML_IdP.rst @@ -0,0 +1,180 @@ +.. _Integrating with a SAML Identity Provider: + +########################################## +Integrating with a SAML Identity Provider +########################################## + +You can integrate your Open edX site with federated identity solutions +that use the Security Assertion Markup Language, version 2.0 (SAML 2.0) +standard. An example is Shibboleth, a single sign on system that is used by +many educational institutions. + +.. contents:: + :local: + :depth: 1 + +****************** +Exchange Metadata +****************** + +SAML metadata is an XML file that contains the information necessary for secure +interactions between identity providers and security providers. You send the +URL of your metadata file, created when you :ref:`configured your Open edX site +as a SAML service provider`, to each identity provider that you want to add. Similarly, you +obtain the metadata URLs from identity providers before you add and enable them +for your installation. + +******************************************* +Add and Enable a SAML Identity Provider +******************************************* + +To add and enable a SAML 2.0 identity provider, follow these steps. + +#. Log in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. In the **Third_Party_Auth** section, next to **Provider Configuration + (SAML IdPs)** select **Add**. + + .. note:: If you want to change the configuration of an existing provider, + next to **Provider Configuration (SAML IdPs)** select **Change**, and then + select **Update** for the provider that you want to configure. + +#. Enter the following information for the provider. + + - **Icon class**: Specifies a `Font Awesome`_ image for the button that + users will select to access the sign in page for this IdP. The **fa-sign- + in** icon is used by default. For university or institutional providers, a + suggested alternative is **fa-university**. + + - **Name**: The name of the IdP as you want it to appear on the sign in + page. + + - **Secondary**: Select this option to include the IdP in an intermediary + list of providers that users access from a **Use my institution/campus + credentials** button on the sign in page. + + - **Backend name**: The default, **tpa-saml**, is optimized for use with + Open edX and works with most SAML providers. Select a different option + only if you have added a custom backend that provides additional + functionality. + + - **Site**: Select the site that you are configuring to use this IdP. Each + IdP can only belong to one site at a time. For more information about + sites in Open edX, see :ref:`Configuring Open edX sites`. + + - **IdP slug**: A short, unique name to identify this IdP in the URL. The + slug becomes part of a URL, so the value that you enter cannot include + spaces. + + - **Entity ID**: The URI that identifies the IdP. This ID must match the + value specified in the metadata XML file. + + - **Metadata source**: The URL of the XML file that contains this provider's + metadata. + +#. Specify your selections for any of the other, optional configuration + options. For more information about these options, see :ref:`Configuration + Options for SAML Providers`. + +#. When you are ready to enable the provider, select **Enabled** at the top of + the page. Alternatively, save your configuration settings and enable the + provider at another time. + +#. Select **Save** or one of the other save options at the bottom of the page. + +Next, you can :ref:`test an enabled provider`. + +.. _Configuration Options for SAML Providers: + +************************************************* +Configure the SAML Identity Provider +************************************************* + +To customize the registration process for IdP, you make selections for these +optional fields on the **Add Provider Configuration (SAML IdP)** page. + +* **Skip Registration Form**: If you select this option, users are not asked to + confirm the user account data supplied for them by the IdP (name, email + address, and so on). Select this option only for providers that are known to + provide accurate user information. + + By default, users review a registration form with the supplied account + details. + +* **Skip Email Verification**: If you select this option, users are not + required to confirm their email addresses, and their accounts are activated + immediately upon registration. + + By default, users receive an email message and must select a link in that + message to activate their user accounts. + +* **User ID Attribute**: Required. This value is used to associate the user's + edX account with the campus account. It is not displayed to users. + + By default, uses ``userid``, ``urn:oid:0.9.2342.19200300.100.1.1``. + +* Optional user attributes: You can indicate specific URN values for the + following user attributes. + + By default, the registration form includes all of the following attributes if + they are sent by the IdP. + + * **Full Name Attribute**: ``commonName``, ``urn:oid:2.5.4.3`` + * **First Name Attribute**: ``givenName``, ``urn:oid:2.5.4.42`` + * **Last Name Attribute**: ``surname``, ``urn:oid:2.5.4.4`` + * **Username Hint Attribute**: ``userid``, + ``urn:oid:0.9.2342.19200300.100.1.1`` + * **Email Attribute**: ``mail``, ``urn:oid:0.9.2342.19200300.100.1.3`` + + If the identity provider sends a value that you do not want to be included on + the registration form, you can enter a value such as "DISABLED" or + "IGNORE" in that field. + +.. _Test an Enabled SAML Provider: + +******************************************* +Test an Enabled SAML Provider +******************************************* + +To verify the sign in process for an IdP that you have enabled, follow these +steps. + +#. On the Django administration console, in the **Third_Party_Auth** section, + select **Provider Configuration (SAML IdPs)**. + +#. Check the icon in the **Metadata ready** column for the IdP. After the + provider's metadata is fetched successfully from the URL that you provided + as the metadata source, a check mark in a green circle appears and the + provider is ready for use immediately. + + You might need to wait 30-60 seconds for the task to complete, and then + refresh this page. + + If the check mark does not appear, make sure that celery is configured + correctly and is running. You can also manually trigger an update by running + the management command ``./manage.py lms saml --pull --settings=production`` on + fullstack or ``./manage.py lms saml --pull --settings=devstack`` on + devstack. + +#. For additional information about the data fetched from the IdP, on the + Django administration console select **SAML Provider Data**, and then select + the provider. The page that opens reports data fetched from the metadata + source URL and the date and time it was fetched. + +#. To verify that users can use the IdP for sign in, go to the sign in page for + your LMS. The page should include the institutional sign in button. + + .. image:: ../../../Images/tpa_signin.png + :alt: Screen shot of an LMS sign in page with a button labeled "Use my + institutional/campus credentials" circled at the bottom. + +#. Select **Use my institutional/campus credentials**. The list of providers + that appears should include the IdP that you enabled. + + .. image:: ../../../Images/tpa_inst_list.png + :alt: Screen shot of the list of enabled IdPs. Each IdP name is linked to + the sign in page for the corresponding authentication system. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/tpa_oauth.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/tpa_oauth.rst new file mode 100644 index 000000000..9e8a1778d --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_integrate_open/tpa_oauth.rst @@ -0,0 +1,474 @@ +.. _Integrating with an OAuth2 Identity Provider: + +############################################### +Integrating with an OAuth2 Identity Provider +############################################### + +Open edX has specific instructions for Google, Facebook, LinkedIn, and Azure +Active Directory. For more information about how to set up one or more of these +integrations, see :ref:`Common OAuth2 Providers`. + +The system also supports integrations with alternative OAuth2 providers. For +more information, see :ref:`Additional Providers`. + +.. _Common OAuth2 Providers: + +**************************** +Common OAuth2 Providers +**************************** + +Integrating with the most common OAuth2 IdPs has several steps. + +#. :ref:`Register the Open edX instance with the provider`. +#. :ref:`Configure Open edX`. +#. :ref:`Add the provider configuration`. + + +.. _Register the Open edX Instance: + +============================== +Register the Open edX Instance +============================== + +The most common OAuth2 providers are Google, Facebook, LinkedIn, and Azure +Active Directory. + +.. contents:: + :local: + :depth: 1 + +Register the Open edX Instance with Google +****************************************** + +The following instructions describe how to configure Google as a third party +authentication provider so that users can use Google accounts (which includes +Google Apps accounts) to sign in. These are based on the official Google +instructions. + +#. Obtain credentials to access the Google API. To do this, follow the + `official Google instructions`_ to go to the `Google Developers Console`_, + create a new project, and enable the Google+ API service. + +#. In the Google Developers Console, select **API Manager**, and then select + **OAuth Consent Screen**. + +#. For **Product name shown to users** enter the name of your Open edX instance + (for example, "Example Academy Online"). + +#. Select **Save**. + +#. Select the **Credentials** tab, select **Create credentials**, and then + select **OAuth client ID**. + + * For **Application type**, select **Web application**. + * Leave the **Authorized JavaScript origins** field blank. + * For **Authorized redirect URIs**, enter ``/auth/complete/google-oauth2/``. For example, for devstack, enter + ``http://localhost:8000/auth/complete/google-oauth2/``. + * Select **Create** to finish creating the credentials. + +#. After you obtain the credentials, note the client ID and the client secret. + +Register the Open edX Instance with Facebook +******************************************** + +To create the app in the Facebook developer portal, follow these steps. + +#. Sign in to Facebook, then go to the `Facebook for Developers`_ page. + +#. Select **Add a New App**, and then select **Website**. + +#. Enter a name for the app, and then select **Create New Facebook App ID**. + +#. Enter your information in the rest of the fields in the app creation + process. + +#. Under **Quick Start for Website**, select **Skip Quick Start**. + + You are now at the developer console page for the new Facebook app. + +#. Select **Settings**, and note the **App ID** and **App Secret**. + +#. On the **Settings** page, select **Add Platform**, and then select + **Website**. + +#. For **Site URL**, enter the URL of your Open edX instance (for example, + ```` for devstack). + +#. In the **App Domains** field, enter the domain name from this URL (for + example, ``localhost``). + +#. Select **Save Changes**. + +#. Under **Products** -> **Facebook Login** -> **Settings** -> + **Authorized redirect URIs**, enter ``/auth/complete/facebook/``. For example, for devstack, enter + ``http://localhost:8000/auth/complete/facebook/``. + +#. Select **Save Changes**. + +Register the Open edX Instance with LinkedIn +******************************************** + +To create the LinkedIn app, follow these steps. + +#. Go to the `LinkedIn Developers`_ page. + +#. Click **Create Application**, enter your information in the form, and then + submit the form. + +#. On the page that opens with information about the app, note the **Client + ID** and **Client Secret**. + +#. In the **OAuth 2.0** section, for **Authorized Redirect URL**, enter ``/auth/complete/linkedin-oauth2/``. For example, for + devstack, enter ``http://localhost:8000/auth/complete/linkedin-oauth2/``. + +#. Select **Update** to save your information. + +Register the Open edX Instance with Azure Active Directory +********************************************************** + +You can use Azure Active Directory to allow users with Microsoft Office 365 +Business accounts to sign in to Open edX. Note that this feature currently does +not work with other types of Microsoft accounts (such as "@live.com" or +"@hotmail.com" accounts). + +#. If you do not have a Microsoft account, create one on the `Microsoft sign in`_ page. + +#. If you do not have an Azure subscription, create one on the `Azure account + creation`_ page. + + .. note:: + You must enter a credit card on this page, but if you do not create any + virtual machines or other services besides Azure AD, you will not be + charged. + +#. Go to the `Azure sign in`_ page. + +#. Click **New**, locate **Active Directory**, and then select **Create**. + +#. Enter a name, domain name, and country. + +#. Create a new application. + + #. Find the new Active Directory in the portal, select **Applications**, + select **Add**, and then select **Add an application my organization is + developing**. + + #. Enter a name for the app, and then select **Web Application**. + + #. For **Sign-on URL**, enter ``/auth/complete/azuread-oauth2/``. + For example, you might enter + ``http://localhost:8000/auth/complete/azuread-oauth2/``. + + #. For **App ID URL**, enter ``/sign in``. For example, you might + enter ``http://localhost:8000/sign in``. + + #. Finish creating the new app. + +#. In the portal, locate your Azure AD application, click **Configure**, and + then locate and make a note of the client ID. For example, the client ID may + be ``fe3c3868-0faa-44ee-a1bf-1110aeab1a65``. + +#. In the **Keys** section, select a two-year duration, and then select + **Save** to create a secret key. Note the value of the key. For example, the + key-value may be ``abcdef12341yHlmOrR8D3vlV1cD2VtL7k9xk9DSB8vw=``. + +#. In the **Permissions to other applications** section, locate the **Delegated + Permissions** option for Windows Azure Active Directory, and then select + **Sign in and read user profile**. + +#. Verify the Azure AD domain name. To do this, follow these steps. + + #. In the portal, locate the new Active Directory. + + #. Select **Domains**, select **Add**, and then add the root domain you want + to use (for example, ``edx.org``). Make sure that you add the root domain + first, and then follow the TXT record verification process. + + #. (optional) After the domain has been verified, add subdomains (for + example, ``courses.edx.org``). Subdomains also request verification, but + do not need it. + +#. In the Active Directory, select **Applications**, and then select the + application that you created. + +#. Enable **multi-tenant** support. + + +.. _OAuth2 Configure Open edX: + +====================== +Configure Open edX +====================== + +Configuring Open edX is very similar for Google, Facebook, LinkedIn, and Azure. + +#. In the ``lms.yml`` file, change the value of ``FEATURES`` > + ``ENABLE_THIRD_PARTY_AUTH`` to ``true`` (it is ``false`` by default). + +#. If necessary, make sure that the correct backend is specified. + + * If you are using Google, Facebook, LinkedIn, or Active Directory, open the + ``lms.yml`` file and look for the ``THIRD_PARTY_AUTH_BACKENDS`` list. + By default, the file does not contain this list. + + If the ``lms.yml`` file does not contain the + ``THIRD_PARTY_AUTH_BACKENDS`` list, you do not have to complete any + additional steps. + + If the ``lms.yml`` file contains the ``THIRD_PARTY_AUTH_BACKENDS`` + list, add the backend for the applicable IdP to the list. + + * For Google, add ``"social_core.backends.google.GoogleOAuth2"``. + + * For Facebook, add ``"social_core.backends.facebook.FacebookOAuth2"``. + + * For LinkedIn, add ``"social_core.backends.linkedin.LinkedinOAuth2"``. + + * For Azure Active Directory, add + ``"social_core.backends.azuread.AzureADOAuth2"``. + + * If you are using a custom backend, add the applicable OAuth2 provider to + the ``THIRD_PARTY_AUTH_BACKENDS`` list in the ``lms.yml`` file. If + the file does not contain the ``THIRD_PARTY_AUTH_BACKENDS`` list, create + the list, and then add the OAuth2 provider. + + For more information, see the `AWS template file`_ file in GitHub. + +#. In the ``lms.yml`` file, add the client secret. To do this, create the + ``SOCIAL_AUTH_OAUTH_SECRETS`` key if the key does not already exist, and + then add the appropriate value for your IdP. + + .. note:: + If you are using Ansible, set the ``EDXAPP_SOCIAL_AUTH_OAUTH_SECRETS`` + variable. + + * For Google, add the following value. + + .. code-block:: none + + "SOCIAL_AUTH_OAUTH_SECRETS": { "google-oauth2": + "abcdef123456789101112131" } + + * For Facebook, add the following value. + + .. code-block:: none + + "SOCIAL_AUTH_OAUTH_SECRETS": { + "facebook": "98765432181bbe3a2596efa8ba7abcde" + } + + * For LinkedIn, add the following value. + + .. code-block:: none + + "SOCIAL_AUTH_OAUTH_SECRETS": { "linkedin-oauth2": "4D3Cb2aB1C0dEFGH" } + + * For Azure, add the following value. + + .. code-block:: none + + "SOCIAL_AUTH_OAUTH_SECRETS": { "azuread-oauth2": + "abcdef12341yHlmOrR8D3vlV1cD2VtL7k9xk9DSB8vw=" } + +#. Restart the LMS server so that it will use the new settings. + +.. _Add the Provider Configuration: + +============================== +Add the Provider Configuration +============================== + +#. Go to ``/admin/third_party_auth/oauth2providerconfig/``. For + example, on devstack, go to + ``http://localhost:8000/admin/third_party_auth/oauth2providerconfig/``. + +#. Select **Add Provider Configuration (OAuth)**. + +#. Make sure that **Enabled** is selected. + +#. Make sure that **Visible** is selected. + +#. For **Icon Class**, enter the appropriate value. + + * For Google, enter ``fa-google-plus``. + + * For Facebook, enter ``fa-facebook``. + + * For LinkedIn, enter ``fa-linkedin``. + + * For Azure, leave the field blank. + +#. For **Name**, enter the appropriate value. + + * For Google, enter ``Google``. + + * For Facebook, enter ``Facebook``. + + * For LinkedIn, enter ``LinkedIn``. + + * For Azure, enter ``Microsoft``. + +#. For **Backend Name**, select the appropriate value. + + * For Google, select **google-oauth2**. + + * For Facebook, select **facebook**. + + * For LinkedIn, select **linkedin-oauth2**. + + * For Azure, select **azuread-oauth2**. + + .. note:: + If the value does not appear in the list, either the + ``ENABLE_THIRD_PARTY_AUTH`` setting or the ``THIRD_PARTY_AUTH_BACKENDS`` + setting is not configured correctly. + +#. For **Client ID**, enter the client ID that you noted earlier. + +#. Leave **Client Secret** blank. Open edX sets the secret through + ``lms.yml``, which is more secure. + +#. (Optional) If you want Facebook or LinkedIn to provide the user's email + address during registration, enter the following code into **Other + settings**. + + For Facebook, use this code. + + .. code-block:: none + + { + "SCOPE": ["email"], + "PROFILE_EXTRA_PARAMS": { + "fields": "id, name, email" + } + } + + For LinkedIn, use this code. + + .. code-block:: none + + { "SCOPE": ["r_basicprofile", "r_emailaddress"], "FIELD_SELECTORS": + ["email-address"] } + + +#. Select **Save**. + +Users who have an account with the IdP that you have configured can now sign +in. + +.. note:: + + For Google only, if you see the following error message, the + ``SOCIAL_AUTH_OAUTH_SECRETS`` setting is not correct. + + ``'unicode' object has no attribute 'get'`` + + To resolve this problem, make sure that this setting does not appear multiple + times in the ``lms.yml`` file. + +.. _Additional Providers: + +************************************** +Additional OAuth2 Providers (Advanced) +************************************** + +You can add any other third party authentication provider that supports the +OAuth2 standard to the Open edX platform. To do this, follow these steps. + +.. note:: + OAuth1 providers are also supported and can be configured using these same + steps. However, OAuth2 is preferred over OAuth1 wherever possible. + +#. In ``lms.yml``, change the value of ``FEATURES`` > + ``ENABLE_THIRD_PARTY_AUTH`` to ``true`` (it is ``false`` by default). + +#. Install the python-social-auth authentication backend specific to + that provider, and determine the python module path of the backend. + + * If the provider is a `python-social-auth supported backend`_, the backend + is already installed. + + To determine the python module path of the backend, locate the backend in + the `list of python-social-auth backends`_, open the file for the backend, + and locate the name of the class. The python module path is of the format + ``social_core.backends..``. + + For example, for GitHub, the file is ``github.py`` and the class in that + file is ``GithubOAuth2``. The backend module path is therefore + ``social_core.backends.github.GithubOAuth2``. + + * If the provider is not a python-social-auth supported backend, you must + create a new Python package that includes the code required to implement + the backend. Your python package must contain a module with a class that + subclasses ``social_core.backends.oauth.BaseOAuth2``. For more information, see + the `python-social-auth documentation`_, or see the code of the fully + supported backends (such as Google or Facebook) for examples. + +#. Enable the python-social-auth authentication backend specific to that + provider: + + #. In the ``THIRD_PARTY_AUTH_BACKENDS`` setting in ``lms.yml``, add the + full path of the module to the list. + + #. (optional) Set the value of ``THIRD_PARTY_AUTH_BACKENDS`` to match `the + default value in the aws.py file`_, and then add any additional backends + you need. + +#. Obtain a client ID and client secret from the provider. + +#. Add the client secret to ``lms.yml``. To do this, create a new key + called ``SOCIAL_AUTH_OAUTH_SECRETS`` if it doesn't already exist, and then + add the backend name to that key as follows. + + .. code-block:: none + + "SOCIAL_AUTH_OAUTH_SECRETS": { "backend-name": "secret" } + + If you are using Ansible, the variable to set is called + ``EDXAPP_SOCIAL_AUTH_OAUTH_SECRETS``. + +#. Restart the LMS server so that it will use the new settings. + +#. Go to ``/admin/third_party_auth/oauth2providerconfig/``. For + example, on devstack, go to + ``http://localhost:8000/admin/third_party_auth/oauth2providerconfig/``. + +#. Select **Add Provider Configuration (OAuth)**. + +#. Make sure that **Enabled** is selected. + +#. Make sure that **Visible** is selected. + +#. For **Icon Class**, select one of the following options. + + * Use a generic icon by entering ``fa-sign-in``. + + * Use a relevant Font Awesome icon. + + * Upload an SVG icon using the **Icon Image** field. + +#. For **Name**, enter the name of the provider. + +#. For **Site**, choose the site which you want to apply the provider config to, + if there are multiple site configurations. + +#. For **Backend Name**, select the backend name from the list. (If it does not + appear in the list, either the ``ENABLE_THIRD_PARTY_AUTH`` setting or the + ``THIRD_PARTY_AUTH_BACKENDS`` setting is not configured correctly.) + +#. For **Client ID**, enter the client ID that you noted earlier. + +#. Leave **Client Secret** blank. Open edX sets the secret through + ``lms.yml``, which is more secure. + +#. Select **Save**. + +Users can now sign in using this OAuth2 provider. + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_providers.rst b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_providers.rst new file mode 100644 index 000000000..47c8fbad4 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/tpa/tpa_providers.rst @@ -0,0 +1,83 @@ +.. _Supported Identity Providers: + +####################################### +Supported Identity Providers +####################################### + +In an exchange of authentication and authorization data, an identity provider +securely asserts the identity and access rights of a set of users. Your Open +edX site is the service provider that allows the users access on the basis of credentials sent by an identity provider. + +For example, your Open edX site hosts the courses of three different +organizations. When you configure the Open edX site to be a service provider, +and configure each of the three organizations to be identity providers, you +permit learners who have valid user credentials at any of those organizations +to access the Open edX site. + +You can enable third party authentication between your Open edX site and many +types of identity providers. The Open edX platform provides support for +three types of identity providers. + +**************************** +Supported Identity Providers +**************************** + +The Open edX platform has integrated support for the following providers. + +* **OAuth** based providers (OAuth2 and the older OAuth v1). Google, Facebook, + LinkedIn, and Azure Active Directory are available by default. Any other + `OAuth backends supported by python-social-auth v0.2.12`_ can be enabled by + changing a configuration setting. People in the Open edX community sometimes + use “third party auth” to refer to Google or Facebook integration. Single + sign on, or “SSO”, and “third party auth” are largely interchangeable terms + for the purposes of this document. + +* **Security Assertion Markup Language (SAML) version 2.0**, or Shibboleth. + SAML is an SSO standard mostly used by universities and corporations. + Shibboleth is the name of a particular implementation of SAML, commonly used + by higher education institutions. People in the Open edX community sometimes + use “SSO” to refer to SAML or Shibboleth. “SSO” and “Third Party Auth” are + largely interchangeable terms for the purposes of this doc. For more + information, see :ref:`Integrating with a SAML Identity Provider`. + +* **LTI**. Users can use Learning Tools Interoperability® (LTI®) to + authenticate. + +****************************************** +Provisionally Supported Identity Providers +****************************************** + +The Open edX platform also includes limited support for the following SSO +providers. + +* OpenID +* Apache-hosted Shibboleth +* SSL client certificates +* Central Authentication Service (CAS) + +These providers are part of the external_auth app, tend to be older and less +robustly tested, and have a much more limited feature set. These providers are +included in the source code but are not officially supported. + +****************************** +Integrating Identity Providers +****************************** + +Regardless of the standard that the identity provider you want to integrate +with uses, you begin by :ref:`enabling the third party authentication +feature` for your site. + +For example, your Open edX site hosts the courses of three different +organizations. When you configure the Open edX site to be a service provider, +and configure each of the three organizations to be identity providers, you +permit learners who have valid user credentials at any of those organizations +to access the Open edX site. + +If you are using :ref:`edX as an LTI tool provider` to a external learning management system +or application, you can set up an authentication workflow between your Open +edX site and the system that is the LTI tool consumer. For more information, +see :ref:`Options for LTI Authentication and User Provisioning` and +:ref:`Configuring Open edX for LTI Authentication`. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/transcripts.rst b/source/site_ops/install_configure_run_guide/configuration/transcripts.rst new file mode 100644 index 000000000..47a84efc6 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/transcripts.rst @@ -0,0 +1,40 @@ +.. _Configure Transcripts: + +#################################### +Configuring Transcript Behavior +#################################### + +As a best practice, transcripts should always be provided, so that course +videos meet accessibility requirements. Video transcripts are displayed in the +language selected by the learner in the video player if they are available in +that language. Otherwise, by default video transcripts fall back to an English +language transcript. In cases where no transcript is available, you can +configure Open edX so that the video player does not display the caption and +transcript buttons. + +You can configure the default transcript behavior using the +``FALLBACK_TO_ENGLISH_TRANSCRIPTS`` feature flag. By default, this feature +flag is set to ``TRUE``. If you set it to ``FALSE``, then the video transcript +will not fall back to an English language transcript and if no transcript is +available, the caption and transcript buttons are not displayed in the video +player. + +*************************************** +Configuring the Transcript Feature Flag +*************************************** + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +To set the ``FALLBACK_TO_ENGLISH_TRANSCRIPTS`` feature flag, you modify the +``lms.yml`` and ``studio.yml`` files, which are located one level above +the ``edx-platform`` directory. + +#. In the ``lms.yml`` and ``studio.yml`` files, in the ``FEATURES`` + dictionary, change the value of ``FALLBACK_TO_ENGLISH_TRANSCRIPTS`` to + ``FALSE``. + +#. Save the ``lms.yml`` and ``studio.yml`` files. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/updating_platform.rst b/source/site_ops/install_configure_run_guide/configuration/updating_platform.rst new file mode 100644 index 000000000..3374a21d2 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/updating_platform.rst @@ -0,0 +1,18 @@ +.. _Guidelines for Updating the Open edX Platform: + +###################################################### +Guidelines for Updating the Open edX Platform +###################################################### + +When you update the Open edX Platform, you should not change configuration +files on a running server. Doing so can result in unpredictable problems. + +If you need to change settings on a running server, take the following steps. + +#. Provision a new server that matches the running server. +#. Make configuration changes on the new server. +#. Start the new server. +#. Reroute traffic from the old server to the new server. +#. Decommission the old server. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/configuration/youtube_api.rst b/source/site_ops/install_configure_run_guide/configuration/youtube_api.rst new file mode 100644 index 000000000..7b5f52663 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/configuration/youtube_api.rst @@ -0,0 +1,125 @@ +.. _YouTube_API: + +############################### +Setting Up the YouTube API Key +############################### + +This topic describes how to set the YouTube API key for your instance of +Open edX. + +.. contents:: + :local: + :depth: 1 + +********* +Overview +********* + +If you intend for courses on your Open edX instance to include videos that are +hosted on YouTube, you must get a YouTube API key and set the key in the +Open edX Platform. + +The Open edX Platform uses the `YouTube Data API v3`_, which requires that +the application uses an API key. + +************************* +Get a YouTube API Key +************************* + +To get the YouTube API key, follow YouTube's `instructions for obtaining +authorization credentials`_. YouTube provides two different options for API +keys: server keys or browser keys. You should use a **browser key** for +Open edX. + +.. Note:: + Before proceeding, review :ref:`Guidelines for Updating the Open edX + Platform`. + +****************************************** +Install the YouTube API Key in Open edX +****************************************** + +After you obtain a YouTube API key, you must install that key into your +Open edX installation. There are two different ways you can do this. + +.. contents:: + :local: + :depth: 1 + +Option 1: Ansible (recommended) +=============================== + +`Ansible`_ is the automation system used for installing and updating Open edX. +If you set your YouTube API key in Ansible's configuration file, then Ansible +will make sure that the YouTube API key remains in place when you update Open +edX. + +To set your YouTube API key in Ansible's configuration file, follow these +steps. + +#. Find the `configuration`_ repository on your Open edX server. If you are + running devstack or fullstack, the directory is + ``/edx/app/edx_ansible/edx_ansible``. + +#. In that repository, open the ``playbooks/roles/edxapp/defaults/main.yml`` + file in a text editor. + +#. Find the line for the YouTube API key. + + ``EDXAPP_YOUTUBE_API_KEY: "PUT_YOUR_API_KEY_HERE"`` + + Replace ``PUT_YOUR_API_KEY_HERE`` with your YouTube API key. Ensure + that the YouTube API key is within by quotation marks. + +#. Save and close the file. + +#. Run Ansible so that it applies your YouTube API key to your Open edX + installation. + + For example, if you are running the Open edX Cypress release, run the + following command. + + .. code-block:: bash + + /edx/bin/update edx-platform named-release/cypress + + +Option 2: JSON files +==================== + +Ansible outputs information to several JSON files used by Open edX. If you +prefer not to edit the Ansible configuration, you can edit these files +directly. + +However, every time you update Open edX, your edits will be overwritten by +Ansible. As a result, we recommend setting your YouTube API key in Ansible's +configuration instead. + +To set your YouTube API key by editing JSON files, complete the following +steps. + +#. Find the `edx-platform`_ repository on your Open edX server. If you are + running devstack or fullstack, the directory is + ``/edx/app/edxapp/edx-platform``. + +#. In the directory *above* your repository, there should be several JSON + files, including ``lms.yml`` and ``studio.yml``. If you are running + devstack or fullstack, the directory is ``/edx/app/edxapp``. + +#. Open the ``lms.yml`` file in your text editor. + +#. Find the line for the YouTube API key. + + ``"YOUTUBE_API_KEY": "PUT_YOUR_API_KEY_HERE",`` + + Replace ``PUT_YOUR_API_KEY_HERE`` with your YouTube API key. Verify + that the YouTube API key is between the quotation marks. + +#. Save and close the file. + +#. Open the ``studio.yml`` file and make the same change. If that line does + not exist in this file, create it. + +#. Save and close the file. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/apple_pay.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/apple_pay.rst new file mode 100644 index 000000000..43fb79a85 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/apple_pay.rst @@ -0,0 +1,47 @@ +Apple Pay +######### + +Apple Pay support is available when you use the CyberSource processor. Apple Pay +allows learners to check out quickly without having to manually fill out the +payment form. If you are not familiar with Apple Pay, take a moment to read the +following documents to understand the user flow and necessary configuration. + +* `Apple Pay JS `_ +* `CyberSource Simple Order API `_ + +Apple Pay is available only to learners using Safari on the following platforms: + +* iOS 10+ on devices with a Secure Element +* macOS 10.12+. The user must have an iPhone, Apple Watch, or a MacBook Pro with + Touch ID that can authorize the payment. + +An exhaustive list of devices that support Apple Pay is available on +`Wikipedia `_. + +.. note:: + + The Apple Pay button is not displayed to users with incompatible hardware + and software. + +Settings +-------- +Apple Pay is configured via the ``PAYMENT_PROCESSOR_CONFIG`` dictionary in settings. The following keys are required. + +.. list-table:: + :header-rows: 1 + + * - Name + - Purpose + * - apple_pay_merchant_identifier + - Merchant identifier created at the `Apple Developer portal`_ + * - apple_pay_country_code + - Two-letter `ISO 3166 country code `_ for your + business/merchant account + * - apple_pay_merchant_id_domain_association + - Domain verification text obtained from the `Apple Developer portal`_ + * - apple_pay_merchant_id_certificate_path + - Filesystem path to the merchant identity certificate (used to authenticate with Apple to start sessions). This + file should be kept in a secure location that is only accessible by administrators and the application' + service user. + +.. _Apple Developer portal: https://developer.apple.com/account/ios/identifier/merchant diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/change_processors.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/change_processors.rst new file mode 100644 index 000000000..659af955a --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/change_processors.rst @@ -0,0 +1,33 @@ +.. _Changing Payment Processors: + +############################# +Changing Payment Processors +############################# + + +Payment processors sometimes experience temporary outages. When these outages +occur, you can use Waffle switches to disable the faulty payment processor or +processors, then re-enable them after the outage is over. + +The names of these switches use prefixes that are the value of the +``PAYMENT_PROCESSOR_SWITCH_PREFIX`` setting. By default, this value is +``payment_processor_active_``. The following table lists valid switches and the +payment processors they control. + +.. list-table:: + :widths: 15 45 10 + :header-rows: 1 + + * - Payment Processor + - Switch Name + - Default Value + * - PayPal + - payment_processor_active_paypal + - True + * - CyberSource + - payment_processor_active_cybersource + - True + +In the unlikely event that all payment processors are disabled, the LMS will +display an informative error message explaining why payment is not currently +possible. diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/gate_ecommerce.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/gate_ecommerce.rst new file mode 100644 index 000000000..b39e9791b --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/gate_ecommerce.rst @@ -0,0 +1,71 @@ +.. _Gating ECommerce Features: + +#################################### +Gating E-Commerce Service Features +#################################### + +You can release new E-Commerce service features and functionality behind a +feature gate. This project uses the `Waffle`_ library for feature gating. + +**************************** +Types of Feature Gates +**************************** + +Waffle supports the following types of feature gates. + +* Flag: This gate allows you to enable a feature for specific users, groups, + users who meet certain criteria (such as authenticated users or staff), or a + certain percentage of visitors. + +* Switch: This gate is a Boolean that turns a feature on or off for all + users. + +* Sample: This gate allows you to define the probability with which a given + feature will be on. + +For more information about creating or updating features and feature gates, see +the `Waffle documentation`_. + +*************** +Feature Gates +*************** + +Waffle offers the following feature gates. + +.. list-table:: + :widths: 35 10 60 + :header-rows: 1 + + * - Name + - Type + - Purpose + * - user_enrollments_on_dashboard + - Switch + - Display a user's current enrollments on the dashboard user detail page. + * - publish_course_modes_to_lms + - Switch + - Publish prices and SKUs to the LMS after every course modification. + * - async_order_fulfillment + - Sample + - Specify what percentage of orders are fulfilled asynchronously. + * - ENABLE_CREDIT_APP + - Switch + - Enable the credit checkout page, from which learners can purchase credit + in a course. + * - ENABLE_NOTIFICATIONS + - Switch + - Enable email notifications for a variety of user actions, such as when + an order is placed. + * - PAYPAL_RETRY_ATTEMPTS + - Switch + - Enable users to retry unsuccessful PayPal payments. + +********************************** +Enable a Feature Permanently +********************************** + +If you want to make a feature permanent, remove its feature gate from relevant +code and tests, and delete the gate from the database. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/index.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/index.rst new file mode 100644 index 000000000..187af647b --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/index.rst @@ -0,0 +1,29 @@ +.. _Additional Ecommerce Features: + +################################ +Additional E-Commerce Features +################################ + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + +After you install the basic features of the E-Commerce service on your instance +of the Open edX platform, you can enable or install additional features. You +can set up E-Commerce to send email, switch payment processors, or track event +data if one of your usual processors is unavailable. + +.. toctree:: + :maxdepth: 2 + + send_notifications + change_processors + apple_pay + track_data + gate_ecommerce + maintain_ecommerce + + + +.. Moved globalization.rst to desktop/Works In Progress folder, pending +.. possible move to ICRV. + diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/maintain_ecommerce.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/maintain_ecommerce.rst new file mode 100644 index 000000000..6198fb9e6 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/maintain_ecommerce.rst @@ -0,0 +1,35 @@ +.. _Maintaining ECommerce: + +#################################### +Maintaining the E-Commerce Service +#################################### + +Most of the time, you do not have to perform maintenance on the E-Commerce +service. However, E-Commerce creates **basket** objects to track products that +users want to purchase before users place an order. As more baskets and orders +are created, the baskets table can grow large. Depending on your database +backend, a large table can become difficult to manage and migrate. After an +order is placed, you can delete the corresponding basket from the baskets +table. + +To delete one or more baskets, follow these steps. + +.. note:: + Baskets that contain products but that are not used to create orders, such as + when a user adds a product to a basket but does not complete the order + process, are not deleted. These baskets provide records that users intended to + purchase a product. + +#. To display the number of baskets that you can delete, run the following + command. + + .. code-block:: bash + + $ ./manage.py delete_ordered_baskets + +#. To delete all the baskets that appear after you run the command in step 1, + use the --commit option. + + .. code-block:: bash + + $ ./manage.py delete_ordered_baskets --commit diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/send_notifications.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/send_notifications.rst new file mode 100644 index 000000000..03b63453c --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/send_notifications.rst @@ -0,0 +1,61 @@ +.. _Sending Notifications: + +####################### +Sending Notifications +####################### + +The edX E-Commerce service uses the `Communications API`_ that is part of +`Oscar`_ to create and send notifications in the form of email messages. To +send notifications, you must set up notifications, create one or more email +messages, and then send the email messages. + +************************* +Set Up Notifications +************************* + +#. Enable the E-Commerce service to send notifications. To do this, change the + value of the ``ENABLE_NOTIFICATIONS`` feature flag to True. +#. Define communication type codes to refer to particular types of + notification. For example, you might define a communication type code named + ``COURSE_SEAT_PURCHASED`` to correspond to the purchase of a course seat. + +************************* +Create an Email Message +************************* + +The E-Commerce service can send both HTML and plain text email messages. To +create an email message, create the following three files in the +``ecommerce/ecommerce/templates/customer/emails/`` folder. + + * An HTML template that extends ``email_base.html`` and includes the body of + the email. + * A plain text file that contains the email's subject line. + * A plain text file that contains the body of the email. + +Use the following convention to name these files. + +``commtype_{communication type code}_body.html`` + +For example, if the communication type code is ``course_seat_purchased``, the +three files would have the following names. + +* ``commtype_course_seat_purchased_body.html`` +* ``commtype_course_seat_purchased_body.txt`` +* ``commtype_course_seat_purchased_subject.txt`` + +.. note:: + To add a custom email body, override ``block body`` in the email_base.html + file. To add a custom footer, override ``block footer`` in the email_base.html + file. + +******************* +Send Email Messages +******************* + +To send email messages, use the ``send_notification(user, commtype_code, +context)`` method. This method is implemented in +``ecommerce/ecommerce/notifications/notifications.py``. + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/track_data.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/track_data.rst new file mode 100644 index 000000000..a26a8671f --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/additional_features/track_data.rst @@ -0,0 +1,12 @@ +.. _Tracking Data: + +################### +Tracking Data +################### + +The E-Commerce service uses `Segment`_ to collect business intelligence data. + +To emit events to your Segment project, specify your Segment project's API key +as the value of the ``SEGMENT_KEY`` setting. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_coupons.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_coupons.rst new file mode 100644 index 000000000..f9f58b4e4 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_coupons.rst @@ -0,0 +1,650 @@ +.. _Create and Manage Coupons: + +################################## +Create and Manage Coupons +################################## + +This topic covers how to create and distribute coupons and their associated +coupon codes. You can use coupons to provide discounted or free course +enrollments, also called "course seats", to your learners. + +.. contents:: + :depth: 1 + :local: + +.. _Create a Coupon: + +*************** +Create a Coupon +*************** + +To create a coupon, you create one or more coupon codes that learners use to +receive their discounts. You then use your email system to distribute the +discount or enrollment codes for that coupon. + +Creating a coupon code has several steps. + +.. contents:: + :depth: 1 + :local: + +You create coupons and their associated discount or enrollment codes on the +**Create New Coupon** page in the E-Commerce Coupon Administration tool, which +is located at ``http://localhost:8002/coupons/``. In the tool, you enter basic +information and select the options for your coupon. + +.. _Enter Basic Coupon Information: + +=============================== +Enter Basic Information +=============================== + +Each coupon requires some basic information. To enter basic information for +your coupon, follow these steps. + +#. Start the E-Commerce Service on your site. For details, see :ref:`Start + ECommerce Service`. + +#. In a browser on your E-Commerce server, go to + ``http://localhost:8002/coupons/`` to access the E-Commerce Coupon + Administration tool. + +#. On the **Coupon Codes** page, select **Create Coupon**. + +#. On the **Create New Coupon** page, enter the following information. + + * **Coupon Name**: The name you want to give the coupon, such as "January + 15% Promotion". The name must have fewer than 30 characters. + * **Category**: A list of possible classifications for your coupon, + such as "Course Promotion" and "Financial Assistance". Categories + can help you keep track of your coupons. + * **Valid from** and **Valid until**: The dates and times when the discount + or enrollment code is valid for use. The time zone is set to Universal + Coordinated Time (UTC). + * **Email Domains**: Optional. A list of comma separated domains. If + specified, only users registered with an email address that matches can + use the coupon. If null, any user can use the coupon. + * **Discount Value**: The discount that you want to apply to the course fee, + specified as a percentage between 1% and 99% or a fixed amount in U.S. + dollars. + * **Client**: The name of the organization that you create the codes for. + Note that the current system cannot automatically send this organization + an invoice for the codes you create. For more information, see + :ref:`Specify Invoicing Options` and :ref:`View the Invoice for a Coupon`. + * **Note** (optional): Any additional information that you want to add to + your coupon, such as why the coupon was created. The note is visible on + the coupon page in the coupon administration tool and in the .csv file for + the coupon. It is not visible to learners. + * **Tax Deducted Source (TDS)**: This field is not yet active. + +After you specify basic information for your coupon, you must specify the +coupon code type. + +.. _Specify the Coupon Code Type: + +=============================== +Specify the Coupon Code Type +=============================== + +In addition to entering basic information, you must specify a coupon code type. +The coupon code type is either "enrollment code" or "discount code". + +* An enrollment code covers the entire fee for a course seat. +* A discount code offers between 1% and 99% or a fixed dollar amount off the + fee for a course seat. + +A "course seat" is a single course enrollment in a specific course track. + +To specify the coupon code type, follow these steps. + +#. For **Code Type**, select **Enrollment Code** if you want the coupon code to + cover the entire course fee, or select **Discount Code** if you want to + provide a discount for the course. + +#. If you selected **Enrollment Code**, locate the **Number of Codes** field, + and then enter the number of enrollment codes that you want to create. + + If you selected **Discount Code**, the following fields are visible. + + * **Discount per Code** (required): Enter the percent or U.S. dollar amount + of the discount that you want to offer, then select **Percent** or + **Fixed**. Do not add a percent sign or a dollar sign. + + * **Code** (optional): If you want to specify your own discount code, such + as ``SCHOLAR15``, enter the code that you want in this field. This code + can have 1 to 16 characters. + + If you want the system to generate a discount code for you, leave this + field empty, and then enter the number of discount codes that you want to + create in the **Number of Codes** field. + +After you complete this step, you must specify the courses that you want your +coupon to apply to. + +.. _Coupons Specify Courses: + +================== +Specify Courses +================== + +In addition to specifying your coupon's code type, you must specify the courses +for your coupon. Your coupon can apply to a single course or to multiple +courses. + +.. note:: + If you want your coupon to apply to multiple courses, you must use the edX + Course Catalog API. The Course Catalog API is in beta and is not documented + or fully supported. + +To specify the courses for your coupon, follow these steps. + +#. On the **Create New Coupon** page, select **Single Course** or **Multiple + Courses**. + +#. Specify the courses for your coupon. + + If you selected **Single Course**, follow these steps. + + #. For **Course ID**, enter the ID of the course that you want. To find the + course ID, open the course administration tool at + ``http://localhost:8002/courses``, select your course name in the list of + courses, and then locate the **Course ID** field on the page for the + course. + + #. For **Seat Type**, select the type of seat for the coupon. A "seat" is + a single course enrollment in a specific course track. For example, the + seat type might be "verified" or "professional". The options for this + field appear after you enter a valid value in the **Course ID** field. + + If you selected **Multiple Courses**, follow these steps. + + #. In the **Valid for** field, enter a query to retrieve the courses that + you want. For more information about creating a query, see :ref:`Create a + Query for Multiple Courses`. + + To see a preview of the results that your query will return, enter your + query in the **Valid for** field, and then select **Preview**. A dialog + box opens that lists the courses in your query results. + + #. For **Seat Types**, select **Non-credit** or **Credit**. + + If you select **Non-credit**, you must also select **Verified**, + **Professional**, or both. + +After you complete these steps, you must :ref:`specify usage limitations for +your coupon `. + +.. _Create a Query for Multiple Courses: + +Create a Query for Multiple Courses +************************************* + +.. note:: + To create a query, you must use the edX Course Catalog API. The Course + Catalog API is in beta and is not documented or fully supported. + +The coupon administration tool uses queries to return a catalog of courses. The +coupons that you create apply to each course in that catalog. + +These queries use the following syntax. + +``field_name:search_terms`` + +Your query can contain operators such as quotation marks ("), asterisks (*), +and hyphens (-). + +For example, your query might resemble one of the following queries. + +:: + + org:(Company OR University) + + org:(-Company OR -University) + + start:[2016-01-01 TO 2016-12-31] + + number:6.002x* + +For more information about queries, including syntax and operators, see `Query +string syntax`_. + +The following table lists the field names that you can use in your query, along +with a description for each field name. + +.. list-table:: + :widths: 25 60 + :header-rows: 1 + + * - Field Name + - Description + * - ``announcement`` + - The date the course is announced to the public, in YYYY-MM-DD format. + * - ``end`` + - The course run end date, in YYYY-MM-DD format. + * - ``enrollment_end`` + - The enrollment end date, in YYYY-MM-DD format. + * - ``enrollment_start`` + - The enrollment start date, in YYYY-MM-DD format. + * - ``key`` + - The course run key, sometimes also called the course ID. + * - ``language`` + - The language in which the course is administered. + * - ``max_effort`` + - The estimated maximum number of hours necessary to complete the course. + * - ``min_effort`` + - The estimated minimum number of hours necessary to complete the course. + * - ``number`` + - The course number (for example, 6.002x). + * - ``org`` + - The organization associated with the course (for example, MITx). + * - ``pacing_type`` + - The pacing for the course run. Options are ``instructor_paced`` or + ``self_paced``. + * - ``start`` + - The course run start date, in YYYY-MM-DD format. + * - ``title`` + - The course title. + +.. _Specify Coupon Usage Limitations: + +=========================== +Specify Usage Limitations +=========================== + +In addition to specifying courses for your coupon, you must specify usage +limitations. Usage limitations control whether one or more customers can use +the coupon, as well as the number of times each customer can use the coupon. + +To specify usage limitations, follow these steps. + +#. On the **Create New Coupon** page, locate **Usage Limitations**. + +#. Select one of the following options. + + * **Can be used once by one customer** + + If you select this option, the **Number of Codes** field is visible. In + this field, specify the number of individual discount or enrollment codes + you want to create. The value must be between 1 and 1000. Make sure that + you create enough discount or enrollment codes so that each person receives + one code. + + * **Can be used once by multiple customers** or + * **Can be used multiple times by multiple customers** + + If you select one of these options, the **Maximum Number of Uses** field is + visible. In this field, specify the number of times customers can use the + coupon code. + + For example, if you want to create a single coupon code that is available + for use by 10 different customers, and each customer can use the code + only one time, select **Can be used once by multiple customers** , ``1`` + for **Number of Codes**, and ``10`` for **Maximum Number of Uses**. + + If you want to create a coupon code that is available for 10 uses, + whether by one customer or multiple customers, select **Can be used + multiple times by multiple customers**, ``1`` for **Number of Codes**, + and ``10`` for **Maximum Number of Uses**. + +After you specify usage limitations, you must specify invoicing options for +your coupon. + +.. _Specify Invoicing Options: + +=========================== +Specify Invoicing Options +=========================== + +In addition to setting usage limitations for your coupon, you must specify +invoicing options. You can send an invoice when you create the coupon or after +one or more customers have redeemed the coupon. The invoice can be for the +total amount or for part of the total amount. + +To specify the way you want to invoice your client, follow these steps. + +#. On the **Create New Coupon** page, locate **Invoice Type**. + +#. Select one of the following options. + + * **Already invoiced**: Select this option if you have already sent an + invoice to your client. + + If you select this option, you must also enter information in the + following fields. + + * **Invoice Number**: Your internal invoice number. + + * **Invoice Amount**: The amount that you have already invoiced the + client. + + * **Payment Date**: The date when payment is due from the client. + + * **Invoice after redemption**: Select this option if you will send an + invoice to your client after one or more coupon codes have been redeemed. + + * **N/A**: Select this option if neither of the other options + applies to your situation. + + +=============================== +Finish and Review Coupon +=============================== + +* After you have :ref:`entered all the basic coupon information ` and specified the options that you want, select **Create + Coupon**. + +When you select **Create Coupon**, the system generates one or more discount or +enrollment codes as well as the URLs where users can redeem these codes. + +When the system has finished generating the coupon, a page for the coupon +opens. This page lists the information for your coupon, including all discount +or enrollment codes for the coupon, the coupon's status, URLs where users can +redeem the codes, dates the coupon is valid, and the course that the coupon +applies to. You can also :ref:`download a .csv file with the coupon information +` from this page. + +.. _Download Coupon Information: + +*********************************** +Download Coupon Information +*********************************** + +After you create a coupon, you can download a .csv file that lists the +information that you entered when you created the coupon. The .csv file also +includes additional information, such as the discount or enrollment codes that +are associated with your coupon and the system-generated URL where a user can +redeem each code. + +#. In your browser, go to ``http://localhost:8002/coupons/`` to open the coupon + administration tool. +#. On the **Coupon Codes** page, locate the coupon that you want in the table, + and then select the name of the coupon. The page for the coupon opens. +#. On the page for the coupon, select **Download**. Your .csv file begins + downloading automatically. + +The .csv file for your coupon lists the following information. + +.. list-table:: + :widths: 25 60 + :header-rows: 1 + + * - **Coupon Name** + - The name of the coupon. + * - **Code** + - The 16-digit alphanumeric discount or enrollment code. The .csv file + lists at least one entry for each code. The system creates an additional + entry for the code each time the status of the code changes (for + example, when the status changes from **Active** to **Redeemed**). + * - **Maximum Coupon Usage** + - The number of times that the discount code or enrollment code that is + associated with the coupon can be used. For single-use coupons, this + value is 1. For multi-use coupons, this is the value that you specified + in the **Maximum Number of Uses** field. + * - **Redemption Count** + - The number of times the coupon has been redeemed. The initial value is + 0, and the value is incremented each time that a discount code or + enrollment code for the coupon is redeemed. + * - **Coupon Type** + - The type of coupon code associated with this coupon. Possible values are + **Enrollment** and **Discount**. + * - **URL** + - The URL where the user redeems the coupon code. + * - **Catalog Query** (for multi-course coupons only) + - The query that was used to determine which courses the coupon applies + to. + * - **Course Seat Types** (for multi-course coupons only) + - The seat type that the coupon applies to. For example, the seat type + might be "verified" or "professional". For more information about seat + types, see :ref:`Coupons Specify Courses`. + * - (for single-course coupons only) **Course ID** + - The ID of the course that the coupon applies to. + * - (for single-course coupons only) **Organization** + - The organization that provides the course. + * - **Client** + - The organization that purchased the coupon codes. + * - **Category** + - The value that you selected for the **Category** field when you created + the coupon. + * - **Note** + - The text, if any, that you entered in the **Note** field when you + created the coupon. + * - **Price** + - The regular fee for the course. + * - **Email Domains** + - The email domains allowed to use this coupon. + * - **Invoiced Amount** + - The text, if any, that you entered in the **Total to Invoice to Client** + field when you created the coupon. + * - **Discount Percentage** + - The percent discount, if any, that you specified when you created the + coupon. + * - **Discount Amount** + - The dollar amount discount, if any, that you specified when you created + the coupon. + * - **Status** + - The status of the coupon. Possible values are **Active**, **Redeemed**, + or **Expired**. + * - **Order Number** + - The order number associated with the redemption of the enrollment or + discount code. + * - **Redeemed By Username** + - The username of the customer who redeemed the enrollment or discount + code. + * - (for multi-course coupons only) **Redeemed for Course ID** + - The course ID of the course for which the coupon was redeemed. + * - **Created By** + - The username of the user who created the coupon. + * - **Create Date** + - The date the coupon was created. + * - **Coupon Start Date** + - The first date the coupon can be used. + * - **Coupon Expiry Date** + - The last date the coupon can be used. + + +.. _Edit Coupons: + +************* +Edit a Coupon +************* + +You edit a coupon by using the coupon administration tool. + +.. note:: + You cannot edit the following fields. + + * **Code Type** + * **Course ID** + * **Single course** or **Multiple courses** + * **Seat Type** + * **Usage Limitations** + * **Number of Codes** or **Maximum Number of Uses** + +#. In your browser, go to ``http://localhost:8002/coupons/`` to open the coupon + administration tool. + +#. On the **Coupon Codes** page, locate the coupon that you want in the table, + and then select the name of the coupon. The page for the coupon opens. + +#. On the page for the coupon, select **Edit Coupon**. + +#. Make the changes that you want. + +#. Select **Save Changes**. + +.. _Deactivate Coupons: + +************************ +Deactivate a Coupon +************************ + +To deactivate a coupon, change the **Valid from** and **Valid until** date +fields so that both dates are in the past. For more information, see :ref:`Edit +Coupons`. + + +.. _Distribute Coupon Codes: + +*************************************** +Distribute Coupon Codes to Learners +*************************************** + +You can distribute both discount codes and enrollment codes to learners in two +ways. + +* You provide a coupon code that learners enter on the **Checkout** page for + the verified or professional certificate track. If you do this, edX + recommends that you also provide the URL for the course About page to make + signing up for the course easier. + +* You provide a URL for an offer landing page. This automatically generated + page presents information about the course, lets the learner know that the + coupon code has been applied, and provides the opportunity for the learner to + enroll. Learners can access this URL if they do not have an edX account or + they are not signed in. However, learners must sign in or create an edX + account to redeem the coupon and enroll in the course. + + A URL for an offer landing page has the following format. + + ``http://localhost:8002/coupons/offer/?code=################`` + +.. note:: + If the coupon code is a discount code, the learner must pay any balance due + before enrolling in the course for a verified or professional certificate. + +To distribute the coupon code or URL to learners, you determine the coupon code +or the URL for the learner to use, and then you create and send an email that +includes the coupon code or the URL. For suggestions for email message text, +see :ref:`Example Email Messages`. + +.. _Find a Coupon Code or URL: + +=========================== +Find a Coupon Code or URL +=========================== + +You can find coupon codes, whether discount codes or enrollment codes, and +their associated URLs in two places: on the page for the coupon in the coupon +administration tool, and in a downloadable .csv file. You can use either option +to find the coupon code or URL for your learners. + + +Find a Code or URL on the Coupon Page +************************************* + +To find a coupon code or URL on the page for the coupon in the coupon +administration tool, follow these steps. + +#. In your browser, go to ``http://localhost:8002/coupons/`` to open the coupon + administration tool. +#. On the **Coupon Codes** page, locate the coupon that you want in the table, + and then select the name of the coupon. The page for the coupon opens. +#. On the page for the coupon, locate the table under **Codes**. +#. In the table, locate the information that you want. + + * For a coupon code that the learner will enter on the **Checkout** page, + use the value in the **Code** column. + + * For an offer landing page, use the URL in the **Redemption URL** column. + +Find a Code or URL in a Downloaded File +*************************************** + +To find a coupon code or URL in the .csv file for a coupon, follow these steps. + +#. :ref:`Download a .csv file ` that lists + the information for your coupon, and then open the .csv file. +#. In the .csv file, locate the information that you want. + + * For a coupon code that the learner will enter on the **Checkout** page, + use the value in the **Code** column. + + * For an offer landing page, use the URL in the **URL** column. + +.. _Send an Email Message: + +=========================== +Send an Email Message +=========================== + +After you :ref:`locate the coupon code or URL ` that +you want to use, you use your email system to provide that information in a +message to potential learners. + +.. note:: + When you send a coupon code for a learner to use on the **Checkout** page, + edX recommends that you include the About page URL for the course as well + as the coupon code to help the learner enroll more easily. + + +.. _Example Email Messages: + +Example Email Messages +************************ + +You can use the following email messages as examples of the communication that +you send to your learners. + +If Learners Enter a Coupon Code on the Checkout Page +==================================================== + +.. code:: + + Dear learner, + + This message includes a discount code for edX101: Overview + of Creating an edX Course. For more information about the course, see + https://www.edx.org/course/overview-creating-edx-course-edx-edx101. + + To redeem this code, sign up for a verified certificate, and + then enter the following coupon code in the **Coupon Code** field on the + **Checkout** page: + + ZDPC3AQV3732RQT5 + + We look forward to learning with you! + + The edX101 course team + + +If Learners Visit an Offer Landing Page +======================================= + +.. code:: + + Dear learner, + + This message includes a discount code for edX101: Overview + of Creating an edX Course. To redeem this code and enroll in the course, visit + the following URL: + + http://localhost:8002/coupons/offer/?code=ZDPC3AQV3732RQT5 + + We look forward to learning with you! + + The edX101 course team + +.. _View the Invoice for a Coupon: + +******************************** +View the Invoice for a Coupon +******************************** + +When you create a coupon, the E-Commerce service generates and fulfills an +order. The Invoice Payment Processor module in the service then records the +fulfilled order. Because the Invoice Payment Processor module assumes that you +have sent or will send an invoice to the client who purchased the coupon, the +module also records the order in the Invoice table in the Django administration +panel so that you can view and reconcile the order. + +To view your coupon invoices in the Invoice table, go to +``http://localhost:8002/admin/invoice/invoice/``. The table lists all of the +invoices for your coupons, along with information such as the client name and +the invoice status. + +For more information about the way that the E-Commerce service manages orders, +see :ref:`Manage Orders`. + +.. include:: /links.txt + diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_course_seats.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_course_seats.rst new file mode 100644 index 000000000..27c121d3b --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_course_seats.rst @@ -0,0 +1,76 @@ +.. _Create Course Seats: + +#################### +Create Course Seats +#################### + +A course seat represents an enrollment track, sometimes called an enrollment +mode. For information about the enrollment tracks that edX offers, see +:term:`Enrollment track`. + +You create course seats by creating a course on the **Create New Course** page +in the E-Commerce Course Administration tool, which is located at +``http://localhost:8002/courses/``. After you create a course, the E-Commerce +service creates the course seats that are associated with that course. + +To create a course seat, follow these steps. + +#. Start the E-Commerce Service on your site. For details, see :ref:`Start + ECommerce Service`. + +#. In a browser on your E-Commerce server, go to + ``http://localhost:8002/courses/`` to access the E-Commerce Course + Administration tool. + +#. On the **Courses** page, select **Add New Course**. + +#. On the **Create New Course** page, enter the following information for your + course. + + * Course ID + * Course Name + * Course Type + * Course Seats + * Bulk :ref:`Enrollment Code` Yes/No + + For **Course Type**, select a course type and the options for that course + type. + + * If you select **Free (Audit)**, you must specify whether you want to + allow honor code learners to earn an honor code certificate. To do this, + select **Yes** under **Include Honor Seat**. + + * If you select **Verified**, you must add the following information. + + * **Price (in USD)** + * **Upgrade Deadline** + * **Verification Deadline** + * **Include Honor Seat**: This option grants honor code certificates to + learners who successfully complete the course. + + * If you select **Professional Education**, you must add the following + information. + + * **Price (in USD)** + * **ID Verification Required?** + * **Upgrade Deadline** + + * **Verification Deadline**: This option is required if you select + **Yes** for **ID Verification Required?** + + * If you select **Credit**, you must add the following information. + + * **Price (in USD)**: The price for a verified certificate. + * **Upgrade Deadline** + * **Credit Provider** + * **Price (USD)**: The price for course credit. + * **Credit Hours** + * **Upgrade Deadline** + * **Verification Deadline** + * **Include Honor Seat**: This option grants honor code certificates to + learners who successfully complete the course. + + +#. Select **Create Course**. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_enrollment_codes.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_enrollment_codes.rst new file mode 100644 index 000000000..54cf1b10d --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_enrollment_codes.rst @@ -0,0 +1,64 @@ +.. _Enable and Create Enrollment Codes: + +##################################### +Enable and Create Enrollment Codes +##################################### + +Enrollment codes allow users to purchase bulk enrollments for a course. + +.. note:: + + Enrollment codes used for bulk enrollments, as described in this topic, are + not related to the "enrollment code" coupon code type that is referred to in + the :ref:`Create and Manage Coupons` topic. + + +************************ +Enable Enrollment Codes +************************ + +Before you create enrollment codes that can be used for bulk enrollments for a +course, you must enable enrollment codes in the E-Commerce service and in +individual courses. + +#. To enable enrollment codes in the E-Commerce service, run the site + configuration command together with the following option. + + :: + + ``--enable-enrollment-codes=True`` + + For more information, see :ref:`Add Another Site Partner and Site + Configuration`. + +#. To enable enrollment codes in individual courses, follow these steps. + + #. Follow step 1 through step 5 in :ref:`Create Course Seats` to access and + select options on the **Add New Course** page. Do not select **Create + Course** after you complete step 5. + #. Select **Include Enrollment Code**. + #. Select **Create Course**. + +After you select **Create Course**, enrollment codes are enabled for that +course. + +************************ +Create Enrollment Codes +************************ + +#. Go to the enrollment page for the course. +#. On the enrollment page, select **Buy enrollment**. Do not select **Enroll in + the course**. + + The basket page opens. + +#. For **Number of Enrollment Codes**, enter the number of enrollment codes + that you want. Each enrollment code is for one course seat. +#. Select **Purchase**. + +After you select **Purchase**, you receive an e-mail message that contains a +link to a .csv file. The .csv file lists the enrollment codes. + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_products_overview.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_products_overview.rst new file mode 100644 index 000000000..91406bca5 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_products_overview.rst @@ -0,0 +1,57 @@ +.. _Create Products Overview: + +########################### +Creating Products Overview +########################### + +The edX platform offers several types of products. You create these products in +E-Commerce web pages. + +* Course seats represent an :term:`Enrollment track`. Each + course seat has an associated set of attributes, such as price and + certificate availability. The edX code uses course seats to determine how a + given enrollment should be handled. For more information, see :ref:`Create + Course Seats`. + +* Coupons allow you to offer learners a discount, either percentage or fixed + amount, on a course enrollment. For more information, see :ref:`Create and + Manage Coupons`. + +* Enrollment codes allow users to purchase bulk enrollments for a course. For + more information, see :ref:`Enable and Create Enrollment Codes`. + +* Programs are collections of related courses. Learners can enroll in and + purchase courses separately, or you can configure programs to allow one- + click purchasing of all courses in a program. For more information, see + :ref:`Programs`. + + +.. _Start ECommerce Service: + +****************************** +Start the E-Commerce Service +****************************** + +Before you can create a product, you must start the E-Commerce service on your +site. Follow these steps to start the E-Commerce service. + +#. In the ecommerce and LMS configuration files (``/edx/etc/ecommerce.yml`` and + ``/edx/app/edxapp/lms.yml``, respectively), verify the following + settings. + + .. note:: + If you are using `devstack`_, these values are set correctly for you. + However, edX recommends that you verify these values. + + * The ``EDX_API_KEY`` value in the LMS file must be the same as the + ``EDX_API_KEY`` value in the ecommerce file. If the values differ, change + the value in the LMS file to match the ecommerce file. + * The ``ECOMMERCE_API_SIGNING_KEY`` value in the LMS file must be the same + as the ``JWT_SECRET_KEY`` value in the ecommerce file. If the values + differ, change the value in the LMS file to match the ecommerce file. + +#. On devstack, start the E-Commerce server on port 8002, and start the LMS + on port 8000. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_program_offers.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_program_offers.rst new file mode 100644 index 000000000..0380c86e9 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_program_offers.rst @@ -0,0 +1,50 @@ +.. _Create Program Offers: + +##################### +Create Program Offers +##################### + +Program offers are discounts, either percentage or fixed amount discounts, that +apply to a specific program. When a program offer is active for a program, the +program's price appears discounted both on the program's purchase button and on +the e-commerce checkout page. + +You create program offers on the **Create Program Offer** page in the E-Commerce +Program Offers Administration tool, which is located at +``http://localhost:8002/programs/offers``. + +.. note:: Each program can be associated with only one program offer. + To offer a new discount, edit the existing program offer for your program. + +To create a program offer, follow these steps. + +#. Start the E-Commerce Service on your site. For details, see :ref:`Start + ECommerce Service`. + +#. Obtain the Program UUID for the program for which you are creating an offer. + Find your program's UUID in the Discovery Service Django administration site, + under **Course Metadata > Programs**. + +#. In a browser on your E-Commerce server, go to + ``http://localhost:8002/programs/offers/`` to access the E-Commerce Program + Offers Administration tool. + +#. On the **Program Offers** page, select **Create Program Offer**. + +#. On the **Create Program Offer** page, enter the following information for + your program offer. + + * Program UUID + * Start Date + * End Date + * Discount Type - either percentage or absolute. + * Discount Value - the value of the discount based on the discount type. + +.. note:: To ensure that your program discount is reflected even when only some, + not all, of a program's courses are in a learner's basket for checkout, you + must select the **Enable Partial Program Offer** setting in the E-Commerce + Service Django Administration site, under **Core > Site configurations**. + +#. Select **Create Program Offer**. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_programs.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_programs.rst new file mode 100644 index 000000000..2ac20aaf2 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/create_programs.rst @@ -0,0 +1,90 @@ +.. _Programs: + +################ +About Programs +################ + +Programs are collections of related courses that you make available on your +marketing site. Each program is of a particular type. + +The cost for a program is the sum of the cost for each of its courses. You can +change the cost for a program by creating a program offer, which is a discount +on the program price of either a percentage or fixed amount. For more details, +see :ref:`Create Program Offers`. + + +******************** +Create Program Types +******************** + +You add program types in the Discovery Service Django administration site for +your Open edX instance. + +To add a program, follow these steps. + +#. Sign into the Discovery Service Django Administration site for your Open + edX instance. For example, ``https:///admin/``, or + ``localhost:18381`` if you are testing locally. + +#. In the **Course Metadata** section, select **Program types**. + +#. Select **Add Program Type**. + +#. On the **Add program type** page, specify a name for the new program type, + and select the seat types that are applicable to programs of this type. + +#. Optionally, add a program logo image and a slug for this program type for + use on the marketing site. + +#. When you have finished entering information for the program type, select one of + the **Save** options: **Save**, **Save and add another**, or **Save and + continue editing**. + + You can now specify this program type when you create new programs. + + +*************** +Create Programs +*************** + +You add programs and specify the courses that are in each program in the +Discovery Service Django administration site for your Open edX instance. + +To add a program, follow these steps. + +#. Sign into the Discovery Service Django Administration site for your Open + edX instance. For example, ``https:///admin/``, or + ``localhost:18381`` if you are testing locally. + +#. In the **Course Metadata** section, select **Programs**. + +#. Select **Add Program**. + + On the **Add Program** page, a UUID is assigned to the new program. + +#. Enter information for the new program. Required fields, for example + **Title**, **Status** and **Type**, have boldface names. + + * In the **Courses** field, specify the courses that are part of the program. + Names of current courses are automatically matched as you continue to type. + To add a course that does not currently exist, click the plus sign (+) next + to the field to create a new course. + + * To allow learners to purchase upgrades to the verified track for all + the courses in the program with one click, select **One click purchase + enabled**. + +#. When you have finished entering information for the program, select one of + the **Save** options: **Save**, **Save and add another**, or **Save and + continue editing**. + +.. This procedure completes the course and program structure. To provide "site +.. functionality" for programs, the LMS and the marketing site also need to know +.. about the program and the program offer, if any, that is associated with the +.. program. + +.. Discovery service? + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/index.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/index.rst new file mode 100644 index 000000000..8ece65366 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/create_products/index.rst @@ -0,0 +1,25 @@ +.. _Create Ecommerce Products: + +############################ +Create E-Commerce Products +############################ + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + +After you :ref:`configure a partner and at least one site ` for the E-Commerce service to use, and you +have compiled and moved your static assests, you can create products. For more +information, see the following topics. + +.. toctree:: + :maxdepth: 2 + + create_products_overview + create_course_seats + create_coupons + create_enrollment_codes + create_programs + create_program_offers + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/enable_receipt_page.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/enable_receipt_page.rst new file mode 100644 index 000000000..71d01dfc7 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/enable_receipt_page.rst @@ -0,0 +1,47 @@ +.. _Enable the ECommerce Receipt Page: + +########################################## +Enable the E-Commerce Service Receipt Page +########################################## + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + +The E-Commerce service includes a receipt page that you can display to users +after their orders are complete. + +.. contents:: + :depth: 1 + :local: + +.. _Enable the Receipt Page: + +*********************** +Enable the Receipt Page +*********************** + +To enable the default receipt page for the E-Commerce service, follow these +steps. + +#. Sign in to the LMS Django administration console for your base URL. For + example, ``http://{your_URL}/admin``. + +#. On the **Site Administration** page, locate **Site_Configuration**. + +#. In the **Site_Configuration** section, next to **Site configurations**, + select **Change**. + +#. On the **Change site configuration** page, locate the **Values** field, and + then add the following JSON format value. + + :: + + { + "ECOMMERCE_RECEIPT_PAGE_URL":"/checkout/receipt/?order_number=" + } + +#. Select **Save**. + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/index.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/index.rst new file mode 100644 index 000000000..9802512d0 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/index.rst @@ -0,0 +1,49 @@ +.. _Adding ECommerce (Deprecated) to Open edX: + +######################################################### +Adding E-Commerce (Deprecated) to the Open edX Platform +######################################################### + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + +edX uses a Django application called ``ecommerce`` to provide the platform with +ecommerce functionality. This `E-Commerce service`_ extends `Oscar`_, an open +source Django ecommerce framework, to manage the edX product catalog and handle +orders for those products. The following sections describe how to install and +use the E-Commerce service with the Open edX platform. + +To complete the procedures that this section describes, you use both the +E-Commerce Service's Django administration site and the E-Commerce +Administration Tool (CAT). The CAT is a web app that is included with the +E-Commerce service and enables you to configure and manage products that are +associated with the courses and programs on your instance of the Open edX +learning management system (LMS). + +In addition to these required steps, you can add optional features to the +E-Commerce service for your instance of the Open edX platform. For more +information, see :ref:`Additional Ecommerce Features`. + + +.. toctree:: + :maxdepth: 2 + + install_ecommerce + theming + manage_assets + create_products/index + enable_receipt_page + manage_orders + test_ecommerce + additional_features/index + internationalization + + + +.. include:: /links.txt + +.. TODO +.. - Oscar Dashboard +.. - Payment processors +.. - API +.. - Course Administration Tool diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/install_ecommerce.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/install_ecommerce.rst new file mode 100644 index 000000000..bec08ba2b --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/install_ecommerce.rst @@ -0,0 +1,356 @@ +.. _Install and Start ECommerce: + +######################################## +Install and Start the E-Commerce Service +######################################## + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + +To install and start the edX E-Commerce service, you must complete the +following steps. + +.. contents:: + :depth: 1 + :local: + +.. _Set Up a Virtual Environment: + +**************************** +Set Up a Virtual Environment +**************************** + +#. Create or activate a Python virtual environment. You execute all of the + commands described in this section within the virtualenv (unless otherwise + noted). + + For more information, see `Virtual Environments`_. + +#. Run the following command to install dependencies. + + .. code-block:: bash + + $ make requirements + +#. (Optional) Create settings overrides that you do not commit to the + repository. To do this, create a file named + ``ecommerce/settings/private.py``. The ``ecommerce/settings/local.py`` file + reads the values in this file, but Git ignores the file. + +.. _Run Migrations: + +************** +Run Migrations +************** + +To set up the ``ecommerce`` database, you must run migrations. + +.. note:: + Local installations use SQLite by default. If you use another database + backend, make sure you update your settings and create the database, if + necessary, before you run migrations. + +#. To run migrations, execute the following command. + + .. code-block:: bash + + $ make migrate + +When you run migrations, the E-Commerce service adds a default site to your installation. + +.. _Configure OIDC: + +*********************************** +Configure edX OpenID Connect (OIDC) +*********************************** + +The E-Commerce service relies on the edX `OpenID Connect`_ (OIDC) +authentication provider for login. OIDC is built on top of OAuth 2.0. +Currently, the LMS serves as the authentication provider. + +To configure the E-Commerce service to work with OIDC, complete the following +procedures. + +.. contents:: + :depth: 1 + :local: + +.. _Create Register Client: + +============================ +Create and Register a Client +============================ + +To create and register a new OIDC client, follow these steps. + +#. Install and start the Open edX `devstack`_. +#. In your browser, go to ``http://127.0.0.1:8000/admin/oauth2/client/``. +#. Select **Add client**. +#. Leave the **User** field blank. +#. For **Client Name**, enter ``E-Commerce Service``. +#. For **URL**, enter ``http://localhost:8002/``. +#. For **Redirect URL**, enter ``http://127.0.0.1:8002/complete/edx-oidc/``. + This is the OIDC client endpoint. + + The system automatically generates values in the **Client ID** and **Client + Secret** fields. + +#. For **Client Type**, select **Confidential (Web applications)**. +#. Select **Save**. + +=============================== +Designate the Client as Trusted +=============================== + +After you create your client, designate it as trusted. Trusted clients +bypass the user consent form that usually appears after the system validates +the user's credentials. + +To designate your client as trusted, follow these steps. + +#. In your browser, go to + ``http://127.0.0.1:8000/admin/oauth2_provider/trustedclient/add/``. +#. In the **OAuth 2.0 clients** list, select the redirect URL for the client + that you just created. +#. Select **Save**. + +.. _Configure a Site Partner and Site Configuration: + +************************************************* +Configure a Site, Partner, and Site Configuration +************************************************* + +To finish creating and configuring your OIDC client, you must configure a +partner, site, and site configuration for the E-Commerce service to use. The +site that you configure is the default site that the E-Commerce service adds +when you run migrations. You must update this default site to match the domain +that you will use to access the E-Commerce service. You must also set up a site +configuration that contains an ``oauth_settings`` JSON field that stores your +OIDC client's settings, as follows. + +.. list-table:: + :widths: 25 60 20 + :header-rows: 1 + + * - Setting + - Description + - Value + * - ``SOCIAL_AUTH_EDX_OIDC_KEY`` + - OAuth 2.0 client key + - The **Client ID** field in the :ref:`Create + Register Client` section. + * - ``SOCIAL_AUTH_EDX_OIDC_SECRET`` + - OAuth 2.0 client secret + - The value from the **Client Secret** field in the :ref:`Create + Register Client` section. + * - ``SOCIAL_AUTH_EDX_OIDC_URL_ROOT`` + - OAuth 2.0 authentication URL + - For example, ``http://127.0.0.1:8000/oauth2``. + * - ``SOCIAL_AUTH_EDX_OIDC_ID_TOKEN_DECRYPTION_KEY`` + - OIDC ID token decryption key, used to validate the ID + token + - The same value as ``SOCIAL_AUTH_EDX_OIDC_SECRET``. + * - ``SOCIAL_AUTH_EDX_OIDC_ISSUER`` + - OIDC ID token issuer + - For example, ``http://127.0.0.1:8000/oauth2``. + * - ``SOCIAL_AUTH_EDX_OIDC_LOGOUT_URL`` + - User logout URL + - For example, ``http://127.0.0.1:8000/logout``. + + +To configure your default site, partner, and site configuration, use the +appropriate settings module for your environment +(``ecommerce.settings.devstack`` for Devstack, +``ecommerce.settings.production`` for Fullstack) to run the following Django +management command. This command updates the default site and creates a new +partner and site configuration with the specified options. + + .. code-block:: bash + + $ sudo su ecommerce + $ python manage.py create_or_update_site --site-id=1 --site-domain=localhost:8002 --partner-code=edX --partner-name='Open edX' --lms-url-root=http://localhost:8000 --theme-scss-path=sass/themes/edx.scss --payment-processors=cybersource,paypal --client-id=[change to OIDC client ID] --client-secret=[change to OIDC client secret] + +.. note:: + The ``--lms-url-root`` option must start with the desired protocol (e.g. ``http://``). + +.. _Add Another Site Partner and Site Configuration: + +================================================= +Add Another Site, Partner, and Site Configuration +================================================= + +If you want to add more sites, partners, and site configurations, you can use +the ``create_or_update_site`` command. The following options are available for +this command. + +.. list-table:: + :widths: 25 20 60 20 + :header-rows: 1 + + * - Option + - Required + - Description + - Example + * - ``--site-id`` + - No + - Database ID of a site you want to update. + - ``--site-id=1`` + * - ``--site-domain`` + - Yes + - Domain by which you will access + the E-Commerce service. + - ``--site-domain=ecommerce.example.com`` + * - ``--site-name`` + - No + - Name of the E-Commerce site. + - ``--site-name='Example E-Commerce'`` + * - ``--partner-code`` + - Yes + - Short code of the partner. + - ``--partner-code=edX`` + * - ``--partner-name`` + - No + - Name of the partner. + - ``--partner-name='Open edX'`` + * - ``--lms-url-root`` + - Yes + - URL root of the Open edX LMS instance. + - ``--lms-url-root=https://example.com`` + * - ``--theme-scss-path`` + - No + - ``STATIC_ROOT`` relative path of the site's SCSS file. + - ``--theme-scss-path=sass/themes/edx.scss`` + * - ``--payment-processors`` + - No + - Comma-delimited list of payment processors used on the site. + - ``--payment-processors=cybersource,paypal`` + * - ``--client-id`` + - Yes + - OIDC client ID. + - ``--client-id=ecommerce-key`` + * - ``--client-secret`` + - Yes + - OIDC client secret. + - ``--client-secret=ecommerce-secret`` + * - ``--from-email`` + - Yes + - Address from which email messages are sent. + - ``--from-email=notifications@example.com`` + * - ``--enable-enrollment-codes`` + - No + - Indication that specifies whether enrollment codes for seats can be + created. + - ``--enable-enrollment-codes=True`` + * - ``--payment-support-email`` + - No + - Email address displayed to user for payment support. + - ``--payment-support-email=support@example.com`` + * - ``--payment-support-url`` + - No + - URL displayed to user for payment support. + - ``--payment-support-url=https://example.com/support`` + + +To add another site, use the appropriate settings module for your environment +(``ecommerce.settings.devstack`` for Devstack, +``ecommerce.settings.production`` for Fullstack) to run the following Django +management command. This command creates a new site, partner, and site +configuration with the options that you specify. + + .. code-block:: bash + + $ sudo su ecommerce + $ python manage.py create_or_update_site --site-domain=[change me] --partner-code=[change me] --partner-name=[change me] --lms-url-root=[change me] --client-id=[OIDC client ID] --client-secret=[OIDC client secret] --from-email=[from email] + +**************** +Start the Server +**************** + +To complete the installation and start the E-Commerce service, follow these +steps. + +.. note:: + Local installations use SQLite by default. If you use another database + backend, make sure you update your settings and create the database, if + necessary, before you run migrations. + +#. (Devstack only) If you are using devstack, switch to the ``ecommerce`` user + and use the ``ecommerce.settings.devstack`` settings module to run the + following commands. + + .. code-block:: bash + + $ sudo su ecommerce + $ make serve + +#. To run the server, execute the following command. + + .. code-block:: bash + + $ python manage.py runserver 8002 + + .. note:: + If you use a different port, make sure you update the OIDC client by using + the LMS Django Administration site. For more information about + configuring the OIDC client, see :ref:`Configure OIDC`. + + +***************************************** +Switch from ShoppingCart to E-Commerce +***************************************** + +.. note:: The ShoppingCart service was deprecated in the Dogwood release of + Open edX. Ecommerce-related tasks are now handled by the E-Commerce + service. + +If you are upgrading from an earlier version of Open edX, follow these steps +to use the E-Commerce service for ecommerce-related tasks instead of +ShoppingCart. + +#. Sign in to the LMS Administration Django site for your base URL. For example, + ``http://{your_URL}/admin``. + +#. In the **Commerce** section, next to **Commerce configuration**, select + **Add**. + +#. Select **Enabled**. + +#. Select **Checkout on ecommerce service**. + +#. (Optional) In the **Single course checkout page** field, override the + default path value of ``/basket/single-item/`` with your own path value. + + .. important:: If you override the default path value, you must also change + all of the code that relies on that path. + +#. Set the **Cache Time To Live** value in seconds. + +#. Select the site for which you want to enable the E-Commerce service. + +#. Select **Save**. + + +.. _Development Outside Devstack: + +**************************** +Development Outside Devstack +**************************** + +If you are running the LMS in `devstack`_ but would prefer to run the +E-Commerce service on your host, set up a reverse port-forward. This reverse +port-forward allows the LMS process inside your devstack to use +``127.0.0.1:8002`` to make calls to the E-Commerce service running on your +host. This simplifies LMS URL configuration. + +To set up a reverse port-forward, execute the following command when you SSH +into your devstack. Make sure that you run this command on the VM host, not the +guest. + +.. code-block:: bash + + $ vagrant ssh -- -R 8002:127.0.0.1:8002 + + + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/internationalization.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/internationalization.rst new file mode 100644 index 000000000..4a8f85e3d --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/internationalization.rst @@ -0,0 +1,82 @@ +Internationalization +==================== + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + + +Follow the `internationalization coding guidelines`_ in the edX Developer's Guide when developing new features. + +Languages are enabled in the settings file, for example in ``ecommerce/settings/base.py`` + +.. code-block:: python + + LANGUAGES = ( + ('en', _('English')), + ('es', _('Spanish')), + ('es-419', _('Spanish (Latin American)')), + ) + +More details can be found in the `Django documentation for Languages`_. + +.. _E-Commerce Language Negotiation: + +E-Commerce Language Negotiation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Language negotiation for E-Commerce is handled by `Django's Locale Middleware`_. Django's Language Negotiation rules, in +priority order, are as follows. + +#. Language prefix is not enabled by default for the E-Commerce application. +#. LANGUAGE_SESSION_KEY is not used. +#. LANGUAGE_COOKIE_NAME is used to negotiate language. A user's language is set in their account settings in edx-platform which sets the language cookie. The language cookie name that is set for the E-Commerce language should be the same as the language cookie name set in the edx-platform repo. This can be configured in ``ecommerce/settings/base.py``. + + .. code-block:: python + + LANGUAGE_COOKIE_NAME = 'openedx-language-preference' + +#. The Accept-Language HTTP header is used. +#. LANGUAGE_CODE is used as the last resort. This can be set in ``ecommerce/settings/base.py`` + +.. _PayPal Language Negotiation: + +PayPal Language Negotiation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +To enable localization for PayPal, follow these steps. + +#. Sign in to the LMS Django administration console for your base URL. For + example, ``http://{your_URL}/admin``. + +#. On the **Site Administration** page, locate **Waffle**. + +#. In the **Waffle** section, next to **Switches**, select **Add**. + +#. On the **Add switch** page, locate the **Name** field, and then add ``create_and_set_webprofile``. + +#. On the **Add switch** page, select the **Active** checkbox. + +#. Select **Save**. + +A language code for E-Commerce will be taken from a cookie as described in `E-Commerce Language Negotiation`_. When the +language code is fetched from the cookie, only the base language is used. For example, ``es-419`` resolves to ``es``. +PayPal requires a country code. To get the country code, we use the language code to map it to a country. For example, +the language code ``es`` will map to the country code ``MX`` when it is sent to PayPal. To add your language for PayPal, +look up `PayPal's country to language mapping`_ and add it to PAYPAL_LOCALES in ``ecommerce/extensions/payment/constants.py``. + +.. code-block:: python + + PAYPAL_LOCALES = { + 'zh': 'CN', + 'fr': 'FR', + 'en': 'US', + 'es': 'MX', + } + + +If a language fetched from the cookie cannot be found in PAYPAL_LOCALES, the LANGUAGE_CODE is used. If the LANGUAGE_CODE does not exist in PAYPAL_LOCALES, PayPal will use its own language negotiation. + +.. _internationalization coding guidelines: http://edx.readthedocs.io/projects/edx-developer-guide/en/latest/conventions/internationalization/i18n.html +.. _Django's Locale Middleware: https://docs.djangoproject.com/en/2.0/topics/i18n/translation/#how-django-discovers-language-preference +.. _PayPal's country to language mapping: https://developer.paypal.com/docs/classic/api/locale_codes/ +.. _Django documentation for Languages: https://docs.djangoproject.com/en/2.0/ref/settings/#languages + + diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/manage_assets.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/manage_assets.rst new file mode 100644 index 000000000..675825604 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/manage_assets.rst @@ -0,0 +1,48 @@ +.. _Manage Static Assets: + +############################## +Manage Static Assets +############################## + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + + +After you :ref:`configure a partner and at least one site ` for the E-Commerce system to use, you must +compile all static assets and move them to the correct location to be served. +The edX E-Commerce service uses `django-compressor`_ and `RequireJS`_ to manage +static assets. + +* django-compressor compiles and minifies CSS and JavaScript files, + and names files to facilitate cache busting after new file deployment. + +* RequireJS manages JavaScript dependencies. + +.. note:: + + The static file directories are set up so that ``make static`` reads the + build output directory of ``r.js`` before it checks for assets in the + ``ecommerce/static/`` directory. EdX does not recommend that you run ``make + static`` locally. If you run ``make static`` or ``r.js`` locally, make sure + you delete the ``ecommerce/static/build`` folder or that you run ``make + static`` before you continue with development. If you do not run ``make + static`` again, django-compressor ignores all changes that you make to + static files. + +********************************** +Compile and Move Static Assets +********************************** + +To compile and move your static assets and deploy your E-Commerce service, +execute the following command locally or on another server. + +.. code-block:: bash + + $ make static + +If you create new pages that have RequireJS dependencies, remember to add your +new JavaScript modules to the RequireJS build file for the project. This is the +``build.js`` file. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/manage_orders.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/manage_orders.rst new file mode 100644 index 000000000..c23b5afd4 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/manage_orders.rst @@ -0,0 +1,83 @@ +.. _Manage Orders: + +################## +Manage Orders +################## + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + + +EdX has created a framework that manages order placement and fulfillment for +digital products. Most of the products that edX supports involve modifications +to enrollments. + +The edX framework allows modules that fulfill enrollment-related products to +interact with the `edX Enrollment API`_, which is a part of the LMS. This +process can be either synchronous or asynchronous. + + +****************** +Place an Order +****************** + +To place an order, you need the following information. + +* Order number +* User +* Basket +* Shipping method +* Shipping charge +* Billing address +* Order total + +To place an order, use the ``handle_order_placement()`` method that +``EdxOrderPlacementMixin`` provides. If you modify this code, make sure that +the code collects payment before it creates order objects. + +****************** +Fulfill Orders +****************** + +To fulfill orders, emit a ``post_checkout`` signal. An internal fulfillment API +then delegates fulfillment of individual order items to the appropriate +fulfillment modules. + +*************************** +About Fulfillment Modules +*************************** + +The E-Commerce base fulfillment module has the following interface. + +.. code-block:: python + + fulfill_product(product) + + revoke_line(line) + +Every ``ProductType`` has a corresponding module that extends this interface +and fulfills order items of that particular ``ProductType``. To fulfill an +order, the system gives each fulfillment module configured in settings +(``_oscar.py``) an opportunity to fulfill order lines. + +* The ``fulfill_product`` method fulfills the order. For example, + ``fulfill_product`` might enroll a learner in a course or upgrade the learner + to a verified certificate). + +* The ``revoke_line`` method revokes a specific order line. For example, + ``revoke_line`` might unenroll learners from courses or downgrade a learner + from a verified seat. + + + +************************************* +Recover from a Fulfillment Error +************************************* + +If a fulfillment operation fails, the E-Commerce service assigns the order a +status indicating the reason for the failure. If you have enabled asynchronous +order fulfillment, the service tries again to fulfill the order. You can also +manually retry fulfillment of a failed order from the `Oscar`_ order dashboard. + +.. include:: /links.txt + diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/test_ecommerce.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/test_ecommerce.rst new file mode 100644 index 000000000..7549d8444 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/test_ecommerce.rst @@ -0,0 +1,390 @@ +.. _Test ECommerce: + +################################### +Test Your E-Commerce Application +################################### + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + + +To test new applications that you develop for the E-Commerce service, you +create and run tests for the Open edX platform first, and then you run a set of +tests that are specific to E-Commerce. + +******************** +Tests for E-Commerce +******************** + +When you develop E-Commerce applications, you must run a pre-packaged set of +unit tests, Python tests, and E-Commerce acceptance tests. + +============================= +Run E-Commerce Unit Tests +============================= + +The E-Commerce unit tests include migrations, the unit test suite, and quality +checks. You can run the full unit test, or save time for a local test by +disabling the migrations. (You can also run the quality checks independent of +the unit test suite.) + +* To run the full unit test, including migrations and quality checks, use the + following command. + + .. code-block:: bash + + $ make validate + + .. note:: + If numerous unit tests fail with an ``OfflineGenerationError`` message, run + the following command, then try to run unit tests again. + + .. code-block:: bash + + $ DJANGO_SETTINGS_MODULE=ecommerce.settings.test make static + +* To run unit tests with quality checks but without migrations, run the + following command. + + .. code-block:: bash + + $ DISABLE_MIGRATIONS=1 make validate + + .. note:: + We recommend that you only run tests without migrations when you run the + tests locally. + +* To validate code quality independently, run the following command. + + .. code-block:: bash + + $ make quality + + +Python Unit Tests +******************** + +When you create E-Commerce tests, use the ``TestCase`` class in +``ecommerce/tests/testcases.py`` to ensure every test has ``Site`` and +``Partner`` objects configured. This will help you test any code that relies on +these models, which are used for multi-tenancy. + +* To run all Python unit tests and quality checks, run the following command. + + .. code-block:: bash + + $ make validate_python + +* To run all Python unit tests and quality checks *in parallel*, run the + following command. + + .. code-block:: bash + + $ make fast_validate_python + +* To run the Python unit tests in a specific file, such as + ``ecommerce/courses/tests/test_utils.py``, run the following command and + substitute the desired file path. + + .. code-block:: bash + + $ DISABLE_ACCEPTANCE_TESTS=True ./manage.py test + ecommerce.courses.tests.test_utils --settings=ecommerce.settings.test + --with-ignore-docstrings --logging-level=DEBUG + + Setting the DISABLE_MIGRATIONS variable significantly decreases the time + needed to run tests by creating the test database directly from Django model + definitions as opposed to applying the defined migrations. + + .. code-block:: bash + + $ DISABLE_MIGRATIONS=1 DISABLE_ACCEPTANCE_TESTS=True ./manage.py test + ecommerce.courses.tests.test_utils --settings=ecommerce.settings.test + --with-ignore-docstrings --logging-level=DEBUG + + +JavaScript Unit Tests +********************** + +The E-Commerce project uses `Jasmine`_ for JavaScript unit testing. To create +these tests, place your tests in the ``ecommerce/static/js/test/specs`` +directory, and add a ``_spec`` suffix. For example, your test name may be +``ecommerce/static/js/test/specs/course_list_view_spec.js``. + +All JavaScript code must adhere to standards outlined in the `edX JavaScript Style Guide`_. +These standards are enforced using :ref:`ESLint`. + +* To run all JavaScript unit tests and linting checks, run the following + command. + + .. code-block:: bash + + $ make validate_js + + +=================================== +Run E-Commerce Acceptance Tests +=================================== + +To run specific acceptance tests for the E-Commerce service, you must complete +the following procedures. + +.. contents:: + :depth: 1 + :local: + +Configure the LMS +******************** + +To configure the LMS, follow these steps. + +#. Verify that the following settings in ``/edx/app/edxapp/lms.yml`` are + correct. :: + + "ECOMMERCE_API_URL": "http://localhost:8002/api/v2/" + "ECOMMERCE_PUBLIC_URL_ROOT": "http://localhost:8002" + "JWT_ISSUER": "http://127.0.0.1:8000/oauth2" // Must match the E-Commerce JWT_ISSUER setting + "OAUTH_ENFORCE_SECURE": false + "OAUTH_OIDC_ISSUER": "http://127.0.0.1:8000/oauth2" + +#. Verify that the following settings in ``/edx/app/edxapp/lms.yml`` are + correct. :: + + "ECOMMERCE_API_SIGNING_KEY": "insecure-secret-key" // Must match the E-Commerce JWT_SECRET_KEY setting + "EDX_API_KEY": "PUT_YOUR_API_KEY_HERE" // Must match the E-Commerce EDX_API_KEY setting + +#. Verify that an LMS account with staff and superuser permissions exists. + + By default, most devstack and fullstack LMS instances include a user + account that has staff permissions. This account has the username + ``staff``, the email address ``staff@example.com``, and the password + ``edx``. Run the following commands to grant the account superuser + permissions. + + .. code:: sh + + cd ~/edx-platform + ./manage.py lms set_superuser staff --settings=devstack + + + .. the ecomm version has these commands for granting superuser permissions + .. to the account: + + .. ./manage.py lms shell --settings=devstack + from django.contrib.aut.models import User + u = User.objects.get(username-'staff') + u. is_superuser = True + u.save() + +#. Navigate to the OAuth2 Clients section of the Django administration console + (e.g. http://localhost:8000/admin/oauth2/client/). Sign in using the + superuser account you created earlier. + + Verify that an OAuth2 client with the following attributes exists. If one + does not already exist, :ref:`create a new OAuth 2 client `. + + The client ID and secret must match the values of the E-Commerce + ``SOCIAL_AUTH_EDX_OIDC_KEY`` and ``SOCIAL_AUTH_EDX_OIDC_SECRET`` settings, + respectively. :: + + Name: ecommerce + URL: http://localhost:8002/ + Redirect URI: http://localhost:8002/complete/edx-oidc/ + Client ID: 'ecommerce-key' + Client Secret: 'ecommerce-secret' + Client Type: Confidential (Web applications) + Logout url: http://localhost:8002/logout/ + +#. Navigate to the Edx\_Oauth2\_Provider Trusted clients section of the Django + administration console (http://localhost:8000/admin/edx_oauth2_provider/trustedclient/). + + Verify that the OAuth2 client referred to above is designated as a + trusted client (look for the Redirect URI). If this isn't already + the case, add the client created above as a new trusted client. + +#. In the Django administration panel, create a new access token for + the superuser account. Set the client to the OAuth2 client referred + to above. Make note of this token; it is required to run the + acceptance tests. + +#. Make sure that the LMS instance that you will use for testing has at least + two courses that learners can enroll in. By default, most LMS instances + include the edX demonstration course. Use Studio to create a second course. + + +Configure E-Commerce +******************** + +You use the E-Commerce Course Administration Tool ("ECAT") to finish +configuring the two courses in your LMS instance. + +#. Become the ``ecommerce`` user. + + .. code:: sh + + sudo su ecommerce + +#. Verify that the following keys in ``/edx/etc/ecommerce.yml`` match your + settings in ``/edx/app/edxapp/lms.yml`` and + ``/edx/app/edxapp/lms.yml``. + + * One of the ``JWT_AUTH:JWT_ISSUERS`` entries should match + ``/edx/app/edxapp/lms.yml:JWT_ISSUER``. The default value is + ``http://127.0.0.1:8000/oauth2``. + * ``JWT_AUTH:JWT_SECRET_KEY`` should match + ``/edx/app/edxapp/lms.yml:ECOMMERCE_API_SIGNING_KEY``. The default + value is ``lms-secret``. + * ``EDX_API_KEY`` should match + ``/edx/app/edxapp/lms.yml:EDX_API_KEY``. The default value is + ``PUT_YOUR_API_KEY_HERE``. + +#. Set up the E-Commerce environment. + + .. code:: sh + + cd /edx/app/ecommerce/ecommerce + source ../ecommerce_env + source ../venvs/ecommerce/bin/activate + make requirements + make static + make migrate + +#. Create a new site linking to the LMS. + + .. code:: sh + + ./manage.py create_or_update_site \ + --site-id=1 \ + --site-domain=localhost:8002 \ + --partner-code=edX \ + --partner-name='Open edX' \ + --lms-url-root=http://localhost:8000 \ + --theme-scss-path=sass/themes/edx.scss \ + --payment-processors=cybersource,paypal \ + --client-id=ecommerce-key \ + --client-secret=ecommerce-secret \ + --from-email staff@example.com + +#. Start the E-Commerce Django development server. + + .. code:: sh + + ./manage.py runserver 0.0.0.0:8002 + +#. Get the course key from the LMS by navigating to a course and examining its + URL. The course key should look something like + ``course-v1:edX+DemoX+Demo_Course``. + +#. Navigate to the E-Commerce Courses page (http://localhost:8002/courses/) to + add the two test courses that are on your LMS instance to E-Commerce. Configure + one course as a "Free (Audit)" course, and the second as a "Verified" course. + +#. To configure the "Verified" course, click **Add New Course**. Leave the + default values in all fields, with the exception of the following fields. + + :: + + Course ID: The course key from the LMS + Course Name: Use any name + Course Type: Verified + Include Honor Seat: No + +#. Navigate to the learner dashboard (e.g. http://localhost:8000/dashboard) and + confirm that the course you added in E-Commerce now has a green "Upgrade to + Verified" badge, which you can select. + +#. In the ECAT, add the second course on your LMS instance to E-Commerce. + Specify its course type as ``Free (Audit)``. + +#. To test integration with external payment processors, update the contents + of the ``PAYMENT_PROCESSOR_CONFIG`` dictionary found in the settings with + valid credentials. To override the default values for development, create a + private settings module, ``private.py``, and set + ``PAYMENT_PROCESSOR_CONFIG`` inside the module. + + .. note:: + If you created a ``private.py`` file to create settings overrides when you + :ref:`set up your virtual environment `, you + can use that same ``private.py`` file. + +.. _Configure Acceptance Tests: + + +Configure Acceptance Tests +********************************* + +You configure acceptance tests by using the settings in the ``e2e/config.py`` +file. You can use the default values for most settings in this file. However, +for the following settings, you must specify values using environment +variables. + + .. ecomm version has this file path instead: + .. ecommerce/blobmaster/acceptance_tests/config.py + +.. list-table:: + :widths: 30 60 + :header-rows: 1 + + * - Variable + - Description + * - ACCESS_TOKEN + - The OAuth2 access token used to authenticate requests. + * - ECOMMERCE_URL_ROOT + - The URL root for the E-Commerce service. + * - LMS_URL_ROOT + - The URL root for the LMS. + * - LMS_USERNAME + - A username for any current LMS user, to use during testing. + * - LMS_EMAIL + - The email address used to sign in to the LMS. + * - LMS_PASSWORD + - The password used to sign in to the LMS. + +If you test PayPal integration, you must also specify values for the following +settings by using environment variables. + +.. list-table:: + :widths: 30 60 + :header-rows: 1 + + * - Variable + - Description + * - PAYPAL_EMAIL + - The email address used to sign in to PayPal during payment. + * - PAYPAL_PASSWORD + - The password used to sign in to PayPal during payment. + + + +Run Acceptance Tests +****************************** + +Run all acceptance tests by executing ``make e2e``. + + .. ecomm version has ``make accept``? + +To run a specific test, execute the following command. + +.. code-block:: bash + + $ nosetests -v + +The acceptance tests rely on the :ref:`environment variables that you have +configured `. For example, when you run the +acceptance tests against local instances of E-Commerce and the LMS, you might +run the following command, replacing values between angle brackets (<>) with +your own values. + +:: + + $ ECOMMERCE_URL_ROOT="http://localhost:8002" LMS_URL_ROOT="http://127.0.0.1:8000" LMS_USERNAME="" LMS_EMAIL="" LMS_PASSWORD="" ACCESS_TOKEN="" LMS_HTTPS="False" LMS_AUTO_AUTH="True" PAYPAL_EMAIL="" PAYPAL_PASSWORD="" ENABLE_CYBERSOURCE_TESTS="False" VERIFIED_COURSE_ID="" make e2e + +When you run the acceptance tests against a production-like staging +environment, you might run the following command. + +:: + + $ ECOMMERCE_URL_ROOT="https://ecommerce.stage.edx.org" LMS_URL_ROOT="https://courses.stage.edx.org" LMS_USERNAME="" LMS_EMAIL="" LMS_PASSWORD="" ACCESS_TOKEN="" LMS_HTTPS="True" LMS_AUTO_AUTH="False" PAYPAL_EMAIL="" PAYPAL_PASSWORD="" BASIC_AUTH_USERNAME="" BASIC_AUTH_PASSWORD="" HONOR_COURSE_ID="" VERIFIED_COURSE_ID="" make e2e + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/ecommerce-deprecated/theming.rst b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/theming.rst new file mode 100644 index 000000000..48743944a --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-deprecated/theming.rst @@ -0,0 +1,312 @@ +.. _Comprehensive Theming: + +###################### +Comprehensive Theming +###################### + +.. warning:: + This service is deprecated and was last tagged for the Redwood release. We are not fixing bugs or developing new features for it. For updates, `follow along on the DEPR ticket `_ + + +Any application, including Otto, can be loosely divided into two parts: + +* the user interface ("how it looks"), and +* the application logic ("how it works"). + +Considerations of the Otto user interface include, for example, how the +products are laid out on the page, how the selectors look, how the checkout +button is labelled, what sort of fonts and colors are used to display the +text, and so on. Considerations of Otto's application logic includes how Otto +adjusts product price based on discount coupons, and how it records that +information to be displayed in the future. + +Theming consists of changing the user interface without changing the +application logic. When you set up an E-Commerce website for use with your +Open edX site, you probably want to use your organization's own logo, modify +the color scheme, change links in the header and footer for SEO (search engine +optimization) purposes, and so on. + +However, although the user interface might look different, the application +logic must remain the same so that Otto continues to work properly. A well- +designed theme preserves the general layout and structure of the user +interface, so that users of the website still find it familiar and easy to +use. Be careful about making sweeping changes to the user interface without +warning: your users will be very confused! + +The default Open edX theme is named "Comprehensive Theming". You can disable +Comprehensive Theming by setting ``ENABLE_COMPREHENSIVE_THEMING`` to +``False``, as shown in this example, then applying your custom theme. + + .. code-block:: python + + ENABLE_COMPREHENSIVE_THEMING = False + + +.. contents:: + :local: + :depth: 1 + +*************** +Theme Structure +*************** + +From a technical perspective, theming consists of overriding core templates, +static assets, and Sass with themed versions of those resources. + +Every theme must conform to a directory structure that mirrors the Otto directory structure. + +.. code-block:: text + + my-theme + ├── README.rst + ├── static + | └── images + | | └── logo.png + | | + | └── sass + | └── partials + | └── utilities + | └── _variables.scss + | + └── templates + └── oscar + | └── dashboard + | └── index.html + └── 404.html + + +========= +Templates +========= + +Any template included in ``ecommerce/templates`` directory can be "themed". +However, make sure not to override class names or ID values of HTML elements +within a template, as these are used by JavaScript or CSS. Overriding these +names and values can cause unwanted behavior. + +================== +Static Assets +================== + +Any static asset included in ``ecommerce/static`` can be overridden except for +the CSS files in the ``ecommerce/static/css`` directory. CSS styles can be +overridden via Sass overrides explained below. + +.. caution:: Theme names must be unique. The names of static assets or + directories must not be same as the theme's name, otherwise static assets + will not work correctly. + +===== +Sass +===== + +Sass overrides are a little different from static asset or template overrides. +There are two types of styles included in ``ecommerce/static/sass``: + +* base +* partials + +.. caution:: Styles present in ``ecommerce/static/sass/base`` should not be + overridden as overriding these could result in an unexpected behavior. + +Any styles included in ``ecommerce/static/sass/partials`` can be overridden. +Styles included in this directory contain variable definitions that are used +by main Sass files. Elements of the user interface such as header/footer, +background, fonts, and so on, can be updated in this directory. + + +***************** +Enabling a Theme +***************** + +To enable a theme, you must first install your theme onto the same server that +is running Otto. If you are using devstack or fullstack to run Otto, you must +be sure that the theme is present on the Vagrant virtual machine. It is up to +you where to install the theme on the server, but a good default location is +``/edx/app/ecommerce/ecommerce/themes``. + +.. note:: All themes must reside in the same physical directory. + +In order for Otto to use the installed themes, you must specify the location +of the theme directory in Django settings by defining +``COMPREHENSIVE_THEME_DIRS`` in your settings file, as shown in the example, +where ``/edx/app/ecommerce/ecommerce/themes`` is the path to where you have +installed the themes on your server. + +.. code-block:: python + + COMPREHENSIVE_THEME_DIRS = ["/edx/app/ecommerce/ecommerce/themes", ] + +You can list all theme directories using this setting. + +After you install a theme, you associate it with your site by adding appropriate +entries to the following tables. + +* ``Site`` +* ``Site Themes`` + +For local devstack, if the Otto server is running at ``localhost:8002`` you can +enable a ``my-theme`` by following these steps. + +#. Add a new site with the domain ``localhost:8002`` and the name "Otto My Theme". + +#. Add a site theme with the theme dir name ``my-theme``, selecting + ``localhost:8002`` from the ``site`` dropdown. + +The Otto server can now be started, and you should see that ``my-theme`` has +been applied. If you have overridden Sass styles and you are not seeing those +overrides, then you need to compile Sass files as described in `Compiling +Theme Sass`_. + +****************** +Disabling a Theme +****************** + +A theme can be disabled by removing its corresponding ``Site Theme`` entry +using django admin. + +======================================= +Creating or Updating Site and SiteTheme +======================================= + +If you have already set up ``COMPREHENSIVE_THEME_DIRS``, you can use the +management command for adding ``Site`` and ``SiteTheme`` directly from the +terminal. + +.. code-block:: Bash + + python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-name=localhost:8002 --site-theme=my-theme + +The ``create_or_update_site_theme`` command accepts the following optional +arguments, listed below with examples. + +* settings: The settings file to use. The default file is + ``ecommerce.settings.devstack``. + +.. code-block:: Bash + + python manage.py create_or_update_site_theme --settings=ecommerce.settings.production + +* site-id: The ID of the site that you want to update. + +.. code-block:: Bash + + # update domain of the site with id 1 and add a new theme + # ``my-theme`` for this site + python manage.py create_or_update_site_theme --site-id=1 --site-domain=my-theme.localhost:8002 --site-name=my-theme.localhost:8002 --site-theme=my-theme + +* site-domain: The domain of the site to be created. + +.. code-block:: Bash + + python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-theme=my-theme + +* site-name: The name of the site to be created. The default setting is ``''``. + +.. code-block:: Bash + + python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-name=localhost:8002 --site-theme=my-theme + +* site-theme: The theme dir for the new theme. + +.. code-block:: Bash + + python manage.py create_or_update_site_theme --site-domain=localhost:8002 --site-name=localhost:8002 --site-theme=my-theme + + +===================== +Compiling Theme Sass +===================== + +You use the management command ``update_assets`` to compile and collect themed +Sass. + +.. code-block:: yaml + + python manage.py update_assets + +The ``update_assets`` command accepts the following optional arguments, listed +below with examples. + +* settings: The settings file to use. The default file is + ``ecommerce.settings.devstack``. + +.. code-block:: Bash + + python manage.py update_assets --settings=ecommerce.settings.production + +* themes: The space-separated list of themes to compile Sass for. Possible + options are ``all`` for all themes, ``no`` to skip Sass compilation for + themes. The default option is ``all``. + +.. code-block:: Bash + + # compile Sass for all themes + python manage.py update_assets --theme=all + + # compile Sass for only given themes, useful for situations if you have + # installed a new theme and want to compile Sass for just this theme + + python manage.py update_assets --themes my-theme second-theme third-theme + + # skip Sass compilation for themes, useful for testing changes to system + # Sass, keeping theme styles unchanged + + python manage.py update_assets --theme=no + +* output-style: The coding style for compiled CSS files. Possible options are + ``nested``, ``expanded``, ``compact`` and ``compressed``. The default option + is ``nested``. + +.. code-block:: Bash + + python manage.py update_assets --output-style='compressed' + +* skip-system: This flag disables system Sass compilation. + +.. code-block:: Bash + + # useful in cases where you have updated theme Sass, and system Sass is + # unchanged. + + python manage.py update_assets --skip-system + +* enable-source-comments: This flag enables source comments in generated CSS + files. + +.. code-block:: Bash + + python manage.py update_assets --enable-source-comments + +* skip-collect: Use this flag to skip the ``collectstatic`` call after Sass + compilation. + +.. code-block:: Bash + + # useful if you just want to compile Sass, and call ``collectstatic`` later, + # possibly by a script + + python manage.py update_assets --skip-collect + + +****************** +Troubleshooting +****************** + +If you have gone through the preceding procedures and you are not seeing theme +overrides, check the following areas. + + +* ``COMPREHENSIVE_THEME_DIRS`` must contain the path for the directory + containing themes. For example, if your theme is + ``/edx/app/ecommerce/ecommerce/themes/my- theme`` then the correct value + for ``COMPREHENSIVE_THEME_DIRS`` is + ``['/edx/app/ecommerce/ecommerce/themes']``. + +* The ``domain`` name for site is the name that users will put in the browser + to access the site, and includes the port number. For example, if Otto is + running on ``localhost:8002`` then the value for ``domain`` should be + ``localhost:8002``. + +* The theme dir name is the name of the directory of your theme. For example, + for our ongoing example, ``my-theme`` is the correct theme dir name. diff --git a/source/site_ops/install_configure_run_guide/ecommerce-solutions.rst b/source/site_ops/install_configure_run_guide/ecommerce-solutions.rst new file mode 100644 index 000000000..c88d956a3 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/ecommerce-solutions.rst @@ -0,0 +1,28 @@ +.. _Adding ECommerce to Open edX: + +Adding ECommerce to Open edX +############################# + +This section is intended for those are who are building Open edX ecommerce +solutions and customizing an Open edX installation to support their use. + +.. contents:: + :local: + :depth: 1 + +Open edX Commerce (WordPress Plugin) +************************************ + +The Open edX WooCommerce Plugin is a free, open-source WordPress plugin that aims to integrate third-party e-commerce, WooCommerce, with your Open edX platform. See the following resources: + +* `Open edX Commerce (WordPress Plugin) Quickstart `_ +* `Open edX Commerce (WordPress Plugin) Source `_ + +Open edX Webhook Receiver +************************* + +The `Open edX Webhook Receiver `_ +extension is a small Django app that listens for incoming webhooks, and then +translates those into calls against the Open edX REST APIs. + +As of Sumac it supports WooCommerce and Shopify endpoints. \ No newline at end of file diff --git a/source/site_ops/install_configure_run_guide/feature_flags/feature_flag_index.rst b/source/site_ops/install_configure_run_guide/feature_flags/feature_flag_index.rst new file mode 100644 index 000000000..eec43e11c --- /dev/null +++ b/source/site_ops/install_configure_run_guide/feature_flags/feature_flag_index.rst @@ -0,0 +1,9 @@ +.. _Feature Flag Index: + +############################### +Index of Open edX Feature Flags +############################### + +For more information abut feature flags, see :doc:`edx-platform:references/featuretoggles`. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/front_matter/browsers.rst b/source/site_ops/install_configure_run_guide/front_matter/browsers.rst new file mode 100644 index 000000000..60cf6fcb7 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/front_matter/browsers.rst @@ -0,0 +1,5 @@ +######################## +Open edX Browser Support +######################## + +See :ref:`Browsers` \ No newline at end of file diff --git a/source/site_ops/install_configure_run_guide/front_matter/getting_help.rst b/source/site_ops/install_configure_run_guide/front_matter/getting_help.rst new file mode 100644 index 000000000..f687c2163 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/front_matter/getting_help.rst @@ -0,0 +1,51 @@ +.. _Getting Help: + +############ +Getting Help +############ + +This section describes resources for getting help if you need technical +assistance during the installation process or after your site is running. + + +****************** +Where to Find Help +****************** + +There are a number of places to get help, including mailing lists and real-time +chat. Please choose an appropriate venue for your question. This helps ensure +that you get good prompt advice, and keeps discussion focused. For details of +your options, see the `Getting Help page`_. + + +******************************************* +Information to Provide When Asking for Help +******************************************* + +Keep in mind when asking for help that you have much more knowledge of your +situation than others do. You need to provide that context so that people can +understand your problem and provide good help. +To make it easier for others to help you, please provide the following types of +information. + +* **What you are trying to do?** What version of the code are you installing, + and why? What is your larger goal? + +* **What you have done?** What instructions were you following? What commands + did you run? Did you deviate from the instructions at any point, even a + little bit? Full output of those commands, even if it seems overwhelming, + can be very useful. + +* **What has gone wrong?** Are there errors in log files? Did you get specific + failures in the terminal? Provide full details about the undesired results + you saw. + +While working through your problem, helpers often need additional information. +Stay involved in the discussion, and try to give them what they need. They know +best what information they need to solve the problem. + + +.. _Getting Help page: https://open.edx.org/getting-help +.. _openedx-ops: http://groups.google.com/forum/#!forum/openedx-ops + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/front_matter/index.rst b/source/site_ops/install_configure_run_guide/front_matter/index.rst new file mode 100644 index 000000000..bbc7dda3d --- /dev/null +++ b/source/site_ops/install_configure_run_guide/front_matter/index.rst @@ -0,0 +1,11 @@ +############################# +General Information +############################# + +.. toctree:: + :maxdepth: 2 + + read_me + getting_help + browsers + diff --git a/source/site_ops/install_configure_run_guide/front_matter/read_me.rst b/source/site_ops/install_configure_run_guide/front_matter/read_me.rst new file mode 100644 index 000000000..26ac91ddf --- /dev/null +++ b/source/site_ops/install_configure_run_guide/front_matter/read_me.rst @@ -0,0 +1,11 @@ +######### +Read Me +######### + +The *Installing and Configuring the Open edX Platform* documentation is created +using RST_ files and Sphinx_. As a member of the community, you can help update +and revise this documentation project on GitHub. + +See the :ref:`Documentor's Home` for more information on how to contribute to the docs! + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/index.rst b/source/site_ops/install_configure_run_guide/index.rst new file mode 100755 index 000000000..7fd7623de --- /dev/null +++ b/source/site_ops/install_configure_run_guide/index.rst @@ -0,0 +1,45 @@ +.. _Installing, Configuring, and Running the Open edX Platform: + +########################################################### +Installing, Configuring, and Running the Open edX Platform +########################################################### + +This guide provides instructions for using your own instance of the Open edX +platform and associated applications. + +The most recent Open edX release will be found on the :ref:`Open edX Release Notes`. +It is strongly recommended to use `Tutor`_ for both development and installation. +It is also recommended to stay up-to-date with the latest Open edX release, as +previous releases are unsupported by the community. See the `Open edX Release Schedule`_ +for information on release dates and end-of-life support. + +You *can* install any release of the Open edX platform, but note the community +will likely be unable to answer questions about issues you encounter. Please be +aware that older releases do not receive security fixes or any of the latest features, +and documentation on docs.openedx.org will always reflect the latest release. + +release. + +.. toctree:: + :maxdepth: 2 + + front_matter/index + platform_releases/index + installation/index + configuration/index + analytics/index + ecommerce-solutions + mobile + feature_flags/feature_flag_index + /glossary + +.. hide outdated materials, but don't remove so links still work + +.. toctree:: + :hidden: + + ecommerce-deprecated/index + insights/index + mobile-deprecated + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/insights/elastic_mapreduce.rst b/source/site_ops/install_configure_run_guide/insights/elastic_mapreduce.rst new file mode 100644 index 000000000..41fa2d982 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/insights/elastic_mapreduce.rst @@ -0,0 +1,402 @@ +.. _Using Elastic MapReduce on AWS: + +****************************************** +Using Elastic MapReduce on AWS +****************************************** + +.. note:: + + The edX Insights service is deprecated and no longer supported by the Open + edX community. Please see :ref:`Open edX Analytics Options` for other ways + of running analytics on your Open edX instance. + +This topic provides an overview of the components and services that you set up +and configure in a deployment that uses Amazon EMR. Work to prepare complete +installation procedures for edX Insights is in progress. + +.. contents:: + :local: + :depth: 1 + +For more information about AWS, including detailed procedures, see the `AWS +Documentation`_. + +.. important:: + The tasks described by this topic rely on the use of third-party services and + software. Because the services and software are subject to change by their + owners, the information provided here is intended as a guideline and not as + exact procedures. + +====================== +Virtual Private Cloud +====================== + +Create a Virtual Private Cloud (VPC) with at least one public subnet. A +limitation of EMR running in a VPC is that clusters must be deployed into +public subnets of VPCs. An existing VPC can be used if one is already available +for use. + +EdX recommends that you configure the VPC to have at least one private subnet +in addition to the required public subnet. A private subnet is not required. +For more information, see the `example configuration scenario`_ +in the *Amazon Virtual Private Cloud User Guide* published by AWS. + +An example configuration that includes only `a single public subnet`_ +can also be found in the *Amazon Virtual Private Cloud User Guide*. + +Other Considerations +********************* + +* To take advantage of price fluctuations in the `spot pricing market`_ , you + can also deploy several public subnets in different availability zones. + +* Consider that the clusters deployed using EMR will need network connectivity + to a read replica of the LMS database. EdX recommends that you use the same + VPC as the LMS if possible. + +* While it is possible to run all of these services outside of a VPC, edX does + not recommend doing so. + +=============================== +Identity and Access Management +=============================== + +For Amazon Identity and Access Management (IAM), create an IAM role for use +by the EMR cluster. Assign all of the Elastic Compute Cloud (EC2) nodes in +the cluster to this role. An option is to consider copying the contents of the +`default IAM roles for Amazon EMR`_ used by AWS. The command +``aws emr create-default-roles`` facilitates this task. For more information, +see `default IAM roles for Amazon EMR`_. + +Also, you need to create a role named ``emr`` with the policy +``AmazonElasticMapReduceforEC2Role`` for the EC2 instance profile. + +Make sure that an IAM user with administrative privileges is available for use. + +================= +SSH Credentials +================= + +Generate a secure SSH key that you use to access all AWS resources. For +example, run the following command. + + .. code-block:: bash + + ssh-keygen -t rsa -C "your_email@example.com" + +Upload the public key from the SSH key pair to AWS and assign a key pair +name to it. + +====================== +Elastic Compute Cloud +====================== + +Ensure that at least one Amazon Elastic Compute Cloud (EC2) instance is +available to host the various services. Depending on the scale of your +deployment, additional instances might be necessary. + +Make sure to use the secure key pair name to deploy all of the EC2 instances. + +============================== +Relational Database Service +============================== + +Deploy a MySQL 5.6 Relational Database Service (RDS) instance. This RDS +instance is the result store. + +Connectivity +*************** + +Ensure that there is connectivity between the EC2 instance that hosts +the edX Analytics API and your RDS instance. + +Also, ensure that instances deployed into the public subnet of the VPC +can connect to your RDS instance. + +Users +*********** + +Create at least the following two users on the RDS instance. + +* The "pipeline" user must have permission to create databases, tables, and + indexes, and issue arbitrary Data Manipulation Language (DML) commands. + +* The "api" user must have read-only access. + +Configure passwords for both of these users. + +Other Considerations +********************* + +Configure the RDS instance to use "utf8_bin" collation by default for +columns in all databases and tables. + +================================== +Scheduler Service +================================== + +Establish an SSH connection to the EC2 instance within the VPC that will +run the scheduler service. Then, issue the following commands from a shell +running on that instance. + +#. Check out the sources files from `edx-analytics-configuration`_. + + .. code-block:: bash + + git clone https://github.com/openedx/edx-analytics-configuration.git + +#. Configure the shell to use the AWS credentials of the administrative AWS + user. + + .. code-block:: bash + + export AWS_ACCESS_KEY_ID= + export AWS_SECRET_ACCESS_KEY= + +#. Install the `AWS Command Line Interface`_. + + .. code-block:: bash + + pip install awscli + +================================== +Simple Storage Solution Buckets +================================== + +Create a Simple Storage Solution (S3) bucket to hold all Hadoop logs from +the EMR cluster. + + .. code-block:: bash + + aws s3 mb s3:// + +Then, create an S3 bucket to hold secure configuration files and +initialization scripts. + + .. code-block:: bash + + aws s3 mb s3:// + +========================= +MySQL Connector Library +========================= + +Download the `MySQL connector library`_ from Oracle. After the download is +complete, you then upload it to S3. + + .. code-block:: bash + + aws s3 cp /tmp/mysql-connector-java-5.1.*.tar.gz s3:/// + +The ``edx-analytics-configuration/batch/bootstrap/install-sqoop`` script +references a specific version of the MySQL connector library. Update this +``install-sqoop`` script to point to the correct version of the library in the +S3 bucket. You must update the script before you continue. + +Then, upload the contents of the ``edx-analytics-configuration/batch/bootstrap/`` directory into your configuration bucket. + + .. code-block:: bash + + aws s3 sync edx-analytics-configuration/batch/bootstrap/ s3:/// + +========================== +Cluster Configuration File +========================== + +Create a cluster configuration file to specify the parameters for the EMR +cluster. Review the parameters that follow, and change them to specify your +desired configuration. For example, review the ``core`` and ``task`` mappings +and change the values for ``bidprice`` and ``type`` to meet your needs. + +Then, save this file to a temporary location such as ``/tmp/cluster.yml``. + + .. code-block:: yaml + + { + name: , + keypair_name: , + vpc_subnet_id: , + log_uri: "s3://", + instance_groups: { + master: { + num_instances: 1, + type: m3.xlarge, + market: ON_DEMAND, + }, + core: { + num_instances: 2, + type: m3.xlarge, + market: SPOT, + bidprice: 0.8 + }, + task: { + num_instances: 1, + type: m3.xlarge, + market: SPOT, + bidprice: 0.8 + } + }, + release_label: emr-4.7.2, + applications: [ {name: Hadoop}, {name: Hive}, {name: Sqoop-Sandbox}, {name: Ganglia} ], + steps: [ + { + type: script, + name: Install MySQL connector for Sqoop, + step_args: [ "s3:///install-sqoop", "s3://" ], + # You might want to set this to CANCEL_AND_WAIT while debugging step failures. + action_on_failure: TERMINATE_JOB_FLOW + } + ], + configurations: [ + { + classification: mapred-site, + properties: + { + mapreduce.framework.name: 'yarn', + mapreduce.jobtracker.retiredjobs.cache.size: '50', + mapreduce.reduce.shuffle.input.buffer.percent: '0.20', + } + }, + { + classification: yarn-site, + properties: + { + yarn.resourcemanager.max-completed-applications: '5' + } + } + ], + user_info: [] + } + + +You might find you need to update Hadoop instance types and container +sizes. In particular, if you encounter jobs that are running out of +physical memory, you might want to choose a larger instance. If your +instance is a good size but being underutilized, you might want to +explicitly define larger values in the "mapred-site" configuration +than would be provided by default in the instance size you are +using. Here is an example of settings we use with an m3.2xlarge +instance type. + + .. code-block:: yaml + + { + classification: mapred-site, + properties: + { + mapreduce.framework.name: 'yarn', + mapreduce.jobtracker.retiredjobs.cache.size: '50', + mapreduce.reduce.shuffle.input.buffer.percent: '0.20', + mapreduce.map.java.opts: '-Xmx2458m', + mapreduce.reduce.java.opts: '-Xmx4916m', + mapreduce.map.memory.mb: '3072', + mapreduce.reduce.memory.mb: '6144' + } + } + + +============ +EMR Cluster +============ + +Deploy the EMR cluster. + + .. code-block:: bash + + EXTRA_VARS="@/tmp/cluster.yml" make provision.emr + +Example Output +*************** + + :: + + pip install -q -r requirements.txt + + ansible-playbook --connection local -i 'localhost,' batch/provision.yml -e "$EXTRA_VARS" + + PLAY [Provision cluster] ****************************************************** + + TASK: [provision EMR cluster] ************************************************* + changed: [localhost] + + TASK: [add master to group] *************************************************** + ok: [localhost] + + TASK: [display master IP address] ********************************************* + ok: [localhost] => { + "msg": "10.0.1.236" + } + + TASK: [display job flow ID] *************************************************** + ok: [localhost] => { + "msg": "j-29UUJVM8P1NPY" + } + + PLAY [Configure SSH access to cluster] **************************************** + + TASK: [user | debug var=user_info] ******************************************** + ok: [10.0.1.236] => { + "item": "", + "user_info": [] + } + + TASK: [user | create the edxadmin group] ************************************** + changed: [10.0.1.236] + + TASK: [user | ensure sudoers.d is read] *************************************** + changed: [10.0.1.236] + + TASK: [user | grant full sudo access to the edxadmin group] ******************* + changed: [10.0.1.236] + + TASK: [user | create the users] *********************************************** + skipping: [10.0.1.236] + + TASK: [user | create .ssh directory] ****************************************** + skipping: [10.0.1.236] + + TASK: [user | assign admin role to admin users] ******************************* + skipping: [10.0.1.236] + + TASK: [user | copy github key[s] to .ssh/authorized_keys] ******************** + skipping: [10.0.1.236] + + TASK: [user | create bashrc file for normal users] **************************** + skipping: [10.0.1.236] + + TASK: [user | create .profile for all users] ********************************** + skipping: [10.0.1.236] + + TASK: [user | modify shell for restricted users] ****************************** + skipping: [10.0.1.236] + + TASK: [user | create bashrc file for restricted users] ************************ + skipping: [10.0.1.236] + + TASK: [user | create sudoers file from template] ****************************** + changed: [10.0.1.236] + + TASK: [user | change home directory ownership to root for restricted users] *** + skipping: [10.0.1.236] + + TASK: [user | create ~/bin directory] ***************************************** + skipping: [10.0.1.236] + + TASK: [user | create allowed command links] *********************************** + skipping: [10.0.1.236] + + PLAY RECAP ******************************************************************** + 10.0.1.236 : ok=0 changed=4 unreachable=0 failed=0 + localhost : ok=4 changed=1 unreachable=0 failed=0 + +Additional Tasks +================= + +To complete the EMR configuration, additional configuration and automation +procedures are required, including scheduling jobs and automating log +duplication. For more information, see the `edX Analytics Installation`_ wiki +page. + + +.. include:: /links.txt + diff --git a/source/site_ops/install_configure_run_guide/insights/index.rst b/source/site_ops/install_configure_run_guide/insights/index.rst new file mode 100644 index 000000000..a2f994b4f --- /dev/null +++ b/source/site_ops/install_configure_run_guide/insights/index.rst @@ -0,0 +1,28 @@ +.. _Adding edX Insights: + +##################################### +Adding edX Insights (Deprecated) +##################################### + +.. note:: + + The edX Insights service is deprecated and no longer supported by the Open + edX community. Please see :ref:`Open edX Analytics Options` for other ways + of running analytics on your Open edX instance. + +The following topics provide information about installing, configuring, and +running edX Insights and its dependencies in a production environment. + +.. toctree:: + :maxdepth: 1 + + install_insights + elastic_mapreduce + +Work to prepare complete installation procedures for edX Insights is in +progress. This section presents the introductory, overview material that is +available now. + + +.. include:: /links.txt + diff --git a/source/site_ops/install_configure_run_guide/insights/install_insights.rst b/source/site_ops/install_configure_run_guide/insights/install_insights.rst new file mode 100644 index 000000000..a5601f63e --- /dev/null +++ b/source/site_ops/install_configure_run_guide/insights/install_insights.rst @@ -0,0 +1,247 @@ +.. _Installing edX Insights: + +################################################# +Options for Installing edX Insights (Deprecated) +################################################# + +.. note:: + + The edX Insights service is deprecated and no longer supported by the Open + edX community. Please see :ref:`Open edX Analytics Options` for other ways + of running analytics on your Open edX instance. + +This topic is intended for those who are interested in running `edX Insights`_ +and its dependencies in a production environment. This topic does not provide +complete installation procedures for edX Insights. It presents the introductory +material that is available now. + +.. contents:: + :local: + :depth: 1 + +******** +Overview +******** + +Course teams use edX Insights to access data gathered from active courses. In +edX Insights, course teams can display charts, summary statistics, and data +tables. + +The Learning Management System (LMS) gathers data about learner activity. This +data is aggregated by the edX Analytics Pipeline. The aggregated data is +exposed by the edX Analytics Data API. EdX Insights reads the data from the edX +Analytics Data API and presents the data to course team members. + +======================== +Architecture Diagram +======================== + +.. image:: ../Images/Analytics_Pipeline.png + :alt: Image showing the relationships between various components of the edX + analytics data pipeline. + :width: 800 + +========== +Components +========== + +.. contents:: + :local: + :depth: 1 + +LMS +*** + +The LMS records learner actions in tracking log files. The standard +``logrotate`` utility periodically compresses and copies these files into a +file system that can be read by the edX Analytics Pipeline. The LMS also +captures a lot of information in a MySQL database. The edX Analytics Pipeline +connects directly to this database to extract information about learners. + +edX Analytics Pipeline +********************** + +The edX Analytics Pipeline reads the MySQL database used by the LMS as well as +the tracking log files produced by the LMS. The data is processed and the +resulting summary data is published to the result store. The result store is a +MySQL database. + +Requirements +============ + +* `Hadoop `_ version 1.0.3 or higher +* `Hive `_ version 0.11.0.2 or higher +* `Sqoop `_ version 1.4.5 +* Python 2.7 +* Either Debian version 6.0 or higher, or Ubuntu version 12.04 or higher +* A MySQL server version 5.6 or higher + +Scheduler +********* + +The Scheduler schedules the execution of data computation tasks. Data +computation tasks are run by the edX Analytics Pipeline. Data computation tasks +are used to update parts of the result store. + +edX Analytics Data API +********************** + +The ref:`opendataapi:edX Analytics Data API` +provides an HTTP interface for accessing data in the result store. Typically, +the data in the result store is updated periodically by the edX Analytics +Pipeline. + +Requirements +============ + +Python 2.7 + +edX Insights +************ + +EdX Insights uses the edX Analytics Data API to present data to users. Users +access the data using a supported web browser. EdX Insights communicates +directly with the LMS to authenticate users, authorize users, and read course +structure information. + +Requirements +============ + +Python 2.7 + +************************************* +What You Should Know Before You Start +************************************* + +To install edX Insights and deploy the edX Analytics Pipeline, you must +understand the following concepts. + +* Basic terminal usage. +* How the LMS has been deployed and configured. +* Basic computer network terminology. +* YAML file format. + +If you plan to use Amazon Web Services, an understanding of AWS terminology is +also required. + +************************ +Planning Your Deployment +************************ + +All edX Analytics services are designed to be relocatable. This means that they +do not require a particular configuration of virtual servers. You are free to +choose how the services should be distributed among the resources you have +available. + +====== +Hadoop +====== + +Most of the computation performed by the edX Analytics Pipeline is implemented +as Map Reduce jobs that must be executed by a Hadoop cluster. You can scale +your Hadoop cluster based on your current and projected data sizes. Hadoop +clusters can be scaled vertically and horizontally as your data grows. For very +small installations of Open edX, a single virtual server should be sufficiently +powerful to process your data. + +Amazon's `Elastic MapReduce`_ (EMR) service offers preconfigured Hadoop +clusters. If you are able to use Amazon Web Services (AWS), use of this service +is recommended. Proper installation and configuration of Hadoop can be time +consuming. For more information, see :ref:`Using Elastic MapReduce on AWS`. + +Additionally, vendors such as Cloudera and MapR offer simplified Hadoop +administration experiences. + +Hadoop is a distributed system that consists of several different services. It +is worth noting that they are Java services and require a non-trivial amount of +memory to run. The high memory requirement might prevent you from running all +services on the same virtual server if it does not have enough memory +available. + +================ +edX Applications +================ + +The edX Analytics Data API responds to a small number of requests every time a +page is loaded in edX Insights. Small installations can probably host both +services on the same virtual server. Larger installations should consider +hosting the services on more than one virtual server. A load balancer is +recommended for each service that requires more than one virtual server. + +============ +Result Store +============ + +The results of computations performed by the edX Analytics Pipeline are stored +in a MySQL database. Even small installations should use a different MySQL +server than the one used by the LMS. The edX Analytics Pipeline's write +patterns to the result store are more I/O intensive than usual. Placing both +databases on the same server can degrade the performance of the LMS. + +========= +Scheduler +========= + +Scheduling executions of the edX Analytics Pipeline can be accomplished in many +different ways. Any tool that can periodically execute shell commands should +work. The simplest tool that can perform this task is `cron`_. `Jenkins`_ is +also a good candidate. + +.. _cron: http://en.wikipedia.org/wiki/Cron +.. _Jenkins: http://jenkins-ci.org/ + +******************* +Example Deployments +******************* + +.. contents:: + :local: + :depth: 1 + +=================================== +Small Scale Using Elastic MapReduce +=================================== + +A small deployment might consist of a single master node and a single core +node. The Scheduler is deployed to the master node and periodically executes +the edX Analytics Data Pipeline on this server. Additionally, the edX Analytics +API, edX Insights and result store are deployed to the master node. These +services run continuously. For more information, see :ref:`Using Elastic +MapReduce on AWS`. + +=================================== +Large Scale Using Elastic MapReduce +=================================== + +A large scale deployment consists of a single master node, several core nodes, +and many task nodes deployed into a public subnet of a Virtual Private Cloud. + +.. image:: ../Images/Analytics_AWS_Deployment.png + :alt: Image showing all of the AWS components needed to run a large scale + deployment of the edX analytics data pipeline. + +The edX Analytics API and edX Insights are each deployed into an auto-scaling +group behind an Elastic Load Balancer which terminates SSL connections and +distributes the load among the application servers. The application servers are +deployed into a private subnet of the Virtual Private Cloud. A single virtual +server is deployed into a private subnet to host the Scheduler. The Relational +Database Service is used to deploy a MySQL server into a private subnet. The +MySQL database will be used as the result store. For more information, see +:ref:`Using Elastic MapReduce on AWS`. + +=========================================== +Large Scale Without Using Elastic MapReduce +=========================================== + +A large deployment that does not use Elastic MapReduce requires additional +configuration steps to establish a properly configured environment. A Hadoop +cluster is deployed. The master node is considered the node that is running the +Job Tracker service for Hadoop 1.X deployments or the Resource Manager service +for Hadoop 2.X deployments. Hive and Sqoop are deployed to the master node. +Several servers are deployed outside of the Hadoop cluster that host the +remainder of the infrastructure. The edX Analytics API and edX Insights +services are each deployed to at least one server. The Scheduler is deployed to +another server. A MySQL database is deployed to a server that is configured to +host a relational database. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/installation/index.rst b/source/site_ops/install_configure_run_guide/installation/index.rst new file mode 100644 index 000000000..0d34978c3 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/installation/index.rst @@ -0,0 +1,56 @@ +.. _Installing and Starting the Open edX Platform: + +############################################# +Installing and Starting the Open edX Platform +############################################# + +This section provides information about options for installing and +starting the Open edX platform. + +We've tried to simplify the installation by providing a small number of +options, prepackaged to varying degrees. Before installing the Open edX platform, you have +two decisions to make: + +* **Version**: What version of the code do you want? +* **Method**: How do you want to install it? + +******************* +Choose a version +******************* + +There are two possibilities for the version to install: + +* **Master** is the latest version of the code. + +* A **Release** is a version of the code marked and tested for wide use. These + are named alphabetically for trees: Sumac, Teak, Ulmo, etc. Look for the most + recent release if you're beginning a new installation. + +You should choose master only if you will be modifying the code and +contributing it back, or if you need a feature or fix that is newer than the +latest Open edX release. If you aren't planning to contribute changes, and you +don't need the absolute latest code, use the latest official Open edX release. +Details of the releases are on the :ref:`Open edX Release Notes`. + +******************************** +Choose an installation method +******************************** + +**`Tutor`_**: is the community-supported Docker-based environment + suited for both production and development. + + +Note that Tutor requires some foundational skills: + +* Comfort with your chosen operating system. +* Using the command line to perform tasks. +* Some ability to diagnose and solve problems with system software. + +You can find more details on each of the methods below: + +.. toctree:: + :maxdepth: 2 + + tutor + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/installation/tutor.rst b/source/site_ops/install_configure_run_guide/installation/tutor.rst new file mode 100644 index 000000000..4a5f39d84 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/installation/tutor.rst @@ -0,0 +1,12 @@ +.. _Open edX Tutor Installation: + +########################### +Open edX Tutor Installation +########################### + +Tutor is the community-supported installation method as of Lilac. + +In order to avoid unnecessary duplication of information, please refer to the +official `Tutor`_ documentation for details of how to use it. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/mobile-deprecated.rst b/source/site_ops/install_configure_run_guide/mobile-deprecated.rst new file mode 100644 index 000000000..f357ef3bc --- /dev/null +++ b/source/site_ops/install_configure_run_guide/mobile-deprecated.rst @@ -0,0 +1,258 @@ +.. _Deprecated Mobile Applications: + +############################################ +Deprecated Open edX Mobile Applications +############################################ + +.. warning:: + The following instructions refer to the older, now unsupported, + mobile applications. They were last supported in the Quince release. + + Please see :ref:`Setting up the Mobile Applications` for more on the current apps. + +Deprecated Mobile Applications +****************************** + +Accessing the Source Code +========================= + +The deprecated mobile applications, one for iOS and one for +Android, are below. You can find the source code and additional documentation for each +application in the following repositories. + +* iOS (`iOS app deprecation ticket `_): http://github.com/openedx-unsupported/edx-app-ios + +* Android (`Android app deprecation ticket `_): http://github.com/openedx-unsupported/edx-app-android + + +Configuring Mobile Application Features +======================================= + +For the mobile API and authentication to work correctly with the edX mobile +applications, you enable them in the ``edx/app/edxapp/lms.yml`` file. You +then complete the setup for authentication by creating OAuth clients and +adding their IDs to the custom configuration file of each mobile application. + +Enable Mobile Application Features +---------------------------------- + +.. note:: Configuration settings added to the ``lms.yml`` file are reset + to their default values when you use Ansible to update edx-platform. + +To enable the mobile application features, follow these steps. + +#. In the ``edx/app/edxapp/lms.yml`` file, add the following lines to the + features section. + + .. code-block:: none + + "FEATURES" : { + ... + "ENABLE_MOBILE_REST_API": true, + "ENABLE_OAUTH2_PROVIDER": true, + "ENABLE_COMBINED_LOGIN_REGISTRATION": true +   } + + If you are running in a non-SSL environment, you can set + ``"OAUTH_ENFORCE_SECURE": false``. This configuration setting should never be + set to ``false`` in anything other than a development environment. + +#. Save the ``edx/app/edxapp/lms.yml`` file. + +#. Restart the server. + +.. future: add server- and client-side configuration for Google and Facebook sign in, incl. add ``"ENABLE_THIRD_PARTY_AUTH": true`` to the ``"FEATURES"`` list + +.. _Create the OAuth Clients: + + +Create the OAuth Clients +------------------------------ + +You create an OAuth client ID and secret that are specific to your +installation for use by the mobile applications. The procedure that follows +assumes that you create a different client for each of the edX mobile +applications. + +Before you can create OAuth clients, a superuser must exist on the server. For +more information, see `edX Managing the Full Stack`_. + +To create your OAuth clients, follow these steps. + +#. Log in to the Django administration console for your base URL. For example, + ``http://{your_URL}/admin``. + +#. In the **Oauth2** section, select **Clients**. + +#. Select **Add client**. A dialog box opens with the **Client id** and + **Client secret** populated for the new client. + +#. Enter a **Url** and **Redirect Url** for the first mobile application. For + example, ``https://{your_URL}/api/mobile/{version}/?app=ios``. While the + console requires values for these fields, they are not used by the edX + mobile applications. You can enter the same value in both fields. + +#. For the **Client type**, select **Public**. + +#. Optionally, enter a **User** and an identifying **Name**. + +#. Select **Save and add another**. + +#. Repeat steps 4-6 for the second mobile application, and then select + **Save**. + +Configure the Applications with OAuth Client IDs +------------------------------------------------ + +The procedure that follows assumes that you have a different OAuth client ID +for each edX mobile application. + +To configure each edX mobile application with its OAuth client ID, you add a +setting to its custom configuration .yaml file. For information about how to +set up custom configuration directories and files, see the GitHub repositories +for `iOS`_ and `Android`_. + +#. Obtain the OAuth client ID for the first mobile application from your + Django administration console. For more information, see :ref:`Create the + OAuth Clients`. + +#. In your custom GitHub configuration directory, edit the .yaml file for the + first mobile application. For example, for the edX mobile application for + iOS, edit your ``ios.yaml`` file. + +#. Add the following line to the .yaml file. + + :: + + OAUTH_CLIENT_ID: '{client_id_for_iOS_app}' + +#. Save the file. + +#. Repeat steps 1-4 for the second mobile application. + + + +.. _Configure OAuth Token Expiration Days: + +Configure OAuth Token Expiration +----------------------------------- + +When OAuth tokens expire, learners who use the mobile apps to access your site +must log in again. + +The ``lms/envs/common.py`` file includes the default configuration settings for +the number of days before OAuth tokens expire for confidential clients and +public clients. Instead of modifying the defaults in ``lms/envs/common.py``, add +the configuration settings to the ``lms.yml`` file and set values that will +override the default settings. + +To configure the number of days before OAuth tokens expire, follow these steps. + +#. In the ``edx/app/edxapp/lms.yml`` file, add the following lines to + specify the number of days that OAuth tokens remain valid for confidential + or public clients. + + .. note:: Make sure you add these lines at the top level of the JSON + dictionary, and not inside any other declarations. + + + .. code-block:: none + + "OAUTH_EXPIRE_CONFIDENTIAL_CLIENT_DAYS" : 365 + "OAUTH_EXPIRE_PUBLIC_CLIENT_DAYS" : 30 + +#. Save the ``lms.yml`` file, then restart the edxapp app. + + The values that you defined in ``lms.yml`` override the default + values defined in ``lms/envs/common.py``. + + +.. _Configuring Video Modules for Mobile: + +Configuring Video Modules for Mobile +===================================== + +Course videos must be specifically prepared to ensure that they are in +mobile accessible formats. Video modules in mobile-available courses should +have low resolution encodings that are readily accessible by mobile +devices. + +After you obtain a low resolution encoding for a video file and post it +online, your course team can add its location to the video module that +includes the video in the course structure. + +* To configure a video module in edX Studio, you edit the video component. On + the **Advanced** tab, in the **Video File URLs** field, enter the URL to the + mobile-targeted video as the first URL in the list. For more information, see + :ref:`Working with Video Components` in *Building and Running + an Open edX Course*. + +* To configure a video module by editing the course XML, enter the URL to the + mobile-targeted video as the first URL in the list of ``html5_sources``. For + more information, see :ref:`Video Components` in the *edX + Open Learning XML Guide*. + +Enabling Push Notifications +============================= + +You enable push notifications on the server and then configure each of the edX +mobile applications. Currently, you can use Parse for notification delivery. + +The procedures that follow assume that you have obtained an application ID, +REST API key, and client key from Parse. + +Enable Push Notification on the Server +----------------------------------------- + +To enable the push notification feature, follow these steps. + +#. In the ``edx/app/edxapp/studio.yml`` file, add the following lines. + + .. code-block:: none + + PARSE_KEYS = { + "APPLICATION_ID": "{app_id}", + "REST_API_KEY": "{API_key}" + } + +2. Save the ``edx/app/edxapp/studio.yml`` file. + +#. Restart the server. + +#. Log in to the Django administration console for your Studio URL. For + example, ``http://studio.{your_URL}/admin``. + +#. In the **Contentstore** section, select **Push notification configs**. + +#. Select **Add push notification config**. + +#. Verify that **Enabled** is selected, and then select **Save**. + +Configure Push Notification on the Clients +----------------------------------------------- + +The procedure that follows assumes that you use a single set of Parse +credentials for both of the edX mobile applications. + +You add push notification settings to the applicable custom configuration +.yaml file. For information about how to set up custom configuration +directories and files, see the GitHub repositories for `iOS`_ and `Android`_. + +#. In your custom GitHub configuration directory, edit the .yaml file that + stores configuration settings that are common to both of the edX mobile + applications. For example, edit your ``shared.yaml`` file. + +#. Add the following lines to the .yaml file. + + :: + + PARSE: + NOTIFICATIONS_ENABLED: true + APPLICATION_ID: {your application id} + CLIENT_KEY: {your client key} + + PUSH_NOTIFICATIONS: true + +#. Save the file. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/mobile.rst b/source/site_ops/install_configure_run_guide/mobile.rst new file mode 100644 index 000000000..e9baed70b --- /dev/null +++ b/source/site_ops/install_configure_run_guide/mobile.rst @@ -0,0 +1,28 @@ +.. _Setting up the Mobile Applications: + +############################################ +Setting Up the Open edX Mobile Applications +############################################ + +This section is intended for those are who are building Open edX mobile +applications and customizing an Open edX installation to support their use. + +Currently Supported Mobile Applications +*************************************** + +There are currently two supported mobile applications: + +* `Open edX Android App `_ + +* `Open edX iOS App `_ + +Mobile Documentation +******************** + +* `Implement Push Notification Channel `_ + +* `Manage Android Configuration `_ + +* `Manage iOS Configuration `_ + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/birch.rst b/source/site_ops/install_configure_run_guide/platform_releases/birch.rst new file mode 100644 index 000000000..62ab95c02 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/birch.rst @@ -0,0 +1,92 @@ +######################################## +Open edX Birch Release +######################################## + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Birch release. + +.. contents:: + :local: + :depth: 1 + +.. note:: + edX no longer supports the Birch release. + +****************************** +What's Included in Birch +****************************** + +The Open edX Birch release contains several new features for students, course +teams, and developers. See the Open edX Release Notes for more details. + +.. Note:: + There are several new features in the Birch release that are available, but + not configured in new installations. For details, see the following topics. + + * :ref:`Enable Course Prerequisites` + * :ref:`Enable Entrance Exams` + +****************************** +What is the Birch Git Tag? +****************************** + +The Git tag for the Birch release is **named-release/birch.2**. You use this tag +to identify the version of Open edX code that is the Birch release. + +The following Open edX Git repositories have the Git tag **named-release/birch.2**: + +* edx-platform +* configuration +* cs_comments_service +* notifier +* edx-certificates +* xqueue +* edx-documentation +* edx-ora2 +* XBlock + +****************************** +Upgrading from Aspen to Birch +****************************** + +You can upgrade your Open edX instance that is running the Aspen release to the +Birch release, using the ``migrate.sh`` script in the configuration repository, +`available here `_. + +.. note:: + The upgrade scripts provided are verified only for upgrading instances + running the Aspen release. If you are running any other version of the Open + edX Platform, the upgrade scripts might not work. + +.. caution:: + Before upgrading your Open edX instance, back up all data and configuration + files. Then verify that you can restore your Open edX instance from the + backup files. + +On the computer or virtual machine running the Aspen release of Open edX, run +the upgrade script for your type of installation: + +* For devstack, run ``./migrate.sh -t named-release/birch.2 -c devstack``. + +* For fullstack, run ``./migrate.sh -t named-release/birch.2 -c fullstack``. + +* You can also run ``./migrate.sh -h`` to see which other options the script accepts. + +The script creates a temporary directory in which it upgrades Open edX, then +cleans up extra files and directories when it finishes running. + +After upgrading Open edX to the Birch release, run the edX Platform and verify +that course content and data was migrated correctly. + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/cypress.rst b/source/site_ops/install_configure_run_guide/platform_releases/cypress.rst new file mode 100644 index 000000000..5bb55871b --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/cypress.rst @@ -0,0 +1,100 @@ +######################################## +Open edX Cypress Release +######################################## + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes the Open edX Cypress release. Note that edX no longer +supports the Cypress release. + +.. contents:: + :local: + :depth: 1 + +****************************** +What's Included in Cypress +****************************** + +The Open edX Cypress release contains several new features for learners, course +teams, and developers. See the Open edX Release Notes for more details. + +.. Note:: + There are several new features in the Cypress release that are available, but + not enabled by default in new installations. For details, see the following + topics. + + + + * :ref:`Enable edX Search` + * :ref:`Enable CCX` + * :ref:`Enable Licensing` + * Badging - Support was dropped in Palm and so the documentation is no longer + available on the latest release. + +****************************** +What is the Cypress Git Tag? +****************************** + +The Git tag for the Cypress release is ``named-release/cypress``. You use this +tag to identify the version of Open edX code that is the Cypress release. + +The following Open edX Git repositories have the Git tag +``named-release/cypress``. + +* edx-platform +* configuration +* cs_comments_service +* notifier +* edx-certificates +* xqueue +* edx-documentation +* edx-ora2 +* XBlock + +******************************** +Upgrading from Birch to Cypress +******************************** + +You can upgrade an Open edX instance that is running the Birch release to the +Cypress release, by using the ``migrate.sh`` script in the configuration +repository, `available here +`_. + +.. note:: + The upgrade scripts provided are verified only for upgrading instances + running the Birch release. If you are running any other version of the Open + edX Platform, the upgrade scripts might not work. + +.. caution:: + Before upgrading your Open edX instance, back up all data and configuration + files. Then verify that you can restore your Open edX instance from the + backup files. + +On the computer or virtual machine that is running the Birch release of Open +edX, run the upgrade script for your type of installation: + +* For devstack, run ``./migrate.sh -c devstack``. + +* For fullstack, run ``./migrate.sh -c fullstack``. + +* You can also run ``./migrate.sh -h`` to see which other options the script + accepts. + +The script creates a temporary directory in which it upgrades Open edX, then +cleans up extra files and directories when it finishes running. + +After upgrading Open edX to the Cypress release, start the LMS and Studio and +verify that course content and data was migrated correctly. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/dogwood.rst b/source/site_ops/install_configure_run_guide/platform_releases/dogwood.rst new file mode 100644 index 000000000..052188ef0 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/dogwood.rst @@ -0,0 +1,191 @@ +######################################## +Open edX Dogwood Release +######################################## + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes the Open edX Dogwood release. Note that edX no longer +supports the Dogwood relesae. + +.. contents:: + :local: + :depth: 1 + +.. note:: + Now that the Open edX Eucalyptus release is available, edX no longer + supports the Dogwood release. + +****************************** +What's Included in Dogwood +****************************** + +The Open edX Dogwood release contains several new features for learners, course +teams, and developers. See the release notes for the +`Dogwood `_ for more details. + +****************************** +What Is the Dogwood Git Tag? +****************************** + +A Git tag identifies the version of Open edX code that is the Dogwood release. +You can find the most up-to-date Git tag for the current Open edX release on +:ref:`Open edX Release Notes`. + +The following Open edX Git repositories have the Dogwood Git tag. + +* edx-platform +* configuration +* cs_comments_service +* xqueue +* XBlock +* notifier +* edx-ora2 +* edx-documentation +* edx-certificates +* edx-analytics-data-api-client +* edx-analytics-configuration +* edx-analytics-dashboard +* edx-analytics-data-api +* edx-analytics-pipeline + +********************************* +Upgrading from Cypress to Dogwood +********************************* + +You can upgrade an Open edX instance that is running the Cypress release to the +Dogwood release. EdX provides the ``migrate.sh`` script if you have a simple +Cypress installation and want to upgrade it automatically. If you have a more +complex or customized installation, you may need to upgrade manually. + +=================== +Automatic Upgrading +=================== + +`The migrate.sh script`_ is in the edX configuration repository on GitHub. + +.. note:: + The upgrade scripts provided are verified only for upgrading instances + running the Cypress release. If you are running any other version of the Open + edX Platform, the upgrade scripts might not work. + +.. caution:: + Before upgrading your Open edX instance, back up all data and configuration + files. Then verify that you can restore your Open edX instance from the + backup files. + +On the computer or virtual machine that is running the Cypress release of Open +edX, run the upgrade script for your type of installation. + +* For devstack, run ``./migrate.sh -c devstack -t named-release/dogwood``. + +* For fullstack, run + ``./migrate.sh -c fullstack -t named-release/dogwood``. + +You can find the most up-to-date Git tag for the current Open edX release on +:ref:`Open edX Release Notes`. + +You can also run ``./migrate.sh -h`` to see which other options the script +accepts. + +The script creates a temporary directory in which it upgrades Open edX, then +cleans up extra files and directories when it finishes running. + +After upgrading Open edX to the Dogwood release, start the LMS and Studio and +verify that course content and data was migrated correctly. + +======================== +Upgrade Process Overview +======================== + +This is an overview of what happens during an upgrade from Cypress to Dogwood. +The ``migrate.sh`` script implements this process. You may need to understand +this process if your installation is customized in some way, or if you need to +diagnose problems during the upgrade. + +Upgrading Cypress to Dogwood is more involved than most Open edX release +upgrades. + +* Dogwood upgrades the Django framework from version 1.4 to 1.8, which changed + the database migration tool from South to Django. When you upgrade from + Cypress to Dogwood, it is important to take special care with the database + migrations. + +* Dogwood upgrades Python from 2.7.3 to 2.7.10. This means virtualenvs have to + be recreated. + +The upgrade from Cypress to Dogwood includes these steps. + +#. Applies a `forum migration described on the Open edX wiki`_ to support teams + discussion filtering. + +#. Updates edx-platform to the ``release-2015-11-09`` tag. This is the last + released version that used Django 1.4. + +#. Recreates the virtualenvs to use Python 2.7.10 instead of 2.7.3. + +#. Migrates the database. This makes the database current with the last 1.4 + code. + +#. Uninstalls South so that it does not interfere with the new Django + migrations. + +#. Updates edx-platform to the ``dogwood-first-18`` tag. This is the first + version of the code that used Django 1.8. + +#. Applies all the initial Django migrations. This gets your database ready to + use the new Django 1.8 migration mechanism. + +#. Updates edx-platform to Dogwood. + +#. Runs Django database migrations. + +#. Runs two management commands to update records in the database: + ``generate_course_overview`` and ``post_cohort_membership_fix``. + +#. Runs the forum migration again. This step processes any discussion topics + created during the running of the script. + +Similar steps are followed to upgrade other repositories such as xqueue. + + +************************************ +Upgrading to a Dogwood Point Release +************************************ + +Occasionally, we release updates to Dogwood. The first of these is named +Dogwood.1, then Dogwood.2, and so on. The steps differ based on your original +installation method. You will need to know the name of the Dogwood tag you +want to install, for example ``named-release/dogwood.2``. + +================================ +Upgrading a Vagrant Installation +================================ + +Devstack and Fullstack are installed using Vagrant. To upgrade to a Dogwood +point release, follow these steps in the host operating system. + +.. code-block:: bash + + $ export OPENEDX_RELEASE={desired-dogwood-tag} + $ vagrant provision + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the `Open edX Native 12.04 Installation`_, re-run +those steps using your desired Dogwood tag as the new value for +``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/eucalyptus.rst b/source/site_ops/install_configure_run_guide/platform_releases/eucalyptus.rst new file mode 100644 index 000000000..632d27a6f --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/eucalyptus.rst @@ -0,0 +1,139 @@ +######################################## +Open edX Eucalyptus Release +######################################## + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes the Open edX Eucalyptus release. Note that edX no longer +supports the Eucalyptus relesae. + +.. contents:: + :local: + :depth: 1 + +****************************** +What's Included in Eucalyptus +****************************** + +The Open edX Eucalyptus release contains several new features for learners, +course teams, and developers. For more information, see +`Open edX Eucalyptus Release `. + +******************************* +What Is the Eucalyptus Git Tag? +******************************* + +A Git tag identifies the version of Open edX code that is the Eucalyptus release. +You can find the most up-to-date Git tag for the current Open edX release on +:ref:`Open edX Release Notes`. + +The following Open edX Git repositories have the Eucalyptus Git tag. + +* edx-platform +* configuration +* cs_comments_service +* xqueue +* XBlock +* notifier +* edx-ora2 +* edx-documentation +* edx-certificates +* edx-analytics-data-api-client +* edx-analytics-configuration +* edx-analytics-dashboard +* edx-analytics-data-api +* edx-analytics-pipeline + + +************************************ +Upgrading from Dogwood to Eucalyptus +************************************ + +You can upgrade an Open edX instance that is running the Dogwood release to the +Eucalyptus release. EdX provides the ``upgrade.sh`` script if you have a simple +Dogwood installation and want to upgrade it automatically. If you have a more +complex or customized installation, you may need to upgrade manually. + +`The upgrade.sh script`_ is in the edX configuration repository on GitHub. + +.. note:: + The upgrade script is only for upgrading instances running the Dogwood + release. If your instance is running a release prior to the Dogwood release, + follow the instructions to upgrade it to each intervening release, and then + upgrade from Dogwood to Eucalyptus. + +.. caution:: + Before upgrading your Open edX instance, back up all data and configuration + files. Then verify that you can restore your Open edX instance from the + backup files. + +On the computer or virtual machine that is running the Dogwood release of Open +edX, run the upgrade script for your type of installation. + +#. Download the script. + + .. code-block:: bash + + $ export OPENEDX_RELEASE=open-release/eucalyptus.1 + $ curl -OL https://raw.github.com/openedx/configuration/$OPENEDX_RELEASE/util/vagrant/upgrade.sh + +#. Run the script. + + * For devstack, run ``bash upgrade.sh -c devstack``. + + * For fullstack, run ``bash upgrade.sh -c fullstack``. + +You can find the most up-to-date Git tag for the current Open edX release on +:ref:`Open edX Release Notes`. + +You can also run ``bash upgrade.sh -h`` to see which other options the script +accepts. + +The script creates a temporary directory in which it upgrades Open edX, then +cleans up extra files and directories when it finishes running. + +After upgrading Open edX to the Eucalyptus release, start the LMS and Studio and +verify that course content and data was migrated correctly. + + +******************************************** +Upgrading to a Subsequent Eucalyptus Release +******************************************** + +Occasionally, we release updates to Eucalyptus. For example, the second +release of Eucalyptus is ``open-release/eucalyptus.2``. +The steps to upgrade differ based on your original installation method. + +================================ +Upgrading a Vagrant Installation +================================ + +Devstack and Fullstack for Eucalyptus are installed using Vagrant. To upgrade +to a Eucalyptus point release, follow these steps in the host operating system. + +.. code-block:: bash + + $ export OPENEDX_RELEASE=open-release/eucalyptus.2 + $ vagrant provision + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the `Open edX Native 12.04 Installation`_, re-run +those steps using your desired Eucalyptus tag as the new value for +``OPENEDX_RELEASE``. + + +.. include:: /links.txt + diff --git a/source/site_ops/install_configure_run_guide/platform_releases/ficus.rst b/source/site_ops/install_configure_run_guide/platform_releases/ficus.rst new file mode 100644 index 000000000..c2276b750 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/ficus.rst @@ -0,0 +1,92 @@ +###################### +Open edX Ficus Release +###################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes the Open edX Ficus release. Note that edX no longer +supports the Ficus relesae. + +.. contents:: + :local: + :depth: 1 + +************************ +What's Included in Ficus +************************ + +The Open edX Ficus release contains several new features for learners, +course teams, and developers. For more information, see +`Ficus release notes `_. + +************************** +What Is the Ficus Git Tag? +************************** + +A git tag identifies the version of Open edX code that is the Ficus release. +You can find the most up-to-date git tag for the current Open edX release on +:ref:`Open edX Release Notes`. + +The following Open edX git repositories have the Ficus git tag: + +* edx-platform +* configuration +* cs_comments_service +* xqueue +* ecommerce +* ecommerce-worker +* edx-analytics-configuration +* edx-analytics-dashboard +* edx-analytics-data-api +* edx-analytics-pipeline +* edx-certificates +* edx-custom-a11y-rules +* edx-demo-course +* edx-documentation +* edx-notes-api +* edx-ui-toolkit +* notifier +* programs +* ux-pattern-library + + +*************************************** +Upgrading to a Subsequent Ficus Release +*************************************** + +Occasionally, we release updates to Ficus. For example, the second +release of Ficus is ``open-release/ficus.2``. +The steps to upgrade differ based on your original installation method. + +================================ +Upgrading a Vagrant Installation +================================ + +Devstack and Fullstack are installed using Vagrant. To upgrade from one Ficus +release to another, run the following commands in the host operating system: + +.. code-block:: bash + + $ export OPENEDX_RELEASE=open-release/ficus.2 + $ vagrant provision + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the `Legacy Open edX Native Installation`_, you can +upgrade from one Ficus release to another by re-running those steps using your +desired Ficus tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/ginkgo.rst b/source/site_ops/install_configure_run_guide/platform_releases/ginkgo.rst new file mode 100644 index 000000000..fe0ab288f --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/ginkgo.rst @@ -0,0 +1,194 @@ +######################## +Open edX Ginkgo Release +######################## + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes the Open edX Ginkgo release. + +.. contents:: + :local: + :depth: 1 + +************************** +What's Included in Ginkgo +************************** + +The Open edX Ginkgo release contains several new features for learners, +course teams, and developers. For more information, see +`Open edX Ginkgo Release Notes `_. + +**************************** +What Is the Ginkgo Git Tag? +**************************** + +A git tag identifies the version of Open edX code that is the Ginkgo release. +You can find the most up-to-date git tag for the current Open edX release on +:ref:`Open edX Release Notes`. + +The following Open edX git repositories have the Ginkgo git tag: + +* edx-platform +* configuration +* course_discovery +* cs_comments_service +* xqueue +* ecommerce +* ecommerce-worker +* edx-analytics-configuration +* edx-analytics-dashboard +* edx-analytics-data-api +* edx-analytics-pipeline +* edx-certificates +* edx-custom-a11y-rules +* edx-demo-course +* edx-documentation +* edx-notes-api +* edx-ui-toolkit +* notifier +* ux-pattern-library + +********************************** +Upgrading from the Ficus Release +********************************** + +One approach to upgrading an existing installation of the Open edX Ficus +release to the Ginkgo release is to make a fresh installation of the Ginkgo +release on a new machine, and move your data and settings to it. + +To move and upgrade your Ficus data onto a Ginkgo installation, follow these +steps. + +#. Be sure that your Ficus installation is on Ficus.4. The Ficus.4 release + provided required database migrations beyond what was in Ficus.3. The only + version of Ficus that will upgrade to Ginkgo successfully is Ficus.4. + +#. Stop all services on the Ficus machine. + +#. Dump the data on the Ficus machine. Here's an example script that will dump + the MySQL and Mongo databases into a single ``.tgz`` file. The script will + prompt for the MySQL and Mongo passwords as needed. + + .. code-block:: bash + + #!/bin/bash + MYSQL_CONN="-uroot -p" + echo "Reading MySQL database names..." + mysql ${MYSQL_CONN} -ANe "SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('mysql','information_schema','performance_schema', 'sys')" > /tmp/db.txt + DBS="--databases $(cat /tmp/db.txt)" + NOW="$(date +%Y%m%dT%H%M%S)" + SQL_FILE="mysql-data-${NOW}.sql" + echo "Dumping MySQL structures..." + mysqldump ${MYSQL_CONN} --add-drop-database --skip-add-drop-table --no-data ${DBS} > ${SQL_FILE} + echo "Dumping MySQL data..." + # If there is table data you don't need, add --ignore-table=tablename + mysqldump ${MYSQL_CONN} --no-create-info ${DBS} >> ${SQL_FILE} + + for db in edxapp cs_comments_service; do + echo "Dumping Mongo db ${db}..." + mongodump -u admin -p -h localhost --authenticationDatabase admin -d ${db} --out mongo-dump-${NOW} + done + + tar -czf openedx-data-${NOW}.tgz ${SQL_FILE} mongo-dump-${NOW} + +#. Copy the ``.tgz`` data file to the Ginkgo machine. + +#. Stop all services on the Ginkgo machine. + +#. Restore the Ficus data into the Ginkgo machine. As an example, you might use + the following commands. + + .. code-block:: bash + + $ tar -xvf openedx-data-20170811T154750.tgz + $ mysql -uroot -p < mysql-data-20170811T154750.sql + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d edxapp mongo-dump-20170811T154750/edxapp + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d cs_comment_service mongo-dump-20170811T154750/cs_comment_service_development + +#. To migrate data from Ficus to Ginkgo, you need to drop the database tables + used by djcelery. These tables should be empty in your Ficus data, so it is + safe to drop them. The edx-platform application has a management command to + check that they are empty and drop them: + + .. code-block:: bash + + $ sudo su - -s /bin/bash edxapp + edxapp@xyz:~$ . edxapp_env + edxapp@xyz:~$ cd edx-platform/ + edxapp@xyz:~/edx-platform$ python manage.py lms drop_djcelery_tables --settings=aws + +#. Run the Ginkgo migration script, which will update your Ficus data to be valid + for Ginkgo: + + .. code-block:: bash + + $ /edx/app/edx_ansible/edx_ansible/util/install/native.sh --tags migrate + +#. Copy your configuration files from the Ficus machine to the Ginkgo machine. + +#. Restart all services. + +.. _oscar_ginkgo: + +========================= +Upgrading Django Oscar +========================= + +The Ginkgo release of Open edX upgrades Django Oscar to version 1.4. If you have +an existing installation of Open edX with the E-Commerce service, and your +``orders`` table is larger than a million rows, there is an additional step to +upgrade your Django Oscar installation. + +The migration includes a change to the ``guest_email`` column in the ``orders`` +table. This change is applied automatically. If your ``orders`` table is larger +than a million rows, this migration may lock the table for an extended amount of +time. The E-Commerce service does not normally use the ``guest_email`` column. +If your installation does not use this column, you can avoid the table lock by +using the ``--fake`` argument in migrating the ``orders`` table, running the +``migrate`` command in the following form. + +.. code-block:: bash + + ./manage.py migrate orders 0013 --fake + + +**************************************** +Upgrading to a Subsequent Ginkgo Release +**************************************** + +Occasionally, we release updates to Ginkgo. For example, the second +release of Ginkgo will be ``open-release/ginkgo.2``. +The steps to upgrade differ based on your original installation method. + +================================ +Upgrading a Vagrant Installation +================================ + +Devstack and Fullstack are installed using Vagrant. To upgrade from one Ginkgo +release to another, run the following commands in the host operating system: + +.. code-block:: bash + + $ export OPENEDX_RELEASE=open-release/ginkgo.2 + $ vagrant provision + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the `Legacy Open edX Native Installation`_, you can +upgrade from one Ginkgo release to another by re-running those steps using your +desired Ginkgo tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/hawthorn.rst b/source/site_ops/install_configure_run_guide/platform_releases/hawthorn.rst new file mode 100644 index 000000000..a2c360340 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/hawthorn.rst @@ -0,0 +1,175 @@ +######################### +Open edX Hawthorn Release +######################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Hawthorn release. + +.. contents:: + :local: + :depth: 1 + +**************************** +What's Included in Hawthorn +**************************** + +The Open edX Hawthorn release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/hawthorn.html + +======================= +User Retirement Feature +======================= + +The Hawthorn release also includes the new user retirement feature, which is a +set of APIs and tooling that enables Open edX instances to retire registered +users. There have been many changes to privacy laws (for example, GDPR or the +European Union General Data Protection Regulation) intended to change the way +that businesses think about and handle Personally Identifiable Information +(PII) data. The user retirement feature is a step toward enabling Open edX to +support some of the key updates in privacy laws. For more information, see +`retirement`_. + +****************************** +What Is the Hawthorn Git Tag? +****************************** + +A git tag identifies the version of Open edX code that is the Hawthorn release. +About two dozen repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Hawthorn on the +:ref:`Open edX Release Notes`. + +******************************* +Installing the Hawthorn Release +******************************* + +You can install the Open edX Hawthorn release using either +`devstack`_ or the `Legacy Open edX +Native Installation`_ instructions. + +Hawthorn releases have git tag names like ``open-release/hawthorn.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +.. _upgrade_ginkgo: + +********************************** +Upgrading from the Ginkgo Release +********************************** + +The recommended approach to upgrading an existing installation of the Open edX +Ginkgo release to the Hawthorn release is to make a fresh installation of the +Hawthorn release on a new machine, and move your data and settings to it. + +To move and upgrade your Ginkgo data onto a Hawthorn installation, follow these +steps. + +#. Be sure that your Ginkgo installation is on the latest + ``open-release/ginkgo.master``. This ensures that your database is fully + migrated and ready for upgrade to Hawthorn. + +#. Stop all services on the Ginkgo machine. + +#. Dump the data on the Ginkgo machine. Here's an example script that will dump + the MySQL and Mongo databases into a single ``.tgz`` file. The script will + prompt for the MySQL and Mongo passwords as needed. + + .. code-block:: bash + + #!/bin/bash + MYSQL_CONN="-uroot -p" + echo "Reading MySQL database names..." + mysql ${MYSQL_CONN} -ANe "SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('mysql','information_schema','performance_schema', 'sys')" > /tmp/db.txt + DBS="--databases $(cat /tmp/db.txt)" + NOW="$(date +%Y%m%dT%H%M%S)" + SQL_FILE="mysql-data-${NOW}.sql" + echo "Dumping MySQL structures..." + mysqldump ${MYSQL_CONN} --add-drop-database --skip-add-drop-table --no-data ${DBS} > ${SQL_FILE} + echo "Dumping MySQL data..." + # If there is table data you don't need, add --ignore-table=tablename + mysqldump ${MYSQL_CONN} --no-create-info ${DBS} >> ${SQL_FILE} + + for db in edxapp cs_comments_service; do + echo "Dumping Mongo db ${db}..." + mongodump -u admin -p -h localhost --authenticationDatabase admin -d ${db} --out mongo-dump-${NOW} + done + + tar -czf openedx-data-${NOW}.tgz ${SQL_FILE} mongo-dump-${NOW} + +#. Copy the ``.tgz`` data file to the Hawthorn machine. + +#. Stop all services on the Hawthorn machine. + +#. Restore the Ginkgo data into the Hawthorn machine. As an example, you might + use the following commands. + + .. code-block:: bash + + $ tar -xvf openedx-data-20170811T154750.tgz + $ mysql -uroot -p < mysql-data-20170811T154750.sql + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d edxapp mongo-dump-20170811T154750/edxapp + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d cs_comment_service mongo-dump-20170811T154750/cs_comment_service_development + +#. To migrate data from Ginkgo to Hawthorn, you need to drop the database + tables used by djcelery. These tables should be empty in your Ginkgo data, + so it is safe to drop them. The edx-platform application has a management + command to check that they are empty and drop them: + + .. code-block:: bash + + $ sudo su - -s /bin/bash edxapp + edxapp@xyz:~$ . edxapp_env + edxapp@xyz:~$ cd edx-platform/ + edxapp@xyz:~/edx-platform$ python manage.py lms drop_djcelery_tables --settings=aws + +#. Run the Hawthorn migrations, which will update your Ginkgo data to be + valid for Hawthorn: + + .. code-block:: bash + + $ /edx/app/edx_ansible/edx_ansible/util/install/native.sh --tags migrate + +#. Copy your configuration files from the Ginkgo machine to the Hawthorn + machine. + +#. Restart all services. + + +****************************************** +Upgrading to a Subsequent Hawthorn Release +****************************************** + +Occasionally, we release updates to Hawthorn. For example, the second +release of Hawthorn will be ``open-release/hawthorn.2``. +The steps to upgrade differ based on your original installation method. + +================================ +Upgrading a Docker Installation +================================ + +Devstack is installed using Docker. To upgrade from one Hawthorn +release to another, follow the instructions in `devstack`_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the `Legacy Open edX Native Installation`_, you can +upgrade from one Hawthorn release to another by re-running those steps using +your desired Hawthorn tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/index.rst b/source/site_ops/install_configure_run_guide/platform_releases/index.rst new file mode 100644 index 000000000..3f5827ede --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/index.rst @@ -0,0 +1,27 @@ +.. _Open edX Platform Releases: + +########################## +Open edX Platform Releases +########################## + +The following sections provide information about releases of the Open edX +platform: + +.. toctree:: + :maxdepth: 2 + + latest + olive + nutmeg + maple + lilac + koa + juniper + ironwood + hawthorn + ginkgo + ficus + eucalyptus + dogwood + cypress + birch diff --git a/source/site_ops/install_configure_run_guide/platform_releases/ironwood.rst b/source/site_ops/install_configure_run_guide/platform_releases/ironwood.rst new file mode 100644 index 000000000..a12f8052c --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/ironwood.rst @@ -0,0 +1,162 @@ +######################### +Open edX Ironwood Release +######################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Ironwood release. + +.. contents:: + :local: + :depth: 1 + +**************************** +What's Included in Ironwood +**************************** + +The Open edX Ironwood release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/ironwood.html + + +****************************** +What Is the Ironwood Git Tag? +****************************** + +A git tag identifies the version of Open edX code that is the Ironwood release. +About two dozen repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Ironwood on the +:ref:`Open edX Release Notes`. + +******************************* +Installing the Ironwood Release +******************************* + +You can install the Open edX Ironwood release using either +`devstack`_ or the `Legacy Open edX +Native Installation`_ instructions. + +Ironwood releases have git tag names like ``open-release/ironwood.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +.. _upgrade_hawthorn: + +*********************************** +Upgrading from the Hawthorn Release +*********************************** + +The recommended approach to upgrading an existing installation of the Open edX +Hawthorn release to the Ironwood release is to make a fresh installation of the +Ironwood release on a new machine, and move your data and settings to it. + +To move and upgrade your Hawthorn data onto a Ironwood installation, follow these +steps. + +#. Be sure that your Hawthorn installation is on the latest + ``open-release/hawthorn.master``. This ensures that your database is fully + migrated and ready for upgrade to Ironwood. + +#. Stop all services on the Hawthorn machine. + +#. Dump the data on the Hawthorn machine. Here's an example script that will dump + the MySQL and Mongo databases into a single ``.tgz`` file. The script will + prompt for the MySQL and Mongo passwords as needed. + + .. code-block:: bash + + #!/bin/bash + MYSQL_CONN="-uroot -p" + echo "Reading MySQL database names..." + mysql ${MYSQL_CONN} -ANe "SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('mysql','information_schema','performance_schema', 'sys')" > /tmp/db.txt + DBS="--databases $(cat /tmp/db.txt)" + NOW="$(date +%Y%m%dT%H%M%S)" + SQL_FILE="mysql-data-${NOW}.sql" + echo "Dumping MySQL structures..." + mysqldump ${MYSQL_CONN} --add-drop-database --skip-add-drop-table --no-data ${DBS} > ${SQL_FILE} + echo "Dumping MySQL data..." + # If there is table data you don't need, add --ignore-table=tablename + mysqldump ${MYSQL_CONN} --no-create-info ${DBS} >> ${SQL_FILE} + + for db in edxapp cs_comments_service; do + echo "Dumping Mongo db ${db}..." + mongodump -u admin -p -h localhost --authenticationDatabase admin -d ${db} --out mongo-dump-${NOW} + done + + tar -czf openedx-data-${NOW}.tgz ${SQL_FILE} mongo-dump-${NOW} + +#. Copy the ``.tgz`` data file to the Ironwood machine. + +#. Stop all services on the Ironwood machine. + +#. Restore the Hawthorn data into the Ironwood machine. As an example, you might + use the following commands. + + .. code-block:: bash + + $ tar -xvf openedx-data-20170811T154750.tgz + $ mysql -uroot -p < mysql-data-20170811T154750.sql + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d edxapp mongo-dump-20170811T154750/edxapp + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d cs_comment_service mongo-dump-20170811T154750/cs_comment_service_development + +#. To migrate data from Hawthorn to Ironwood, you need to drop the database + tables used by djcelery. These tables should be empty in your Hawthorn data, + so it is safe to drop them. The edx-platform application has a management + command to check that they are empty and drop them: + + .. code-block:: bash + + $ sudo su - -s /bin/bash edxapp + edxapp@xyz:~$ . edxapp_env + edxapp@xyz:~$ cd edx-platform/ + edxapp@xyz:~/edx-platform$ python manage.py lms drop_djcelery_tables --settings=aws + +#. Run the Ironwood migrations, which will update your Hawthorn data to be + valid for Ironwood: + + .. code-block:: bash + + $ /edx/app/edx_ansible/edx_ansible/util/install/native.sh --tags migrate + +#. Copy your configuration files from the Hawthorn machine to the Ironwood + machine. + +#. Restart all services. + +****************************************** +Upgrading to a Subsequent Ironwood Release +****************************************** + +Occasionally, we release updates to Ironwood. For example, the second +release of Ironwood will be ``open-release/ironwood.2``. +The steps to upgrade differ based on your original installation method. + +================================ +Upgrading a Docker Installation +================================ + +Devstack is installed using Docker. To upgrade from one Ironwood +release to another, follow the instructions in `devstack`_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the `Legacy Open edX Native Installation`_, you can +upgrade from one Ironwood release to another by re-running those steps using +your desired Ironwood tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/juniper.rst b/source/site_ops/install_configure_run_guide/platform_releases/juniper.rst new file mode 100644 index 000000000..6edb742e3 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/juniper.rst @@ -0,0 +1,146 @@ +######################### +Open edX Juniper Release +######################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Juniper release. + +.. contents:: + :local: + :depth: 1 + +**************************** +What's Included in Juniper +**************************** + +The Open edX Juniper release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/juniper.html + + +****************************** +What Is the Juniper Git Tag? +****************************** + +A git tag identifies the version of Open edX code that is the Juniper release. +About three dozen repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Juniper on the +:ref:`Open edX Release Notes`. + +******************************* +Installing the Juniper Release +******************************* + +You can install the Open edX Juniper release using either +`devstack`_ or the `Legacy Open edX Native Installation`_ instructions. + +Juniper releases have git tag names like ``open-release/juniper.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +*********************************** +Upgrading from the Ironwood Release +*********************************** + +The recommended approach to upgrading an existing installation of the Open edX +Ironwood release to the Juniper release is to make a fresh installation of the +Juniper release on a new machine, and move your data and settings to it. + +To move and upgrade your Ironwood data onto a Juniper installation, follow these +steps. + +#. Be sure that your Ironwood installation is on the latest commit from + ``open-release/ironwood.master``. This ensures that your database is fully + migrated and ready for upgrade to Juniper. + +#. Stop all services on the Ironwood machine. + +#. Dump the data on the Ironwood machine. Here's an example script that will dump + the MySQL and Mongo databases into a single ``.tgz`` file. The script will + prompt for the MySQL and Mongo passwords as needed. + + .. code-block:: bash + + #!/bin/bash + MYSQL_CONN="-uroot -p" + echo "Reading MySQL database names..." + mysql ${MYSQL_CONN} -ANe "SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('mysql','information_schema','performance_schema', 'sys')" > /tmp/db.txt + DBS="--databases $(cat /tmp/db.txt)" + NOW="$(date +%Y%m%dT%H%M%S)" + SQL_FILE="mysql-data-${NOW}.sql" + echo "Dumping MySQL structures..." + mysqldump ${MYSQL_CONN} --add-drop-database --skip-add-drop-table --no-data ${DBS} > ${SQL_FILE} + echo "Dumping MySQL data..." + # If there is table data you don't need, add --ignore-table=tablename + mysqldump ${MYSQL_CONN} --no-create-info ${DBS} >> ${SQL_FILE} + + for db in edxapp cs_comments_service; do + echo "Dumping Mongo db ${db}..." + mongodump -u admin -p -h localhost --authenticationDatabase admin -d ${db} --out mongo-dump-${NOW} + done + + tar -czf openedx-data-${NOW}.tgz ${SQL_FILE} mongo-dump-${NOW} + +#. Copy the ``.tgz`` data file to the Juniper machine. + +#. Stop all services on the Juniper machine. + +#. Restore the Ironwood data into the Juniper machine. As an example, you might + use the following commands. + + .. code-block:: bash + + $ tar -xvf openedx-data-20200411T154750.tgz + $ mysql -uroot -p < mysql-data-20200411T154750.sql + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d edxapp mongo-dump-20200411T154750/edxapp + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d cs_comment_service mongo-dump-20200411T154750/cs_comment_service_development + +#. Run the Juniper migrations, which will update your Ironwood data to be + valid for Juniper: + + .. code-block:: bash + + $ /edx/app/edx_ansible/edx_ansible/util/install/native.sh --tags migrate + +#. Copy your configuration files from the Ironwood machine to the Juniper machine. + +#. Restart all services. + +****************************************** +Upgrading to a Subsequent Juniper Release +****************************************** + +Occasionally, we release updates to Juniper. For example, the second +release of Juniper will be ``open-release/juniper.2``. +The steps to upgrade differ based on your original installation method. + +================================ +Upgrading a Docker Installation +================================ + +Devstack is installed using Docker. To upgrade from one Juniper +release to another, follow the instructions in `devstack`_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the `Legacy Open edX Native Installation`_, you can +upgrade from one Juniper release to another by re-running those steps using +your desired Juniper tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/koa.rst b/source/site_ops/install_configure_run_guide/platform_releases/koa.rst new file mode 100644 index 000000000..89d4857c8 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/koa.rst @@ -0,0 +1,156 @@ +#################### +Open edX Koa Release +#################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Koa release. + +.. contents:: + :local: + :depth: 1 + +********************** +What's Included in Koa +********************** + +The Open edX Koa release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Platform Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/koa.html + + +************************ +What Is the Koa Git Tag? +************************ + +A git tag identifies the version of Open edX code that is the Koa release. +About three dozen repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Koa on the +:ref:`Open edX Release Notes`. + +************************** +Installing the Koa Release +************************** + +.. warning:: + + This release is unsupported. + +See `Tutor installation instructions `_. + +You can install the Open edX Koa release using either +`devstack`_ or the Open edX Native Installation. + +Koa releases have git tag names like ``open-release/koa.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +********************************** +Upgrading from the Juniper Release +********************************** + +The recommended approach to upgrading an existing installation of the Open edX +Juniper release to the Koa release is to make a fresh installation of the +Koa release on a new machine, and move your data and settings to it. + +To move and upgrade your Juniper data onto a Koa installation, follow these +steps. + +#. Be sure that your Juniper installation is on the latest commit from + ``open-release/juniper.master``. This ensures that your database is fully + migrated and ready for upgrade to Koa. + +#. Stop all services on the Juniper machine. + +#. Dump the data on the Juniper machine. Here's an example script that will dump + the MySQL and Mongo databases into a single ``.tgz`` file. The script will + prompt for the MySQL and Mongo passwords as needed. + + .. code-block:: bash + + #!/bin/bash + MYSQL_CONN="-uroot -p" + echo "Reading MySQL database names..." + mysql ${MYSQL_CONN} -ANe "SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('mysql','information_schema','performance_schema', 'sys')" > /tmp/db.txt + DBS="--databases $(cat /tmp/db.txt)" + NOW="$(date +%Y%m%dT%H%M%S)" + SQL_FILE="mysql-data-${NOW}.sql" + echo "Dumping MySQL structures..." + mysqldump ${MYSQL_CONN} --add-drop-database --skip-add-drop-table --no-data ${DBS} > ${SQL_FILE} + echo "Dumping MySQL data..." + # If there is table data you don't need, add --ignore-table=tablename + mysqldump ${MYSQL_CONN} --no-create-info ${DBS} >> ${SQL_FILE} + + for db in edxapp cs_comments_service; do + echo "Dumping Mongo db ${db}..." + mongodump -u admin -p -h localhost --authenticationDatabase admin -d ${db} --out mongo-dump-${NOW} + done + + tar -czf openedx-data-${NOW}.tgz ${SQL_FILE} mongo-dump-${NOW} + +#. Copy the ``.tgz`` data file to the Koa machine. + +#. Stop all services on the Koa machine. + +#. Restore the Juniper data into the Koa machine. As an example, you might + use the following commands. + + .. code-block:: bash + + $ tar -xvf openedx-data-20200411T154750.tgz + $ mysql -uroot -p < mysql-data-20200411T154750.sql + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d edxapp mongo-dump-20200411T154750/edxapp + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d cs_comment_service mongo-dump-20200411T154750/cs_comment_service_development + +#. Run the Koa migrations, which will update your Juniper data to be + valid for Koa: + + .. code-block:: bash + + $ /edx/app/edx_ansible/edx_ansible/util/install/native.sh --tags migrate + +#. Copy your configuration files from the Juniper machine to the Koa machine. + +#. Restart all services. + +************************************* +Upgrading to a Subsequent Koa Release +************************************* + +Occasionally, we release updates to Koa. For example, the second +release of Koa will be ``open-release/koa.2``. +The steps to upgrade differ based on your original installation method. + +=============================== +Upgrading a Docker Installation +=============================== + +Devstack is installed using Docker. To upgrade from one Koa +release to another, follow the instructions in `devstack`_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the Open edX Native Installation, please +migrate to Tutor. This `Native Installation to Tutor forum post`_ may be helpful, +as may be `this second Native to Tutor post`_. If not, post on the `Open edX Forums`_. + +If you installed Open edX using the Open edX Native Installation, you can +upgrade from one Koa release to another by re-running those steps using +your desired Koa tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/latest.rst b/source/site_ops/install_configure_run_guide/platform_releases/latest.rst new file mode 100644 index 000000000..612e68f44 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/latest.rst @@ -0,0 +1,15 @@ +.. _Open edX Latest Platform Release: + +################################ +Open edX Latest Platform Release +################################ + +The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the +authoratative sources of information on all Open edX releases. It is *strongly* +recommended to operate off the latest Open edX release at all points in time, as +only the most recent release is community-supported. + +See the `Open edX Release Schedule`_ for information on release dates and end-of-life +support. + +.. include:: /links.txt \ No newline at end of file diff --git a/source/site_ops/install_configure_run_guide/platform_releases/lilac.rst b/source/site_ops/install_configure_run_guide/platform_releases/lilac.rst new file mode 100644 index 000000000..d2cb2a4a3 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/lilac.rst @@ -0,0 +1,159 @@ +###################### +Open edX Lilac Release +###################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Lilac release. + +.. contents:: + :local: + :depth: 1 + +************************ +What's Included in Lilac +************************ + +The Open edX Lilac release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Platform Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/lilac.html + + +************************** +What Is the Lilac Git Tag? +************************** + +A git tag identifies the version of Open edX code that is the Lilac release. +About three dozen repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Lilac on the +:ref:`Open edX Release Notes`. + +**************************** +Installing the Lilac Release +**************************** + +.. warning:: + + This release is unsupported. + +See `Tutor installation instructions `_. + +You can install the Open edX Lilac release using the Open edX Installation +instructions (`Tutor`_). + +Lilac releases have git tag names like ``open-release/lilac.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +****************************** +Upgrading from the Koa Release +****************************** + +The recommended approach to upgrading an existing installation of the Open edX +Koa release to the Lilac release is to make a fresh installation of the +Lilac release on a new machine, and move your data and settings to it. + +To move and upgrade your Koa data onto a Lilac installation, follow these +steps. + +#. Be sure that your Koa installation is on the latest commit from + ``open-release/koa.master``. This ensures that your database is fully + migrated and ready for upgrade to Lilac. + +#. Stop all services on the Koa machine. + +#. Dump the data on the Koa machine. Here's an example script that will dump + the MySQL and Mongo databases into a single ``.tgz`` file. The script will + prompt for the MySQL and Mongo passwords as needed. + + .. code-block:: bash + + #!/bin/bash + MYSQL_CONN="-uroot -p" + echo "Reading MySQL database names..." + mysql ${MYSQL_CONN} -ANe "SELECT schema_name FROM information_schema.schemata WHERE schema_name NOT IN ('mysql','information_schema','performance_schema', 'sys')" > /tmp/db.txt + DBS="--databases $(cat /tmp/db.txt)" + NOW="$(date +%Y%m%dT%H%M%S)" + SQL_FILE="mysql-data-${NOW}.sql" + echo "Dumping MySQL structures..." + mysqldump ${MYSQL_CONN} --add-drop-database --skip-add-drop-table --no-data ${DBS} > ${SQL_FILE} + echo "Dumping MySQL data..." + # If there is table data you don't need, add --ignore-table=tablename + mysqldump ${MYSQL_CONN} --no-create-info ${DBS} >> ${SQL_FILE} + + for db in edxapp cs_comments_service; do + echo "Dumping Mongo db ${db}..." + mongodump -u admin -p -h localhost --authenticationDatabase admin -d ${db} --out mongo-dump-${NOW} + done + + tar -czf openedx-data-${NOW}.tgz ${SQL_FILE} mongo-dump-${NOW} + +#. Copy the ``.tgz`` data file to the Lilac machine. + +#. Stop all services on the Lilac machine. + +#. Restore the Koa data into the Lilac machine. As an example, you might + use the following commands. + + .. code-block:: bash + + $ tar -xvf openedx-data-20200411T154750.tgz + $ mysql -uroot -p < mysql-data-20200411T154750.sql + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d edxapp mongo-dump-20200411T154750/edxapp + $ mongorestore -u admin -p -h localhost --authenticationDatabase admin --drop -d cs_comment_service mongo-dump-20200411T154750/cs_comment_service_development + +#. Run the Lilac migrations, which will update your Koa data to be + valid for Lilac: + + .. code-block:: bash + + $ /edx/app/edx_ansible/edx_ansible/util/install/native.sh --tags migrate + +#. Copy your configuration files from the Koa machine to the Lilac machine. + +#. Restart all services. + +*************************************** +Upgrading to a Subsequent Lilac Release +*************************************** + +Occasionally, we release updates to Lilac. For example, the second +release of Lilac will be ``open-release/lilac.2``. +The steps to upgrade differ based on your original installation method. + +=============================== +Upgrading a Docker Installation +=============================== + +Devstack is installed using Docker. To upgrade from one Lilac +release to another, follow the instructions in `devstack`_. + +The `devstack`_ installation method is deprecated. It is recommended +to migrate to Tutor. See `Tutor installation instructions `_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the Open edX Native Installation, please +migrate to Tutor. This `Native Installation to Tutor forum post`_ may be helpful, +as may be `this second Native to Tutor post`_. If not, post on the `Open edX Forums`_. + +If you installed Open edX using the Open edX Native Installation, you can +upgrade from one Lilac release to another by re-running those steps using +your desired Lilac tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/maple.rst b/source/site_ops/install_configure_run_guide/platform_releases/maple.rst new file mode 100644 index 000000000..2d47ff56f --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/maple.rst @@ -0,0 +1,92 @@ +###################### +Open edX Maple Release +###################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Maple release. + +.. contents:: + :local: + :depth: 1 + +************************ +What's Included in Maple +************************ + +The Open edX Maple release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Platform Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/maple.html + + +************************** +What Is the Maple Git Tag? +************************** + +A git tag identifies the version of Open edX code that is the Maple release. +About three dozen repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Maple on the +:ref:`Open edX Release Notes`. + +**************************** +Installing the Maple Release +**************************** + +.. warning:: + + This release is unsupported. + +See `Tutor installation instructions `_. + +Maple releases have git tag names like ``open-release/maple.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +********************************* +Upgrading from the Lilac Release +********************************* + +See `Tutor upgrade instructions `_. + + +*************************************** +Upgrading to a Subsequent Maple Release +*************************************** + +Occasionally, we release updates to Maple. For example, the second +release of Maple will be ``open-release/maple.2``. +The steps to upgrade differ based on your original installation method. + +=============================== +Upgrading a Docker Installation +=============================== + +The `devstack`_ installation method is deprecated. It is recommended +to migrate to Tutor. See `Tutor installation instructions `_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the Open edX Native Installation, please +migrate to Tutor. This `Native Installation to Tutor forum post`_ may be helpful, +as may be `this second Native to Tutor post`_. If not, post on the `Open edX Forums`_. + +If you installed Open edX using the Open edX Native Installation, you can +upgrade from one Maple release to another by re-running those steps using +your desired Maple tag as the new value for ``OPENEDX_RELEASE``. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/nutmeg.rst b/source/site_ops/install_configure_run_guide/platform_releases/nutmeg.rst new file mode 100644 index 000000000..b3b4f62e4 --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/nutmeg.rst @@ -0,0 +1,87 @@ +####################### +Open edX Nutmeg Release +####################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Nutmeg release. + +.. contents:: + :local: + :depth: 1 + +************************* +What's Included in Nutmeg +************************* + +The Open edX Nutmeg release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Platform Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/nutmeg.html + + +*************************** +What Is the Nutmeg Git Tag? +*************************** + +A git tag identifies the version of Open edX code that is the Nutmeg release. +About three dozen repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Nutmeg on the +:ref:`Open edX Release Notes`. + +***************************** +Installing the Nutmeg Release +***************************** + +.. warning:: + + This release is unsupported. + +See `Tutor installation instructions `_. + +Nutmeg releases have git tag names like ``open-release/nutmeg.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +******************************** +Upgrading from the Maple Release +******************************** + +See `Tutor upgrade instructions `_. + +**************************************** +Upgrading to a Subsequent Nutmeg Release +**************************************** + +Occasionally, we release updates to Nutmeg. For example, the second +release of Nutmeg will be ``open-release/nutmeg.2``. +The steps to upgrade differ based on your original installation method. + +=============================== +Upgrading a Docker Installation +=============================== + +The `devstack`_ installation method is deprecated. It is recommended +to migrate to Tutor. See `Tutor installation instructions `_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the Open edX Native Installation, please +migrate to Tutor. This `Native Installation to Tutor forum post`_ may be helpful, +as may be `this second Native to Tutor post`_. If not, post on the `Open edX Forums`_. + + +.. include:: /links.txt diff --git a/source/site_ops/install_configure_run_guide/platform_releases/olive.rst b/source/site_ops/install_configure_run_guide/platform_releases/olive.rst new file mode 100644 index 000000000..25599fcee --- /dev/null +++ b/source/site_ops/install_configure_run_guide/platform_releases/olive.rst @@ -0,0 +1,86 @@ +###################### +Open edX Olive Release +###################### + +.. warning:: + + This release is unsupported. + + The :ref:`Open edX Release Notes` and the :ref:`Open edX Release Notes` are the + authoratative sources of information on all Open edX releases. It is *strongly* + recommended to operate off the latest Open edX release at all points in time, as + only the most recent release is community-supported. + + See the `Open edX Release Schedule`_ for information on release dates and end-of-life + support. + +This section describes how to install the Open edX Olive release. + +.. contents:: + :local: + :depth: 1 + +************************* +What's Included in Olive +************************* + +The Open edX Olive release contains several new features for learners, +course teams, and developers. For more information, see the +`Open edX Platform Release Notes`__. + +__ https://docs.openedx.org/en/latest/community/release_notes/olive.html + +************************** +What Is the Olive Git Tag? +************************** + +A git tag identifies the version of Open edX code that is the Olive release. +Over fourty repositories are tagged as part of an Open edX release. Many +other repositories are installed as dependencies of those repositories. You can +find the most up-to-date git tag for Olive on the +:ref:`Open edX Release Notes`. + +**************************** +Installing the Olive Release +**************************** + +.. warning:: + + This release is unsupported. + +See `Tutor installation instructions `_. + +Olive releases have git tag names like ``open-release/olive.1``. +The available names are detailed on the :ref:`Open edX Release Notes`. + +********************************* +Upgrading from the Nutmeg Release +********************************* + +See `Tutor upgrade instructions `_. + +*************************************** +Upgrading to a Subsequent Olive Release +*************************************** + +Occasionally, we release updates to Olive. For example, the second +release of Olive will be ``open-release/olive.2``. +The steps to upgrade differ based on your original installation method. + +=============================== +Upgrading a Docker Installation +=============================== + +The `devstack`_ installation method is deprecated. It is recommended +to migrate to Tutor. See `Tutor installation instructions `_. + +=============================== +Upgrading a Native Installation +=============================== + +If you installed Open edX using the Open edX Native Installation, please +migrate to Tutor. This `Native Installation to Tutor forum post`_ may be helpful, +as may be `this second Native to Tutor post`_. If not, post on the `Open edX Forums`_. + + +.. include:: /links.txt