Merge pull request #142 from edx/markhoeber-doc1615

Birch version of installation and configuration guide

en_us/install_operations/source/analytics/install_analytics.rst

@@ -11,27 +11,21 @@ and its dependencies in a production environment. Work to prepare complete
 installation procedures for edX Insights is in progress. Introductory material
 is available now.
 
-See the following sections:
+.. contents:: Chapter Contents:
 
-* `Overview`_
-* `What You Should Know Before You Start`_
-* `Planning Your Deployment`_
-* `Example Deployments`_
-
-.. _edX Insights: http://edx.readthedocs.org/projects/edx-insights/en/latest/index.html
 
 ********
 Overview
 ********
 
-Course teams use edX Insights to access to data gathered from courses that are
-being used by students. Course teams use edX Insights to display charts, summary
-statistics, and data tables.
+Course teams use edX Insights to access to data gathered from active courses.
+Course teams use edX Insights to display charts, summary statistics, and data
+tables.
 
 The Learning Management System (LMS) gathers data about student 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.
+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.
 
 .. _edX Analytics Data API: http://edx.readthedocs.org/projects/edx-data-analytics-api/en/latest/index.html
 
@@ -50,11 +44,11 @@ Components
 LMS
 ***
 
-The LMS records student actions in tracking log files. The standard logrotate
-utility periodically compresses and copies these files into a filesystem 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 students.
+The LMS records student actions in tracking log files. The standard
+``logrotate`` utility periodically compresses and copies these files into a
+filesystem 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 students.
 
 edX Analytics Pipeline
 **********************

en_us/install_operations/source/birch.rst

@@ -0,0 +1,176 @@
+.. include:: links.rst
+
+.. _Open edX Birch Release:
+
+########################################
+Open edX Birch Release
+########################################
+
+.. contents:: Chapter Contents:
+
+
+******************************
+What's Included in Birch
+******************************
+
+The Open edX Birch release contains several new features for students, course
+staff, and developers.  See the Open edX Release Notes for more details. (LINK)
+
+.. 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:`Add the Google Drive and Google Calendar XBlock`.
+ * :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**. 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**:
+
+* edx-platform
+* configuration
+* cs_comments_service
+* notifier
+* edx-certificates
+* xqueue
+* edx-documentation
+* edx-ora2
+* XBlock
+
+.. confirm
+
+******************************
+Installing the Birch Release
+******************************
+
+You can install the Open edX Birch release using :ref:`Devstack <Install DevStack>` or :ref:`Fullstack <Install Open edX Fullstack>`.
+
+Review the prerequisities and instructions for each option, then choose the
+option that best meets your needs. Ensure you install the required software to
+run the edX Platform.
+
+If you are upgrading from the Aspen release, see `Upgrading from Aspen to
+Birch`_.
+
+For new installations, follow the steps below.
+
+#. `Download the Vagrant Box`_ or `Download the BitTorrent File`_.
+
+   .. caution::
+     The Vagrant boxes have a large file size (about 2.5GB). If you have a slow
+     or unreliable Internet connection, use BitTorrent to download the the
+     Vagrant box you need.
+
+#. `Set the OPENEDX_RELEASE Environment Variable`_.
+#. `Install the Vagrant Box`_.
+
+=========================
+Download the Vagrant Box
+=========================
+
+If you have a fast and reliable Internet connection, you can download the
+Vagrant box direclty or by running ``vagrant up`` when installing
+:ref:`Devstack <Installing the Open edX Developer Stack>` or
+:ref:`Fullstack <Installing Open edX Fullstack>`.
+
+Use one of the following links to download the box directly.
+
+* `Birch Devstack`_
+* `Birch Fullstack`_
+
+See `Vagrant's documentation on boxes`_ for more information.
+
+
+=============================
+Download the BitTorrent File
+=============================
+
+You can also download the BitTorrent file for the option you selected.
+BitTorrent is recommended if you have a slow or unreliable data conntection.
+You then use the BitTorrent file to download the Vagrant box. If the Internet
+connection is temporarily lost while you are downloading the Vagrant box
+through BitTorrent, you can later continue the download without data loss or
+corruption.
+
+* `Birch Devstack BitTorrent`_
+* `Birch Fullstack BitTorrent`_
+
+See `BitTorrent`_ for more information.
+
+If you download the Vagrant box through BitTorrent, you must add the box to
+Vagrant before continuing with the installation process.
+
+* For Devstack installations, run the following command.
+
+   .. code-block:: bash
+
+     $ vagrant box add /path-to-downloaded-box/vagrant-images-20150224-birch-
+     devstack.box --name birch-devstack
+
+* For Fullstack installations, run the following command.
+
+   .. code-block:: bash
+
+     $ vagrant box add /path-to-downloaded-box/vagrant-images-20150224-birch-
+     fullstack.box --name birch-fullstack
+
+.. confirm names
+
+============================================
+Set the OPENEDX_RELEASE Environment Variable
+============================================
+
+Before installing the Vagrant box, you must set the value of the
+`OPENEDX_RELEASE` environment variable to the Git tag for the Birch release:
+
+.. code-block:: bash
+
+  export OPENEDX_RELEASE="named-release/birch"
+
+
+=========================
+Install the Vagrant Box
+=========================
+
+When you have completed the previous steps, install the Birch release by
+following the installation instructions for :ref:`Devstack <Installing the Open
+edX Developer Stack>` or
+:ref:`Fullstack <Installing Open edX Fullstack>`.
+
+
+******************************
+Upgrading from Aspen to Birch
+******************************
+
+You can upgrade your Open edX instance that is running the Aspen release to the
+Birch release.
+
+.. 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 the ``migrate-devstack.sh`` script.
+
+* For Fullstack, run the ``migrate-fullstack.sh`` script.
+
+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 the upgrade script. Verify that course content and data was migrated
+correctly.

