To change the default configuration of an Open edX instance to use Swift (the OpenStack Object Store project) for data storage, you update the /edx/app/edx_ansible/server-vars.yml file.
Before proceeding, review the Guidelines for Updating the Open edX Platform.
You can define all required and optional Swift settings at one time, or you can update settings as needed over time. Each time you update the server-vars.yml file, you must run the update command and restart the LMS server.
Before you change your data storage configuration, be sure to determine the values that apply to your Swift data storage service, including your credentials and the name of your container. Then, follow these steps.
Define Required Swift Settings
- Stop the LMS server.
- Create or edit the
/edx/app/edx_ansible/server-vars.ymlfile.
Be sure to replace any example values for the settings that follow with values that apply to your instance. - Define or verify the following settings.
EDXAPP_SETTINGS: "openstack"
VHOST_NAME: "openstack"
#. To configure Swift, define values for each of the following settings. The
``EDXAPP_SWIFT_AUTH_VERSION`` can be set to either ``1`` or ``2``, and
defaults to ``1`` if not specified.
.. code-block:: yaml
EDXAPP_SWIFT_USERNAME: ""
EDXAPP_SWIFT_KEY: ""
EDXAPP_SWIFT_TENANT_ID: ""
EDXAPP_SWIFT_TENANT_NAME: ""
EDXAPP_SWIFT_AUTH_URL: ""
EDXAPP_SWIFT_AUTH_VERSION:
EDXAPP_SWIFT_REGION_NAME: ""
#. Customize the name of the Swift container that your system's files will be
uploaded to by defining the following setting.
.. code-block:: yaml
EDXAPP_FILE_UPLOAD_STORAGE_BUCKET_NAME: "container_name"
#. To configure storage for grade reports, define the following settings. The
``name_prefix`` that you define specifies a common prefix for the files
generated by the system.
.. code-block:: yaml
EDXAPP_GRADE_STORAGE_CLASS: 'swift.storage.SwiftStorage'
EDXAPP_GRADE_STORAGE_KWARGS:
name_prefix: "grades/"
.
.
.
ENABLE_GRADE_DOWNLOADS: true
You can continue on to define Swift settings for other features, or complete
the following steps to update your instance.
#. Run the following roles.
::
cd /edx/app/edx_ansible/edx_ansible/playbooks
sudo /edx/app/edx_ansible/venvs/edx_ansible/bin/ansible-playbook -i localhost, -c local -e@/edx/app/edx_ansible/server-vars.yml run-role.yml -e 'role=edxapp' -e 'edx_platform_version=<your branch name>'
sudo /edx/app/edx_ansible/venvs/edx_ansible/bin/ansible-playbook -i localhost, -c local -e@/edx/app/edx_ansible/server-vars.yml run-role.yml -e 'celery_worker=True' -e 'role=edxapp' -e 'edx_platform_version=<your branch name>'
sudo /edx/app/edx_ansible/venvs/edx_ansible/bin/ansible-playbook -i localhost, -c local -e@/edx/app/edx_ansible/server-vars.yml run-role.yml -e 'role=edxapp' -e 'edxapp_code_dir=<path to edx-platform directory>'
.. theoretically, the openstack role also gets run, but I sure don't see where
#. Restart the LMS server.
#. Repeat this procedure for each instance that has data that you want to store
on Swift.
============================================================
Define Swift Settings for Identity Verification (Proctoring)
============================================================
To define data storage for files that verify learner identity, follow these
steps.
#. Stop the LMS server.
#. Edit the ``/edx/app/edx_ansible/server-vars.yml`` file.
#. Verify that you have defined all of the :ref:`required Swift settings<Define
Required Swift Settings>`.
#. Define the following settings.
Be sure to replace any example values for the settings that follow with
values that apply to your instance.
.. code-block:: yaml
EDXAPP_VERIFY_STUDENT:
DAYS_GOOD_FOR: 365
SOFTWARE_SECURE:
STORAGE_CLASS: "swift.storage.SwiftStorage"
STORAGE_KWARGS:
name_prefix: "photos/"
#. Continue on to define Swift settings for other features, or complete steps
7-9 for :ref:`defining required Swift settings<Define Required Swift
Settings>` to update your instance.
Note that you only need to run the ``openstack`` role one time. If you are
completing these identity verification configuration steps as a separate
procedure, you need only run the ``edxapp`` role in step 7.
.. this note assumes that an openstack role actually got run somehow
==========================================
Define Swift Settings for Temporary URLs
==========================================
To use temporary URLs for Swift, follow these steps.
#. Stop the LMS server.
#. Edit the ``/edx/app/edx_ansible/server-vars.yml`` file.
#. Verify that you have defined all of the :ref:`required Swift settings<Define
Required Swift Settings>`.
#. Define the following settings.
The duration setting is the value, in seconds, for how long a temporary URL
remains valid.
.. code-block:: yaml
SWIFT_USE_TEMP_URLS: true
SWIFT_TEMP_URL_KEY: ""
SWIFT_TEMP_URL_DURATION:
#. Continue on to define Swift settings for other features, or complete steps
7-9 for :ref:`defining required Swift settings<Define Required Swift
Settings>` to update your instance.
Note that you only need to run the ``openstack`` role one time. If you are
completing these temporary URL configuration steps as a separate
procedure, you need only run the ``edxapp`` role in step 7.
.. this note assumes that an openstack role actually got run somehow
==========================================
Define Swift Settings for XQueue
==========================================
To define data storage for files for external graders, follow these
steps.
#. Stop the LMS server.
#. Edit the ``/edx/app/edx_ansible/server-vars.yml`` file.
#. Verify that you have defined all of the :ref:`required Swift settings<Define
Required Swift Settings>`.
#. Define the following settings.
In a basic setup, the values for these variables are the same as for the
``EDXAPP_SWIFT_*`` settings.
.. code-block:: yaml
XQUEUE_SETTINGS: "openstack_settings"
XQUEUE_SWIFT_USERNAME: ""
XQUEUE_SWIFT_KEY: ""
XQUEUE_SWIFT_TENANT_ID: ""
XQUEUE_SWIFT_TENANT_NAME: ""
XQUEUE_SWIFT_AUTH_URL: ""
XQUEUE_SWIFT_AUTH_VERSION:
XQUEUE_SWIFT_REGION_NAME: ""
XQUEUE_UPLOAD_BUCKET: ""
XQUEUE_UPLOAD_PATH_PREFIX: ""
#. Run the following roles.
::
cd /edx/app/edx_ansible/edx_ansible/playbooks
sudo /edx/app/edx_ansible/venvs/edx_ansible/bin/ansible-playbook -i localhost, -c local -e@/edx/app/edx_ansible/server-vars.yml run-role.yml -e 'role=xqueue' -e 'edx_platform_version=<your branch name>'
sudo /edx/app/edx_ansible/venvs/edx_ansible/bin/ansible-playbook -i localhost, -c local -e@/edx/app/edx_ansible/server-vars.yml run-role.yml -e 'celery_worker=True' -e 'role=xqueue' -e 'edx_platform_version=<your branch name>'
sudo /edx/app/edx_ansible/venvs/edx_ansible/bin/ansible-playbook -i localhost, -c local -e@/edx/app/edx_ansible/server-vars.yml run-role.yml -e 'role=xqueue' -e 'edxapp_code_dir=<path to edx-platform directory>'
.. I just changed edxapp to xqueue in three places -- is that all that's needed?
.. I left out the note assumes that about an openstack role though maybe it also needs to go here
#. Restart the LMS server.
#. Repeat this procedure for each instance that has data that you want to store
on Swift.
==========================================================
Define Swift Settings for Synchronizing Analytics Logs
==========================================================
To define settings for synchronizing event log files, follow these steps.
#. Stop the LMS server.
#. Edit the ``/edx/app/edx_ansible/server-vars.yml`` file.
#. Verify that you have defined all of the :ref:`required Swift settings<Define
Required Swift Settings>`.
#. Define the following settings.
.. code-block:: yaml
COMMON_OBJECT_STORE_LOG_SYNC: true
.
.
.
SWIFT_LOG_SYNC_USERNAME: ""
SWIFT_LOG_SYNC_PASSWORD: ""
SWIFT_LOG_SYNC_TENANT_ID: ""
SWIFT_LOG_SYNC_TENANT_NAME: ""
SWIFT_LOG_SYNC_AUTH_URL: ""
SWIFT_LOG_SYNC_REGION_NAME: ""
.. important:: If you set ``COMMON_OBJECT_STORE_LOG_SYNC: true``, you must
also define valid values for the ``SWIFT_LOG_SYNC_*`` variables.
Otherwise, analytics log synchronization will fail.
#. Continue on to define Swift settings for other features, or complete steps
7-9 for :ref:`defining required Swift settings<Define Required Swift
Settings>` to update your instance.