From f2c476f954ceb4f72c0630df2c4e6a2ff0990af7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9gis=20Behmo?= Date: Wed, 26 Dec 2018 16:00:47 +0100 Subject: [PATCH] Improve documentation --- Makefile | 15 ++++---- README.md | 15 -------- README.rst | 39 ++++++++++++++++++++ docs/Makefile | 11 ++++-- docs/customise.rst | 36 ++++++++++--------- docs/dev.rst | 23 ++++++++---- docs/index.rst | 34 ++++++------------ docs/missing.rst | 4 +++ docs/options.rst | 2 ++ docs/quickstart.rst | 22 ++++++++++++ docs/requirements.rst | 6 ++-- docs/step.rst | 78 +++++++++++++++++----------------------- docs/troubleshooting.rst | 25 +++++++++++++ docs/tutor.rst | 11 ++++++ 14 files changed, 204 insertions(+), 117 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/quickstart.rst create mode 100644 docs/tutor.rst diff --git a/Makefile b/Makefile index c8e83ca..72c8101 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ USERID ?= $$(id -u) build: ## Build all docker images cd build/ && make build -config.json: +config.json: upgrade-to-tutor @$(MAKE) -s -C build/ build-configurator 1> /dev/null @docker run --rm -it \ --volume="$(PWD):/openedx/config/" \ @@ -23,20 +23,23 @@ substitute: config.json regis/openedx-configurator:hawthorn \ configurator substitute /openedx/templates/ /openedx/output/ -singleserver: ## Configure and run a ready-to-go Open edX platform - cd deploy/ && make all +singleserver: upgrade-to-tutor ## Configure and run a ready-to-go Open edX platform + $(MAKE) -C deploy/singleserver all -android: ## Configure and build a development Android app +stop: ## Stop all single server services + $(MAKE) -C deploy/singleserver stop + +android: upgrade-to-tutor ## Configure and build a development Android app cd android/ && make all -travis: +travis: upgrade-to-tutor cd build && make build cd deploy/singleserver \ && make configure SILENT=1 CONFIGURE_OPTS="-e SETTING_ACTIVATE_NOTES=1 -e SETTING_ACTIVATE_XQUEUE=1" \ && make databases \ && make assets -upgrade-to-tutor: +upgrade-to-tutor: ## Upgrade from earlier versions of tutor @(stat config/config.json > /dev/null 2>&1 && (\ echo "You are running an older version of Tutor. Now migrating to the latest version" \ && echo "Moving config/config.json to ./config.json" && mv config/config.json config.json \ diff --git a/README.md b/README.md deleted file mode 100644 index 1d9e217..0000000 --- a/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Tutor: Open edX 1-click install for everyone - -![Build status](https://img.shields.io/travis/regisb/openedx-docker.svg) -![GitHub issues](https://img.shields.io/github/issues/regisb/openedx-docker.svg) -![GitHub closed issues](https://img.shields.io/github/issues-closed/regisb/openedx-docker.svg?colorB=brightgreen) - -Tutor is a one-click install of [Open edX](https://openedx.org), both for production and local development, inside docker containers. - -[![asciicast](https://asciinema.org/a/6DowVk4iJf3AJ2m8xlXDWJKh3.png)](https://asciinema.org/a/6DowVk4iJf3AJ2m8xlXDWJKh3) - -# Quickstart - - git clone https://github.com/regisb/openedx-docker - cd openedx-docker/ - make singleserver diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..68256aa --- /dev/null +++ b/README.rst @@ -0,0 +1,39 @@ +Tutor 🎓 Open edX 1-click install for everyone +============================================== + +.. image:: https://img.shields.io/travis/regisb/openedx-docker.svg + :alt: Build status + :target: https://travis-ci.org/regisb/openedx-docker + +.. image:: https://img.shields.io/github/issues/regisb/openedx-docker.svg + :alt: GitHub issues + :target: https://github.com/regisb/openedx-docker/issues + +.. image:: https://img.shields.io/github/issues-closed/regisb/openedx-docker.svg?colorB=brightgreen + :alt: GitHub closed issues + :target: https://github.com/regisb/openedx-docker/issues?q=is%3Aclosed + +**Tutor** is a one-click install of `Open edX `_, both for production and local development, inside docker containers. Tutor is easy to run, fast, full of cool features, and it is already used by dozens of Open edX platforms in the world. + +.. image:: https://asciinema.org/a/6DowVk4iJf3AJ2m8xlXDWJKh3.png + :alt: asciicast + :target: https://asciinema.org/a/6DowVk4iJf3AJ2m8xlXDWJKh3 + +Quickstart +---------- + +:: + + git clone https://github.com/regisb/openedx-docker + cd openedx-docker/ + make singleserver + +Documentation +------------- + +Extensive documentation is available online: https://tutor.readthedocs.io/ + +How to contribute +----------------- + +We go to great lengths to make it as easy as possible for people to run Open edX inside Docker containers. If you have an improvement idea, feel free to `open an issue on Github `_ so that we can discuss it. `Pull requests `_ will be happily examined, too! However, we should be careful to keep the project lean and simple: both to use and to modify. Optional features should not make the user experience more complex. Instead, documentation on how to add the feature is preferred. diff --git a/docs/Makefile b/docs/Makefile index 298ea9e..e4ffe88 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,5 +1,4 @@ -# Minimal makefile for Sphinx documentation -# +.DEFAULT_GOAL := html # You can set these variables from the command line. SPHINXOPTS = @@ -11,9 +10,15 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +browse: + sensible-browser _build/html/index.html + +watch: + 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) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/customise.rst b/docs/customise.rst index 219aad5..559baf7 100644 --- a/docs/customise.rst +++ b/docs/customise.rst @@ -1,7 +1,13 @@ +.. _customise: + Customising the ``openedx`` docker image ======================================== -The LMS and the CMS all run from the ``openedx`` docker image. The base image is downloaded from `Docker Hub `_ when we run ``make update`` (or ``make all``). But you can also customise and build the image yourself. The base image is built with:: +The LMS and the CMS all run from the ``openedx`` docker image. The base image is downloaded from `Docker Hub `_ when we run ``make update`` (or ``make all``). But you can also customise and build the image yourself. All image-building commands must be run inside the ``build`` folder:: + + cd build + +Build the base image with:: make build-openedx @@ -12,7 +18,11 @@ The following sections describe how to modify various aspects of the docker imag Custom themes ------------- -Comprehensive theming is enabled by default. Put your themes in ``openedx/themes/``:: +Comprehensive theming is enabled by default, but only the default theme is compiled. To compile your own theme, add it to the ``build/openedx/themes/`` folder:: + + git clone https://github.com/me/myopenedxtheme.git build/openedx/themes/ + +The ``themes`` folder should have the following structure:: openedx/themes/ mycustomtheme1/ @@ -36,7 +46,7 @@ Finally, follow the `Open edX documentation to enable your themes `_:: echo "git+https://github.com/open-craft/xblock-poll.git" >> openedx/requirements/private.txt @@ -57,28 +67,22 @@ Forked version of edx-platform You may want to run your own flavor of edx-platform instead of the `official version `_. To do so, you will have to re-build the openedx image with the proper environment variables pointing to your repository and version:: - EDX_PLATFORM_REPOSITORY=https://mygitrepo/edx-platform.git EDX_PLATFORM_VERSION=my-tag-or-branch make build-openedx + export EDX_PLATFORM_REPOSITORY=https://mygitrepo/edx-platform.git EDX_PLATFORM_VERSION=my-tag-or-branch + make build-openedx You can then restart the services which will now be running your forked version of edx-platform:: make restart-openedx -Note that your release must be a fork of Hawthorn in order to work. Otherwise, you may have important compatibility issues with other services. +Note that your release must be a fork of Hawthorn 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 Docker image instead of `regis/openedx `_ ------------------------------------------------------------------------------------------------------- +Running a different ``openedx`` Docker image +-------------------------------------------- -This is for people who have an account on `hub.docker.com `_ or a private image registry. You can build your image and push it to your repo. Then add the following content to the ``.env`` file:: +By default, Tutor runs the `regis/openedx `_ docker image from Docker Hub. If you have an account on `hub.docker.com `_ or you have a private image registry, you can build your image and push it to your registry. Then add the following content to the ``deploy/singleserver/.env`` file:: OPENEDX_DOCKER_IMAGE=myusername/myimage:mytag Your own image will be used next time you run ``make run``. -Note that the ``make build`` and ``make push`` command will no longer work as you expect and that you are responsible for building and pushing the image yourself. - -Maintainers ------------ - -The images are built, tagged and uploaded to Docker Hub in one command:: - - make dockerhub +Note that the ``make build`` and ``make push`` commands (from the ``build/`` folder) will no longer work as you expect and that you are responsible for building and pushing the image yourself. diff --git a/docs/dev.rst b/docs/dev.rst index 0a6b35a..c16e8f1 100644 --- a/docs/dev.rst +++ b/docs/dev.rst @@ -1,7 +1,7 @@ .. _development: -Open edX development -==================== +Using Tutor for 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. @@ -38,15 +38,16 @@ All development commands will then automatically mount your local repo. For inst make lms-runserver -Note: containers are built on the Hawthorn release. If you are working on a different version of Open edX, you will have to rebuild the images with the right ``EDX_PLATFORM_VERSION`` argument. You may also want to change the ``EDX_PLATFORM_REPOSITORY`` argument to point to your own fork of edx-platform. - -With a customised edx-platform repo, you must be careful to have settings that are compatible with the docker environment. You are encouraged to copy the ``tutor.development`` settings files to our own repo: +With a customised edx-platform repo, you must be careful to have settings that are compatible with the docker environment. You are encouraged to copy the ``tutor.development`` settings files to our own repo:: cp -r config/openedx/tutor/lms/ /path/to/edx-platform/lms/envs/tutor cp -r config/openedx/tutor/cms/ /path/to/edx-platform/cms/envs/tutor You can then run your platform with the ``tutor.development`` settings. +**Note**: containers are built on the Hawthorn release. If you are working on a different version of Open edX, you will have to rebuild the images with the right ``EDX_PLATFORM_VERSION`` argument. You may also want to change the ``EDX_PLATFORM_REPOSITORY`` argument to point to your own fork of edx-platform. + + Develop customised themes ------------------------- @@ -54,7 +55,7 @@ Run a local webserver:: make lms-runserver -Watch the themes folders for changes:: +Watch the themes folders for changes (in a different terminal):: make watch-themes @@ -68,3 +69,13 @@ Assets building and collecting is made more difficult by the fact that developme openedx-assets build This command will take quite some time to run. You can speed up this process by running only part of the full build. Run ``openedx-assets -h`` for more information. + +Running python commands +----------------------- + +These commands will open a python shell in the lms or the cms:: + + make lms-python + make cms-python + +You can then import edx-platform and django modules and execute python code. diff --git a/docs/index.rst b/docs/index.rst index 39f3bbf..8b57f3c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,8 +3,8 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Tutor: Open edX 1-click install for everyone -============================================ +Tutor 🎓 Open edX 1-click install for everyone +============================================== .. image:: https://img.shields.io/travis/regisb/openedx-docker.svg :alt: Build status @@ -18,7 +18,7 @@ Tutor: Open edX 1-click install for everyone :alt: GitHub closed issues :target: https://github.com/regisb/openedx-docker/issues?q=is%3Aclosed -Tutor is a one-click install of `Open edX `_, both for production and local development, inside docker containers. +**Tutor** is a one-click install of `Open edX `_, both for production and local development, inside docker containers. Tutor is easy to run, fast, full of cool features, and it is already used by dozens of Open edX platforms in the world. .. image:: https://asciinema.org/a/6DowVk4iJf3AJ2m8xlXDWJKh3.png :alt: asciicast @@ -26,26 +26,16 @@ Tutor is a one-click install of `Open edX `_, both for prod ---------------------------------- -**Quickstart**:: +.. include:: quickstart.rst + :start-line: 1 - git clone https://github.com/regisb/openedx-docker - cd openedx-docker/ - make all - -**That's it?** - -Yes :) When running `make all`, you will be asked a few questions about the configuration of your Open edX platform. Then, all the components for a functional Open edX platform will be downloaded and assembled to and you will have both an LMS and a CMS running behind a web server on port 80, ready for production. You should be able to access your platform at the address you gave during the configuration phase. - -All of this without touching your host environment! You don't even need root access. - -To be honest, I really don't like 1-click installs :-p They tend to hide much of the important details. So I strongly recommend you read the more detailed instructions below to understand what is going on exactly and to troubleshoot potential issues. Also, instructions are given to setup a local development environment. - -This might seem too simple to be true, but there's no magic -- just good packaging of already existing Open edX code. The code for building the Docker images is 100% available and fits in less than 1000 lines of code, in this repository. +For more advanced usage of Tutor, please refer to the following sections. .. toctree:: :maxdepth: 2 :caption: User guide + quickstart requirements step options @@ -53,23 +43,19 @@ This might seem too simple to be true, but there's no magic -- just good packagi dev troubleshooting missing + tutor Disclaimers & Warnings ---------------------- This project is the follow-up of my work on an `install from scratch of Open edX `_. It does not rely on any hack or complex deployment script. In particular, we do not use the Open edX `Ansible deployment playbooks `_. That means that the folks at edX.org are *not* responsible for troubleshooting issues of this project. Please don't bother Ned ;-) -Do you have a problem? - -1. Carefully read the README, and in particular the :ref:`troubleshooting` section -2. Search for your problem in the `open and closed Github issues `_. -3. If necessary, open an `issue on Github `_. - +In case of trouble, please follow the instructions in the :ref:`troubleshooting` section. Contributing ------------ -Pull requests will be happily examined! However, we should be careful to keep the project lean and simple: both to use and to modify. Optional features should not make the user experience more complex. Instead, documentation on how to add the feature is preferred. +We go to great lengths to make it as easy as possible for people to run Open edX inside Docker containers. If you have an improvement idea, feel free to `open an issue on Github `_ so that we can discuss it. `Pull requests `_ will be happily examined, too! However, we should be careful to keep the project lean and simple: both to use and to modify. Optional features should not make the user experience more complex. Instead, documentation on how to add the feature is preferred. License ------- diff --git a/docs/missing.rst b/docs/missing.rst index 26babcd..8468eaf 100644 --- a/docs/missing.rst +++ b/docs/missing.rst @@ -1,6 +1,10 @@ +.. _missing: + Missing features ================ +Those features are currently not available in Tutor: + - `discovery service `_ - `ecommerce `_ - `analytics `_ diff --git a/docs/options.rst b/docs/options.rst index 1419e85..170a009 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -1,3 +1,5 @@ +.. _options: + Optional features ================= diff --git a/docs/quickstart.rst b/docs/quickstart.rst new file mode 100644 index 0000000..96b02eb --- /dev/null +++ b/docs/quickstart.rst @@ -0,0 +1,22 @@ +.. _quickstart: + +Quickstart +========== + +:: + + git clone https://github.com/regisb/openedx-docker + cd openedx-docker/ + make singleserver + +**That's it?** + +Yes :) This is what happens when you run ``make all``: + +1. You answer a few questions about the configuration of your Open edX platform and your :ref:`selected options ` +2. Configuration files are generated. +3. Docker images are downloaded. +4. Docker containers are provisioned. +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. diff --git a/docs/requirements.rst b/docs/requirements.rst index eab3919..bdc309a 100644 --- a/docs/requirements.rst +++ b/docs/requirements.rst @@ -1,3 +1,5 @@ +.. _requirements: + Requirements ============ @@ -8,8 +10,8 @@ The only prerequisite for running this is a working docker install. You will nee Note that the production web server container will bind to port 80, so if you already have a web server running (Apache or Nginx, for instance), you should stop it. -You should be able to run Open edX on any platform that supports Docker and Python, including Mac OS and Windows. For now, only Ubuntu 16.04 was tested but we have no reason to believe the install would not work on a different OS. +You should be able to run Open edX on any platform that supports Docker, including Mac OS and Windows. Tutor was tested under various versions of Ubuntu and Mac OS. -At a minimum, the server running the containers should have 4 Gb of RAM; otherwise, the deployment procedure will crash during migrations (see the :ref:`troubleshooting` section). +At a minimum, the server running the containers should have 2 Gb of RAM; otherwise, the deployment procedure will crash during migrations (see the :ref:`troubleshooting` section). Also, the host running the containers should be a 64 bit platform. (images are not built for i386 systems) diff --git a/docs/step.rst b/docs/step.rst index 62d16d9..1eca28d 100644 --- a/docs/step.rst +++ b/docs/step.rst @@ -1,6 +1,12 @@ Step-by-step install ==================== +The following commands should be run inside the ``deploy/singlerver`` folder:: + + cd deploy/singleserver + +You can use these individual commands instead of running the full installation with ``make all``. + Configure --------- @@ -8,10 +14,12 @@ Configure make configure -This is the only non-automatic step in the install process. You will be asked various questions about your Open edX platform and appropriate configuration files will be generated. If you would like to automate this step then you should run ``make configure`` interactively once. After that, you will have a ``config.json`` file at the root of the repository. Just upload it to wherever you want to run Open edX and then run ``make configure SILENT=1`` instead of ``make configure``. All values from ``config.json`` will be automatically loaded. +This is the only non-automatic step in the install process. You will be asked various questions about your Open edX platform and appropriate configuration files will be generated. If you would like to automate this step then you should run ``make configure`` interactively once. After that, you will have a ``config.json`` file at the root of the repository. -Download --------- +If you want to run a fully automated install, upload the ``config.json`` file to wherever you want to run Open edX, and then run ``make configure SILENT=1`` instead of ``make configure``. All values from ``config.json`` will be automatically loaded. + +Download docker images +---------------------- :: @@ -25,12 +33,21 @@ Database creation, migrations and collection of static assets :: make databases - make assets -These commands should be run just once. They will create the required databases tables, apply database migrations and make sure that static assets, such as images, stylesheets and Javascript dependencies, can be served by the nginx container. +This command should be run just once. It will create the required databases tables and apply database migrations for all applications. + If migrations are stopped with a ``Killed`` message, this certainly means the docker containers don't have enough RAM. See the :ref:`troubleshooting` section. +Collecting static assets +------------------------ + +:: + + make assets + +This command also needs to be run just once. It will make sure that static assets, such as images, stylesheets and Javascript dependencies, can be served by the nginx container. + Running Open edX ---------------- @@ -40,12 +57,15 @@ Running Open edX This will launch the various docker containers required for your Open edX platform. The LMS and the Studio will then be reachable at the domain name you specified during the configuration step. You can also access them at http://localhost and http://studio.localhost. -Additional commands -------------------- +To stop the running containers, just hit Ctrl+C. -All available commands can be listed by running:: +In production, you will probably want to daemonize the services. Instead of ``make run``, run:: - make help + make daemonize + +And then, to stop all services:: + + make stop Creating a new user with staff and admin rights ----------------------------------------------- @@ -63,17 +83,6 @@ On a fresh install, your platform will not have a single course. To import the ` make import-demo-course -Daemonizing ------------ - -In production, you will probably want to daemonize the services. Instead of ``make run``, run:: - - make daemonize - -And then, to stop all services:: - - make stop - Updating the course search index -------------------------------- @@ -83,30 +92,9 @@ The course search index can be updated with:: Run this command periodically to ensure that course search results are always up-to-date. -Logging -------- +Additional commands +------------------- -To view the logs from all containers use the `docker-compose logs `_ command:: +All available commands can be listed by running:: - docker-compose logs -f - -To view the logs from just one container, for instance the web server:: - - docker-compose logs -f nginx - -The last commands produce the logs since the creation of the containers, which can be a lot. Similar to a ``tail -f``, you can run:: - - docker-compose logs --tail=0 -f - -Debugging ---------- - -Open a bash shell in the lms or the cms:: - - make lms - make cms - -Open a python shell in the lms or the cms:: - - make lms-python - make cms-python + make help diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index f2d3e81..cc3a553 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -3,6 +3,31 @@ Troubleshooting =============== +What should you do if you have a problem? + +1. Read the error logs that appear in the console. When running a single server platform as daemon, you can view the logs with the ``docker-compose logs`` command. (see :ref:`logging` below) +2. Check if your problem already has a solution right here in the :ref:`troubleshooting` section. +3. Search for your problem in the `open and closed Github issues `_. +4. If, despite all your efforts, you can't solve the problem, decide if the issue is related to Open edX or if it's specific to Tutor. In the latter case, you are most welcome to open an `issue on Github `_. **Please follow the instructions from the issue template!!!** Your issue will be examined in all cases, but you can make my life much easier by giving me as much background information as possible. + +.. _logging: + +Logging +------- + +To view the logs from all containers use the `docker-compose logs `_ command:: + + docker-compose logs -f + +To view the logs from just one container, for instance the web server:: + + docker-compose logs -f nginx + +The last commands produce the logs since the creation of the containers, which can be a lot. Similar to a ``tail -f``, you can run:: + + docker-compose logs --tail=0 -f + + "Cannot start service nginx: driver failed programming external connectivity" ----------------------------------------------------------------------------- diff --git a/docs/tutor.rst b/docs/tutor.rst new file mode 100644 index 0000000..678f4cd --- /dev/null +++ b/docs/tutor.rst @@ -0,0 +1,11 @@ +.. _tutor: + +Tutor development +================= + +Pushing to Docker Hub +--------------------- + +The images are built, tagged and uploaded to Docker Hub in one command:: + + make dockerhub