en_us/install_operations/source/change_log.rst

@@ -8,13 +8,18 @@ Change Log
 
    * - Date
      - Change
+   * - 02/24/2015
+     - Updated for the :ref:`Open edX Birch Release`.
+   * - 02/24/2015
+     - Added the section :ref:`Configuring the Open edX Platform`.
    * - 01/20/2015
-     - Addition of the section :ref:`Installing edX Insights`
+     - Added the section :ref:`Installing edX Insights`
    * - 01/14/2015
      - Addition of the section :ref:`Setting up the Mobile Applications`
    * - 06/07/2014
-     - Addition of the section :ref:`Installing the edX Production Stack`
+     - Addition of the section :ref:`Installing Open edX Fullstack`
    * - 05/21/2014
-     - The initial release of this guide, with the sections :ref:`Installing the
-       edX Developer Stack` and :ref:`Running the edX Developer Stack`.
+     - The initial release of this guide, with the sections :ref:`Installing
+       the Open edX Developer Stack` and :ref:`Running the Open edX Developer
+       Stack`.
 

en_us/install_operations/source/conf.py

@@ -29,7 +29,7 @@
 
 
 # General information about the project.
-project = u'Installing, Configuring, and Running the edX Platform'
+project = u'Installing, Configuring, and Running the Open edX Platform'
 copyright = u'2015, edX'
 
 # The short X.Y version.
@@ -63,7 +63,7 @@
     }
 
 #remove directory when content is first added to it, and add to index
-exclude_patterns = ['links.rst']
+exclude_patterns = ['links.rst', 'configuration/configure_milestone_app.rst', 'configuration/enable_course_search.rst']
 
 # The short X.Y version.
 version = ''

en_us/install_operations/source/configuration/configure_milestone_app.rst

@@ -0,0 +1,19 @@
+.. include:: ../links.rst
+
+.. for reuse, not in TOC, excluded from build list
+
+************************************
+Configure the Milestones Application
+************************************
+
+#. Set the value of ``MILESTONES_APP`` in the ``/cms/envs/common.py`` and
+   ``/lms/envs/common.py`` files to ``True``.
+
+   .. code-block:: bash
+
+       # Milestones application flag
+       'MILESTONES_APP': True,
+
+#. Save the ``/cms/envs/common.py`` and ``/lms/envs/common.py`` files.
+
+#. Run database migrations.

en_us/install_operations/source/configuration/enable_course_search.rst

@@ -0,0 +1,58 @@
+.. include:: ../links.rst
+
+.. _Enable Course Search:
+
+######################################################
+Enable Course Search
+######################################################
+
+In the Open edX Birch release, a new feature allows learners to search
+courseware. To enable this feature on your instance of Open edX, you must
+enable both indexing and search.
+
+You should enable course indexing before enabling search, so that the course is
+indexed before learners can search course content.
+
+For information about searching courseware, see the *Open edX Learner's* guide.
+
+.. Note::  
+  Before proceeding, review :ref:`Guidelines for Updating the edX Platform`.
+
+*****************************
+Enable Course Indexing
+*****************************
+
+To enable course indexing:
+
+#. In the edX Platform installation directory, edit the file
+   ``/cms/envs/common.py``
+
+#. Set the value of ``ENABLE_COURSEWARE_INDEX`` to ``True``:
+
+   .. code-block:: bash
+
+      # Enable the courseware search functionality
+      'ENABLE_COURSEWARE_INDEX': True,
+
+#. Save the ``/cms/envs/common.py`` file.
+
+
+**********************************************************
+Enable Course Search in the Learning Management System
+**********************************************************
+
+To enable course search in the Learning Management System, after courses are
+indexed:
+
+#. In the edX Platform installation directory, edit the file
+   ``/lms/envs/common.py``
+
+#. Set the value of ``ENABLE_COURSEWARE_SEARCH`` to ``True``:
+
+   .. code-block:: bash
+
+      # Courseware search feature
+      'ENABLE_COURSEWARE_SEARCH': True,
+
+#. Save the ``/lms/envs/common.py`` file.
+

en_us/install_operations/source/configuration/enable_entrance_exams.rst

@@ -0,0 +1,37 @@
+.. include:: ../links.rst
+
+.. _Enable Entrance Exams:
+
+######################################################
+Enable Entrance Exams
+######################################################
+
+In the Open edX Birch release, a new feature allows course staff to 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 edX Platform`.
+
+.. include:: configure_milestone_app.rst
+
+*************************************************************************
+Enable Entrance Exams in Studio and the Learning Management System
+*************************************************************************
+
+#. Set the value of ``ENABLE_ENTRANCE_EXAMS`` in the
+   ``/cms/envs/common.py`` and ``/lms/envs/common.py`` files to ``True``.
+
+   .. code-block:: bash
+
+     # Entrance exams feature flag
+     'ENABLE_ENTRANCE_EXAMS': True,
+
+#. Save the ``/cms/envs/common.py`` and ``/lms/envs/common.py`` files.
+