Better documentation
- More concise table of contents - New intro - Simpler make commands - Fix a couple typos here and there - Get rid of the default github issue template, and start using the template created online.
This commit is contained in:
Régis Behmo
parent
4f9bb7d752
commit
b4e3c43902
|
|
@ -1,13 +0,0 @@
|
|||
PLEASE PLEASE PLEASE READ THIS AND FOLLOW THE INSTRUCTIONS WHEN OPENING A NEW ISSUE
|
||||
|
||||
## Steps to reproduce
|
||||
|
||||
Include the exact command that you are running and that is causing an error. In case of a web error, include the URL of the page that is causing the error.
|
||||
|
||||
## Unexpected behavior
|
||||
|
||||
Include the full, exact output from the command that is causing your issue. Also include relevant error logs; for instance, to debug the LMS provide the output of `tutor local logs lms --tail=100`
|
||||
|
||||
## Additional info (IMPORTANT)
|
||||
|
||||
Provide the output of `tutor --version`.
|
||||
|
|
@ -57,6 +57,6 @@ To get community support, go to the official discussion forums: https://discuss.
|
|||
Contributing
|
||||
------------
|
||||
|
||||
We are very much open to new ideas, features for Tutor. If you have an improvement idea, feel free to first discuss it on the `Tutor forums <https://discuss.overhang.io>`_. If you are not quite familiar with Open edX or if you need technical advice, the forums are a great place to start, too. Did you find an issue with Tutor? Please first make sure that it's related to Tutor, and not an upstream issue with Open edX. Then, `open an issue on Github <https://github.com/regisb/tutor/issues/new>`_. `Pull requests <https://github.com/regisb/tutor/pulls>`_ will be happily examined, too!
|
||||
We are very much open to new ideas and features for Tutor. If you have an improvement idea, feel free to first discuss it on the `Tutor forums <https://discuss.overhang.io>`_. If you are not quite familiar with Open edX or if you need technical advice, the forums are a great place to start, too. Did you find an issue with Tutor? Please first make sure that it's related to Tutor, and not an upstream issue with Open edX. Then, `open an issue on Github <https://github.com/regisb/tutor/issues/new>`_. `Pull requests <https://github.com/regisb/tutor/pulls>`_ will be happily examined, too!
|
||||
|
||||
.. _readme_contributing_end:
|
||||
|
|
@ -1,24 +1,11 @@
|
|||
.DEFAULT_GOAL := html
|
||||
.PHONY: help
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
html:
|
||||
sphinx-build -b html -a -E "." "_build/html"
|
||||
|
||||
browse:
|
||||
sensible-browser _build/html/index.html
|
||||
|
||||
watch: html
|
||||
watch: html browse
|
||||
while true; do inotifywait -e modify *.rst; $(MAKE) html; done
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
|
|
|||
|
|
@ -1,7 +1,17 @@
|
|||
.. _configuration_customisation:
|
||||
|
||||
Configuration and customisation
|
||||
===============================
|
||||
|
||||
Tutor offers plenty of possibilities for platform customisation out of the box. There are two main ways in which the base Open edX install can be customized:
|
||||
|
||||
a. Modifying the Tutor :ref:`configuration parameters <configuration>`:
|
||||
b. Modifying the:ref:`Open edX docker image <customise>` that runs the Open edX platform.
|
||||
|
||||
.. _configuration:
|
||||
|
||||
Configuration
|
||||
=============
|
||||
-------------
|
||||
|
||||
With Tutor, all Open edX deployment parameters are stored in a single ``config.yml`` file. This is the file that is generated when you run ``tutor local quickstart`` or ``tutor config save``. To view the content of this file, run::
|
||||
|
||||
|
|
@ -26,7 +36,7 @@ Once the base configuration is created or updated, the environment is automatica
|
|||
With an up-to-date environment, Tutor is ready to launch an Open edX platform and perform usual operations. Below, we document some of the configuration parameters.
|
||||
|
||||
Individual service activation
|
||||
-----------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- ``ACTIVATE_LMS`` (default: ``true``)
|
||||
- ``ACTIVATE_CMS`` (default: ``true``)
|
||||
|
|
@ -44,12 +54,12 @@ Individual service activation
|
|||
Every single Open edX service may be (de)activated at will by these configuration parameters. This is useful if you want, for instance, to distribute the various Open edX services on different servers.
|
||||
|
||||
Docker
|
||||
------
|
||||
~~~~~~
|
||||
|
||||
.. _docker_images:
|
||||
|
||||
Custom images
|
||||
~~~~~~~~~~~~~
|
||||
*************
|
||||
|
||||
- ``DOCKER_IMAGE_OPENEDX`` (default: ``"regis/openedx:ironwood"``)
|
||||
- ``DOCKER_IMAGE_ANDROID`` (default: ``"regis/openedx-android:ironwood"``)
|
||||
|
|
@ -60,7 +70,7 @@ Custom images
|
|||
These configuration parameters define which image to run for each service.
|
||||
|
||||
Custom registry
|
||||
~~~~~~~~~~~~~~~
|
||||
***************
|
||||
|
||||
- ``DOCKER_REGISTRY`` (default: ``""``)
|
||||
|
||||
|
|
@ -71,10 +81,10 @@ You may want to pull/push images from/to a custom docker registry. For instance,
|
|||
(the trailing ``/`` is important)
|
||||
|
||||
Vendor services
|
||||
---------------
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
MySQL
|
||||
~~~~~
|
||||
*****
|
||||
|
||||
- ``ACTIVATE_MYSQL`` (default: ``true``)
|
||||
- ``MYSQL_HOST`` (default: ``"mysql"``)
|
||||
|
|
@ -88,19 +98,19 @@ By default, a running Open edX platform deployed with Tutor includes all necessa
|
|||
MYSQL_ROOT_PASSWORD: <root user password>
|
||||
|
||||
Elasticsearch
|
||||
~~~~~~~~~~~~~
|
||||
*************
|
||||
|
||||
- ``ELASTICSEARCH_HOST`` (default: ``"elasticsearch"``)
|
||||
- ``ELASTICSEARCH_PORT`` (default: ``9200``)
|
||||
|
||||
Memcached
|
||||
~~~~~~~~~
|
||||
*********
|
||||
|
||||
- ``MEMCACHED_HOST`` (default: ``"memcached"``)
|
||||
- ``MEMCACHED_PORT`` (default: ``11211``)
|
||||
|
||||
Mongodb
|
||||
~~~~~~~
|
||||
*******
|
||||
|
||||
- ``ACTIVATE_MONGODB`` (default: ``true``)
|
||||
- ``MONGODB_HOST`` (default: ``"mongodb"``)
|
||||
|
|
@ -110,7 +120,7 @@ Mongodb
|
|||
- ``MONGODB_PASSWORD`` (default: ``""``)
|
||||
|
||||
Rabbitmq
|
||||
~~~~~~~~
|
||||
********
|
||||
|
||||
- ``ACTIVATE_RABBITMQ`` (default: ``true``)
|
||||
- ``RABBITMQ_HOST`` (default: ``"rabbitmq"``)
|
||||
|
|
@ -118,7 +128,7 @@ Rabbitmq
|
|||
- ``RABBITMQ_PASSWORD`` (default: ``""``)
|
||||
|
||||
SMTP
|
||||
~~~~
|
||||
****
|
||||
|
||||
- ``ACTIVATE_SMTP`` (default: ``true``)
|
||||
- ``SMTP_HOST`` (default: ``"smtp"``)
|
||||
|
|
@ -127,12 +137,12 @@ SMTP
|
|||
- ``SMTP_PASSWORD`` (default: ``""``)
|
||||
|
||||
Optional features
|
||||
-----------------
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Some optional features may be activated or deactivated during the interactive configuration step (``tutor config save``).
|
||||
|
||||
SSL/TLS certificates for HTTPS access
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
*************************************
|
||||
|
||||
- ``ACTIVATE_HTTPS`` (default: ``false``)
|
||||
|
||||
|
|
@ -155,7 +165,7 @@ To renew the certificate, run this command once per month::
|
|||
tutor local https renew
|
||||
|
||||
Student notes
|
||||
~~~~~~~~~~~~~
|
||||
*************
|
||||
|
||||
- ``ACTIVATE_NOTES`` (default: ``false``)
|
||||
|
||||
|
|
@ -167,8 +177,94 @@ With `notes <https://edx.readthedocs.io/projects/open-edx-building-and-running-a
|
|||
You should beware that the ``notes.<LMS_HOST>`` domain name should be activated and point to your server. For instance, if your LMS is hosted at http://myopenedx.com, the notes service should be found at http://notes.myopenedx.com.
|
||||
|
||||
Xqueue
|
||||
~~~~~~
|
||||
******
|
||||
|
||||
- ``ACTIVATE_XQUEUE`` (default: ``false``)
|
||||
|
||||
`Xqueue <https://github.com/edx/xqueue>`_ is for grading problems with external services. If you don't know what it is, you probably don't need it.
|
||||
|
||||
.. _customise:
|
||||
|
||||
Custom Open edX docker image
|
||||
----------------------------
|
||||
|
||||
There are different ways you can customise your Open edX platform. For instance, optional features can be activated during configuration. But if you want to add unique features to your Open edX platform, you are going to have to modify and re-build the ``openedx`` docker image. This is the image that contains the ``edx-platform`` repository: it is in charge of running the web application for the Open edX "core". Both the LMS and the CMS run from the ``openedx`` docker image.
|
||||
|
||||
On a vanilla platform deployed by Tutor, the image that is run is downloaded from the `regis/openedx repository on Docker Hub <https://hub.docker.com/r/regis/openedx/>`_. This is also the image that is downloaded whenever we run ``tutor local pullimages``. But you can decide to build the image locally instead of downloading it. To do so, build and tag the ``openedx`` image::
|
||||
|
||||
tutor images build openedx
|
||||
|
||||
The following sections describe how to modify various aspects of the docker image. Every time, you will have to re-build your own image with this command. Re-building should take ~20 minutes on a server with good bandwidth. After building a custom image, you should stop the old running containers::
|
||||
|
||||
tutor local stop openedx
|
||||
|
||||
The custom image will be used the next time you run ``tutor local quickstart`` or ``tutor local start``. Do not attempt to run ``tutor local restart``! Restarting will not pick up the new image and will continue to use the old image.
|
||||
|
||||
Adding custom themes
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Comprehensive theming is enabled by default, but only the default theme is compiled. To compile your own theme, add it to the ``env/build/openedx/themes/`` folder::
|
||||
|
||||
git clone https://github.com/me/myopenedxtheme.git $(tutor config printroot)/env/build/openedx/themes/
|
||||
|
||||
The ``themes`` folder should have the following structure::
|
||||
|
||||
openedx/themes/
|
||||
mycustomtheme1/
|
||||
cms/
|
||||
...
|
||||
lms/
|
||||
...
|
||||
mycustomtheme2/
|
||||
...
|
||||
|
||||
Then you must rebuild the openedx Docker image::
|
||||
|
||||
tutor images build openedx
|
||||
|
||||
Finally, follow the `Open edX documentation to apply your themes <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/changing_appearance/theming/enable_themes.html#apply-a-theme-to-a-site>`_. You will not have to modify the ``lms.env.json``/``cms.env.json`` files; just follow the instructions to add a site theme in http://localhost/admin (starting from step 3).
|
||||
|
||||
Installing extra xblocks and requirements
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Would you like to include custom xblocks, or extra requirements to your Open edX platform? Additional requirements can be added to the ``env/build/openedx/requirements/private.txt`` file. For instance, to include the `polling xblock from Opencraft <https://github.com/open-craft/xblock-poll/>`_::
|
||||
|
||||
echo "git+https://github.com/open-craft/xblock-poll.git" >> $(tutor config printroot)/env/build/openedx/requirements/private.txt
|
||||
|
||||
Then, the ``openedx`` docker image must be rebuilt::
|
||||
|
||||
tutor images build openedx
|
||||
|
||||
To install xblocks from a private repository that requires authentication, you must first clone the repository inside the ``openedx/requirements`` folder on the host::
|
||||
|
||||
git clone git@github.com:me/myprivaterepo.git ./openedx/requirements/myprivaterepo
|
||||
|
||||
Then, declare your extra requirements with the ``-e`` flag in ``openedx/requirements/private.txt``::
|
||||
|
||||
echo "-e ./myprivaterepo" >> $(tutor config printroot)/env/build/openedx/requirements/private.txt
|
||||
|
||||
.. _edx_platform_fork:
|
||||
|
||||
Running a fork of ``edx-platform``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You may want to run your own flavor of edx-platform instead of the `official version <https://github.com/edx/edx-platform/>`_. To do so, you will have to re-build the openedx image with the proper environment variables pointing to your repository and version::
|
||||
|
||||
tutor images build openedx \
|
||||
--build-arg EDX_PLATFORM_REPOSITORY=https://mygitrepo/edx-platform.git \
|
||||
--build-arg EDX_PLATFORM_VERSION=my-tag-or-branch
|
||||
|
||||
Note that your release must be a fork of Ironwood in order to work. Otherwise, you may have important compatibility issues with other services. In particular, **don't try to run Tutor with older versions of Open edX**.
|
||||
|
||||
Running a different ``openedx`` Docker image
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default, Tutor runs the `regis/openedx <https://hub.docker.com/r/regis/openedx/>`_ docker image from Docker Hub. If you have an account on `hub.docker.com <https://hub.docker.com>`_ or you have a private image registry, you can build your image and push it to your registry with::
|
||||
|
||||
tutor config save -y --set DOCKER_IMAGE_OPENEDX=myusername/openedx:mytag
|
||||
tutor images build openedx
|
||||
tutor images push openedx
|
||||
|
||||
(See the relevant :ref:`configuration parameters <docker_images>`.)
|
||||
|
||||
The customised Docker image tag value will then be used by Tutor to run the platform, for instance when running ``tutor local quickstart``.
|
||||
|
|
|
|||
|
|
@ -1,85 +0,0 @@
|
|||
.. _customise:
|
||||
|
||||
Open edX platform customisation
|
||||
===============================
|
||||
|
||||
There are different ways you can customise your Open edX platform. For instance, optional features can be activated during configuration. But if you want to add unique features to your Open edX platform, you are going to have to modify and re-build the ``openedx`` docker image. This is the image that contains the ``edx-platform`` repository: it is in charge of running the web application for the Open edX "core". Both the LMS and the CMS run from the ``openedx`` docker image.
|
||||
|
||||
On a vanilla platform deployed by Tutor, the image that is run is downloaded from the `regis/openedx repository on Docker Hub <https://hub.docker.com/r/regis/openedx/>`_. This is also the image that is downloaded whenever we run ``tutor local pullimages``. But you can decide to build the image locally instead of downloading it. To do so, build and tag the ``openedx`` image::
|
||||
|
||||
tutor images build openedx
|
||||
|
||||
The following sections describe how to modify various aspects of the docker image. Every time, you will have to re-build your own image with this command. Re-building should take ~20 minutes on a server with good bandwidth. After building a custom image, you should stop the old running containers::
|
||||
|
||||
tutor local stop openedx
|
||||
|
||||
The custom image will be used the next time you run ``tutor local quickstart`` or ``tutor local start``. Do not attempt to run ``tutor local restart``! Restarting will not pick up the new image and will continue to use the old image.
|
||||
|
||||
Adding custom themes
|
||||
--------------------
|
||||
|
||||
Comprehensive theming is enabled by default, but only the default theme is compiled. To compile your own theme, add it to the ``env/build/openedx/themes/`` folder::
|
||||
|
||||
git clone https://github.com/me/myopenedxtheme.git $(tutor config printroot)/env/build/openedx/themes/
|
||||
|
||||
The ``themes`` folder should have the following structure::
|
||||
|
||||
openedx/themes/
|
||||
mycustomtheme1/
|
||||
cms/
|
||||
...
|
||||
lms/
|
||||
...
|
||||
mycustomtheme2/
|
||||
...
|
||||
|
||||
Then you must rebuild the openedx Docker image::
|
||||
|
||||
tutor images build openedx
|
||||
|
||||
Finally, follow the `Open edX documentation to apply your themes <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/changing_appearance/theming/enable_themes.html#apply-a-theme-to-a-site>`_. You will not have to modify the ``lms.env.json``/``cms.env.json`` files; just follow the instructions to add a site theme in http://localhost/admin (starting from step 3).
|
||||
|
||||
Installing extra xblocks and requirements
|
||||
-----------------------------------------
|
||||
|
||||
Would you like to include custom xblocks, or extra requirements to your Open edX platform? Additional requirements can be added to the ``env/build/openedx/requirements/private.txt`` file. For instance, to include the `polling xblock from Opencraft <https://github.com/open-craft/xblock-poll/>`_::
|
||||
|
||||
echo "git+https://github.com/open-craft/xblock-poll.git" >> $(tutor config printroot)/env/build/openedx/requirements/private.txt
|
||||
|
||||
Then, the ``openedx`` docker image must be rebuilt::
|
||||
|
||||
tutor images build openedx
|
||||
|
||||
To install xblocks from a private repository that requires authentication, you must first clone the repository inside the ``openedx/requirements`` folder on the host::
|
||||
|
||||
git clone git@github.com:me/myprivaterepo.git ./openedx/requirements/myprivaterepo
|
||||
|
||||
Then, declare your extra requirements with the ``-e`` flag in ``openedx/requirements/private.txt``::
|
||||
|
||||
echo "-e ./myprivaterepo" >> $(tutor config printroot)/env/build/openedx/requirements/private.txt
|
||||
|
||||
.. _edx_platform_fork:
|
||||
|
||||
Running a fork of ``edx-platform``
|
||||
----------------------------------
|
||||
|
||||
You may want to run your own flavor of edx-platform instead of the `official version <https://github.com/edx/edx-platform/>`_. To do so, you will have to re-build the openedx image with the proper environment variables pointing to your repository and version::
|
||||
|
||||
tutor images build openedx \
|
||||
--build-arg EDX_PLATFORM_REPOSITORY=https://mygitrepo/edx-platform.git \
|
||||
--build-arg EDX_PLATFORM_VERSION=my-tag-or-branch
|
||||
|
||||
Note that your release must be a fork of Ironwood in order to work. Otherwise, you may have important compatibility issues with other services. In particular, **don't try to run Tutor with older versions of Open edX**.
|
||||
|
||||
Running a different ``openedx`` Docker image
|
||||
--------------------------------------------
|
||||
|
||||
By default, Tutor runs the `regis/openedx <https://hub.docker.com/r/regis/openedx/>`_ docker image from Docker Hub. If you have an account on `hub.docker.com <https://hub.docker.com>`_ or you have a private image registry, you can build your image and push it to your registry with::
|
||||
|
||||
tutor config save -y --set DOCKER_IMAGE_OPENEDX=myusername/openedx:mytag
|
||||
tutor images build openedx
|
||||
tutor images push openedx
|
||||
|
||||
(See the relevant :ref:`configuration parameters <docker_images>`.)
|
||||
|
||||
The customised Docker image tag value will then be used by Tutor to run the platform, for instance when running ``tutor local quickstart``.
|
||||
10
docs/dev.rst
10
docs/dev.rst
|
|
@ -1,15 +1,15 @@
|
|||
.. _development:
|
||||
|
||||
Using Tutor for Open edX development
|
||||
====================================
|
||||
Open edX development
|
||||
====================
|
||||
|
||||
In addition to running Open edX in production, you can use the docker containers for local development. This means you can hack on Open edX without setting up a Virtual Machine. Essentially, this replaces the devstack provided by edX.
|
||||
In addition to running Open edX in production, Tutor can be used for local development of Open edX. This means it is possible to hack on Open edX without setting up a Virtual Machine. Essentially, this replaces the devstack provided by edX.
|
||||
|
||||
The following commands assume you have previously launched a local Open edX platform. If you have not done so already, you should run::
|
||||
The following commands assume you have previously launched a :ref:`local <local>` Open edX platform. If you have not done so already, you should run::
|
||||
|
||||
tutor local quickstart
|
||||
|
||||
You should setup real host names for the LMS and the CMS (i.e: not "localhost"). It is not necessary to configure the DNS records for local development. You should *not* activate HTTPS certificates, which will not work locally.
|
||||
You should setup real host names for the LMS and the CMS (i.e: not "localhost"). It is not necessary to configure the DNS records for local development: in other words, it doesn't matter that the chosen domain names exist or not for your platform, as the LMS and the CMS will be accessed on ``localhost``. You should *not* activate HTTPS certificates, which will not work locally.
|
||||
|
||||
Once the local platform has been configured, you should stop it so that it does not interfere with the development environment::
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,43 @@
|
|||
.. _extra:
|
||||
|
||||
Extra features
|
||||
==============
|
||||
|
||||
.. _webui:
|
||||
|
||||
Web UI
|
||||
------
|
||||
|
||||
Tutor comes with a web user interface (UI) that allows you to administer your Open edX platform remotely. It's especially convenient for remote administration of the platform.
|
||||
|
||||
Launching the web UI
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
|
||||
tutor webui start
|
||||
|
||||
You can then access the interface at http://localhost:3737, or http://youserverurl:3737.
|
||||
|
||||
.. image:: img/webui.png
|
||||
|
||||
All ``tutor`` commands can be executed from this web UI: you just don't need to prefix the commands with ``tutor``. For instance, to deploy a local Open edX instance, run::
|
||||
|
||||
local quickstart
|
||||
|
||||
instead of ``tutor local quickstart``.
|
||||
|
||||
Authentication
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
**WARNING** Once you launch the web UI, it is accessible by everyone, which means that your Open edX platform is at risk. If you are planning to leave the web UI up for a long time, you should setup a user and password for authentication::
|
||||
|
||||
tutor webui configure
|
||||
|
||||
.. _mobile:
|
||||
|
||||
Mobile Android application
|
||||
==========================
|
||||
--------------------------
|
||||
|
||||
With Tutor, you can build an Android mobile application for your platform. To build the application in debug mode, run::
|
||||
|
||||
|
|
@ -10,7 +46,7 @@ With Tutor, you can build an Android mobile application for your platform. To bu
|
|||
The ``.apk`` file will then be available in ``$TUTOR_ROOT/data/android``. Transfer it to an Android phone to install the application. You should be able to sign in and view available courses.
|
||||
|
||||
Releasing an Android app
|
||||
------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Note**: this is an untested feature.
|
||||
|
||||
|
|
@ -25,6 +61,6 @@ Then, place your keystore file in ``$TUTOR_ROOT/env/android/app.keystore``. Fina
|
|||
tutor android build release
|
||||
|
||||
Customising the Android app
|
||||
---------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Customising the application, such as the logo or the background image, is currently not supported. If you are interested by this feature, please tell us about it in the Tutor `discussion forums <https://discuss.overhang.io>`_.
|
||||
20
docs/faq.rst
20
docs/faq.rst
|
|
@ -6,7 +6,16 @@ FAQ
|
|||
What is Tutor?
|
||||
--------------
|
||||
|
||||
Tutor is a distribution of `Open edX <https://open.edx.org>`_. It uses the original code from the various Open edX repositories, such as `edx-platform <https://github.com/edx/edx-platform/>`_, `cs_comments_service <https://github.com/edx/cs_comments_service>`_, etc. and packages everything in a way that makes it very easy to install, administer and upgrade Open edX. In particular, all services are run inside Docker containers.
|
||||
Tutor is an open source distribution of `Open edX <https://open.edx.org>`_. It uses the original code from the various Open edX repositories, such as `edx-platform <https://github.com/edx/edx-platform/>`_, `cs_comments_service <https://github.com/edx/cs_comments_service>`_, etc. and packages everything in a way that makes it very easy to install, administer and upgrade Open edX. In particular, all services are run inside Docker containers.
|
||||
|
||||
Tutor makes it possible to deploy Open edX locally, with `docker-compose <https://docs.docker.com/compose/overview/>`_ or on an existing `Kubernetes cluster <http://kubernetes.io/>`_.
|
||||
|
||||
What is the purpose of Tutor?
|
||||
-----------------------------
|
||||
|
||||
To make it possible to deploy, administer and upgrade Open edX anywhere, easily.
|
||||
|
||||
.. _native:
|
||||
|
||||
What's the difference with the official "native" install?
|
||||
---------------------------------------------------------
|
||||
|
|
@ -42,11 +51,16 @@ Those features are currently not available in Tutor:
|
|||
|
||||
Those extra services were considered low priority while developing this project, but we are planning on adding them to Tutor, eventually. If you need one or more of these services, feel free to let me know by opening a `Github issue <https://github.com/regisb/tutor/issues/>`_. In particular, support for the Analytics stack is going to require a lot of work and I am looking forward to financial sponsorship. Please get in touch if you're interested.
|
||||
|
||||
Are there people already running this in production?
|
||||
----------------------------------------------------
|
||||
|
||||
Yes, many of them. There is no way to count precisely how many running Open edX platforms were deployed with Tutor, but from feedback collected directly from real users, there must be dozens, if not hundreds. Tutor is also used by some Open edX providers who are hosting platforms for their customers.
|
||||
|
||||
Why should I trust software written by some random guy on the Internet?
|
||||
-----------------------------------------------------------------------
|
||||
|
||||
You shouldn't :) I'm `Régis Behmo <https://github.com/regisb/>`_ and I have been working on Tutor since early 2018. I have been a contributor of the Open edX project since 2015. In particular, I have worked for 2 years on `FUN-MOOC <https://www.fun-mooc.fr/>`_, one of the top 5 largest Open edX platforms in the world. Here are the talks I have presented at the Open edX conferences:
|
||||
|
||||
- *FUN: Life in the Avant-Garde*, Oct. 2015 (`video <https://www.youtube.com/watch?v=V1EBo1l8BgY>`__, `slides <http://regisb.github.io/openedx-conference-2015/>`__)
|
||||
- *Open edX 101: A Source Code Review*, June 2016 (`video <https://www.youtube.com/watch?v=DVku7Y7XQII>`__, `slides <http://regisb.github.io/openedx-conference-2016/>`__)
|
||||
- *Videofront: a Self-Hosted YouTube*, June 2017 (`video <https://www.youtube.com/watch?v=e7bJchJrmP8&t=5m53s>`__, `slides <http://regisb.github.io/openedx-conference-2017/>`__)
|
||||
- *Open edX 101: A Source Code Review*, June 2016 (`video <https://www.youtube.com/watch?v=DVku7Y7XQII>`__, `slides <http://regisb.github.io/openedx-conference-2016/>`__)
|
||||
- *FUN: Life in the Avant-Garde*, Oct. 2015 (`video <https://www.youtube.com/watch?v=V1EBo1l8BgY>`__, `slides <http://regisb.github.io/openedx-conference-2015/>`__)
|
||||
|
|
|
|||
|
|
@ -11,21 +11,18 @@
|
|||
.. include:: quickstart.rst
|
||||
:start-line: 1
|
||||
|
||||
But there's a lot more to Tutor than that! For more advanced usage, please refer to the following sections.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: User guide
|
||||
|
||||
intro
|
||||
install
|
||||
quickstart
|
||||
configuration
|
||||
local
|
||||
customise
|
||||
dev
|
||||
k8s
|
||||
webui
|
||||
mobile
|
||||
dev
|
||||
extra
|
||||
troubleshooting
|
||||
tutor
|
||||
faq
|
||||
|
|
|
|||
|
|
@ -0,0 +1,47 @@
|
|||
.. _intro:
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
`Open edX <http://open.edx.org/>`_ is a thriving open source project, backed by a great community, for running an online learning platform at scale. Historically, it's always been :ref:`difficult <native>` to install Open edX. The goal of Tutor is to solve this issue.
|
||||
|
||||
Tutor simplifies the deployment of Open edX by:
|
||||
|
||||
1. Separating the configuration logic from the deployment platforms.
|
||||
2. Running application processes in cleanly separated `docker containers <https://www.docker.com/resources/what-container>`_.
|
||||
|
||||
Because Docker containers are becoming an industry-wide standard, that means that with Tutor it becomes possible to run Open edX anywhere: for now, Tutor supports deploying on a local server, with `docker-compose <https://docs.docker.com/compose/overview/>`_, and in a large cluster, with `Kubernetes <http://kubernetes.io/>`_. But in the future, Tutor may support other deployment platforms.
|
||||
|
||||
How does Tutor work?
|
||||
--------------------
|
||||
|
||||
You can experiment with Tutor very quickly: start by `installing <install>`_ Tutor. Then run::
|
||||
|
||||
tutor config save
|
||||
|
||||
This command does two things:
|
||||
|
||||
1. Generate a ``config.yml`` configuration file: this file contains core :ref:`configuration parameters <configuration>` for your Open edX platforms, such as passwords and feature flags.
|
||||
2. Generate an ``env/`` folder, which we call the Tutor "environment", and which contains all the files that are necessary to run an Open edX platform: these are mostly Open edX configuration files.
|
||||
|
||||
All these files are stored in a single folder, called the Tutor project root. On Linux, this folder is in ``~/.local/share/tutor`` and on Mac OS it is ``~/Library/Application Support/tutor``.
|
||||
|
||||
The values from ``config.yml`` are used to generate the environment files in ``env/``. As a consequence, **every time the values from** ``config.yml`` **are modified, the environment must be regenerated**. This can be done with::
|
||||
|
||||
tutor config save -y
|
||||
|
||||
Another consequence is that **any manual change made to a file in** ``env/`` **will be overwritten by** ``tutor config save`` **commands**. Consider yourself warned ;-)
|
||||
|
||||
Running Open edX
|
||||
----------------
|
||||
|
||||
Now that you have generated a configuration and environment, you probably want to run Open edX.
|
||||
|
||||
- The most simple and popular use case is to `run Open edX locally, on a single server <local>`_, with docker-compose.
|
||||
- If you have a running cluster, you can use Tutor to `deploy Open edX on Kubernetes <k8s>`_.
|
||||
- Are you an Open edX developer? You can use Tutor for `hacking into the internals of edx-platform <development>`_.
|
||||
|
||||
Bells and whistles
|
||||
------------------
|
||||
|
||||
For more advanced usage of Tutor, take a look at the :ref:`configuration and customisation <configuration_customisation>` and the :ref:`extra <extra>` sections
|
||||
|
|
@ -21,3 +21,5 @@ Yes :) This is what happens when you run ``tutor local quickstart``:
|
|||
5. A full, production-ready platform is run with docker-compose.
|
||||
|
||||
The whole procedure should require less than 10 minutes, on a server with a good bandwidth. Note that your host environment will not be affected in any way, since everything runs inside docker containers. Root access is not even necessary.
|
||||
|
||||
There's a lot more to Tutor than that! To understand what Tutor does and how it works, take a look at the :ref:`introduction <intro>`.
|
||||
|
|
@ -46,12 +46,12 @@ Bundle ``tutor`` executable
|
|||
|
||||
make bundle
|
||||
|
||||
Generate the documentation
|
||||
--------------------------
|
||||
Generating the documentation
|
||||
----------------------------
|
||||
|
||||
::
|
||||
|
||||
pip install sphinx sphinx_rtd_theme
|
||||
pip install -r requirements/docs.txt
|
||||
cd docs/
|
||||
make html
|
||||
|
||||
|
|
|
|||
|
|
@ -1,30 +0,0 @@
|
|||
.. _webui:
|
||||
|
||||
Web UI
|
||||
======
|
||||
|
||||
Tutor comes with a web user interface (UI) that allows you to administer your Open edX platform remotely. It's especially convenient for remote administration of the platform.
|
||||
|
||||
Launching the web UI
|
||||
--------------------
|
||||
|
||||
::
|
||||
|
||||
tutor webui start
|
||||
|
||||
You can then access the interface at http://localhost:3737, or http://youserverurl:3737.
|
||||
|
||||
.. image:: img/webui.png
|
||||
|
||||
All ``tutor`` commands can be executed from this web UI: you just don't need to prefix the commands with ``tutor``. For instance, to deploy a local Open edX instance, run::
|
||||
|
||||
local quickstart
|
||||
|
||||
instead of ``tutor local quickstart``.
|
||||
|
||||
Authentication
|
||||
--------------
|
||||
|
||||
**WARNING** Once you launch the web UI, it is accessible by everyone, which means that your Open edX platform is at risk. If you are planning to leave the web UI up for a long time, you should setup a user and password for authentication::
|
||||
|
||||
tutor webui configure
|
||||
Loading…
Reference in New Issue