christianlight
/
tutor
mirror of https://github.com/ChristianLight/tutor.git
7
0
Fork 0
Code Issues Releases Activity

minor typos fixed

This commit is contained in:
Emad Rad 2022-03-27 15:06:55 +04:30 committed by Régis Behmo
parent 43c5177187
commit a25ae73031
28 changed files with 162 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

138
CHANGELOG.md
View File

@ -12,13 +12,13 @@ Note: Breaking changes between versions are indicated by "💥".
## v13.1.7 (2022-03-17)
- [Bugfix] Fix dockerize on arm64 by switching to the [powerman/dockerize](https://github.com/powerman/dockerize) fork (#591).
- [Bugfix] Fix "Unexpected args" error during service initialization on Kubernetes (#611).
- [Bugfix] Fix "Unexpected args" error during service initialisation on Kubernetes (#611).
## v13.1.6 (2022-03-15)
- [Bugfix] Fix `local/k8s quickstart` commands when upgrading from an older release (#595).
- [Bugfix] Fix running the default exim-relay SMTP server on arm64 (#600).
- [Feature] Add `tutor k8s apply` comand, which is a direct interface with `kubectl apply`.
- [Feature] Add `tutor k8s apply` command, which is a direct interface with `kubectl apply`.
- [Feature] Add `openedx-dockerfile-minimal` patch, which you can use to install custom packages and run commands as root in the Docker image.
## v13.1.5 (2022-02-14)
@ -27,7 +27,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v13.1.4 (2022-02-08)
- [Security] Fix vulnerability in redirect url during authentication (see [commit](https://github.com/overhangio/edx-platform/commit/06550411e34c04376fa3d757e1f068f464f816e6)).
- [Security] Fix vulnerability in redirect URL during authentication (see [commit](https://github.com/overhangio/edx-platform/commit/06550411e34c04376fa3d757e1f068f464f816e6)).
## v13.1.3 (2022-02-01)
@ -43,15 +43,15 @@ Note: Breaking changes between versions are indicated by "💥".
## v13.1.1 (2022-01-25)
- [Bugfix] Fix authentication in development due to missing SameSite policy on session ID cookie.
- [Bugfix] Display properly themed favicon.ico image in LMS, Studio and microfrontends.
- [Bugfix] Display properly themed favicon.ico image in LMS, Studio, and microfrontends.
- [Bugfix] Fix "LazyStaticAbsoluteUrl is not JSON serializable" error when sending bulk emails.
- [Bugfix] Fix `tutor local importdemocourse` fails when platform is not up.
- [Bugfix] Fix `tutor local importdemocourse` fails when the platform is not up.
## v13.1.0 (2022-01-08)
- [Improvement] Provide much more comprehensive instructions when upgrading.
- [Bugfix] During upgrade, make sure that environment is up-to-date prior to prompting to rebuild the custom images.
- [Bugfix] Fix ownership of mysql data, in particular when upgrading a Kubernetes cluster to Maple.
- [Bugfix] During the upgrade, make sure that the environment is up-to-date before prompting to rebuild the custom images.
- [Bugfix] Fix ownership of MySQL data, in particular when upgrading a Kubernetes cluster to Maple.
- [Bugfix] Ensure that ``tutor k8s upgrade`` is run during ``tutor k8s quickstart``, when necessary.
- 💥[Bugfix] By default, detect the current version during ``tutor k8s/local upgrade``.
- [Bugfix] Fix upgrading from Lilac to Maple on Kubernetes by deleting deployments and services.
@ -59,7 +59,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v13.0.3 (2022-01-04)
- [Security] Upgrade Django to 3.2.11 in edx-platform.
- [Security] Prevent non-staff users from searching usernames by email by abusing the logout url.
- [Security] Prevent non-staff users from searching usernames by email by abusing the logout URL.
## v13.0.2 (2021-12-22)
@ -93,7 +93,7 @@ Note: Breaking changes between versions are indicated by "💥".
- 💥[Improvement] Run all services as unprivileged containers, for better security. This has multiple consequences:
- The "openedx-dev" image is now built with `tutor dev dc build lms`.
- The "smtp" service now runs the "devture/exim-relay" Docker image, which is unprivileged. Also, the default SMTP port is now 8025.
- 💥[Feature] Get rid of the nginx container and service, which is now replaced by Caddy. this has the following consequences:
- 💥[Feature] Get rid of the Nginx container and service, which is now replaced by Caddy. this has the following consequences:
- Patches "nginx-cms", "nginx-lms", "nginx-extra", "local-docker-compose-nginx-aliases" are replaced by "caddyfile-cms", "caddyfile-lms", "caddyfile", " local-docker-compose-caddy-aliases".
- Patches "k8s-deployments-nginx-volume-mounts", "k8s-deployments-nginx-volumes" were obsolete and are removed.
- The `NGINX_HTTP_PORT` setting is renamed to `CADDY_HTTP_PORT`.
@ -104,7 +104,7 @@ Note: Breaking changes between versions are indicated by "💥".
- [Bugfix] Fix incorrect "from" address in course bulk emails (see [pull request](https://github.com/openedx/edx-platform/pull/29001)).
- 💥[Improvement] Fail on incorrect image name argument in `images build/pull/push/printtag` commands.
- [Bugfix] Remove trailing slashes in docker-compose files for [compatibility with docker-compose v2 in WSL](https://github.com/docker/compose/issues/8558).
- [Improvement] `settheme` now works with preview domain.
- [Improvement] `settheme` now works with the preview domain.
- [Feature] Allow specifying extra pip packages through config.yml.
## v12.1.7 (2021-11-18)
@ -112,7 +112,7 @@ Note: Breaking changes between versions are indicated by "💥".
- [Security] Timed exam security fix [29347](https://github.com/openedx/edx-platform/pull/29347).
- [Feature] Add [tutor-richie](https://github.com/overhangio/tutor-richie) to the plugins that are bundled with the tutor binary.
- [Improvement] Make `tutor plugins list` print plugins sorted by name.
- [Improvement] Ignore Python plugins which cannot be loaded.
- [Improvement] Ignore Python plugins that cannot be loaded.
- [Bugfix] When configured with `RUN_FORUM: false`, omit forum-related [Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/job/) from the manifests that `tutor k8s` generates. (#525)
## v12.1.6 (2021-11-02)
@ -151,7 +151,7 @@ Note: Breaking changes between versions are indicated by "💥".
- [Bugfix] Fix segmentation fault during `tutor config save` on Mac OS M1 (#473). Thanks @ghassanmas!
- [Bugfix] Fix a bug that prevented connecting to external MongoDB instances.
- [Improvement] Make sure that the logo included in email notifications (including discussion responses) is the same as the site logo.
- [Bugfix] Install IPython directly from pypi instead of installing it from source (the reason it was installed from source is no longer relevant). The effect of this shall speed up the process of building the openedx-dev Docker image.
- [Bugfix] Install IPython directly from PyPI instead of installing it from source (the reason it was installed from source is no longer relevant). The effect of this shall speed up the process of building the openedx-dev Docker image.
- [Feature] Add "openedx-dockerfile-post-git-checkout" patch.
- [Improvement] In the "openedx" Docker images, convert git patches to cherry-picks for a cleaner source tree.
- 💥[Feature] Make it possible to override local job configuration. This deprecates the older model for running jobs which dates back from a long time ago.
@ -170,12 +170,12 @@ Note: Breaking changes between versions are indicated by "💥".
## v12.0.2 (2021-07-06)
- [Bugfix] Fix "Invalid command argument" during upgrade from Koa to Lilac.
- [Bugfix] Fix mysql initialisation in docker-compose==2.0.0beta4.
- [Improvement] Tutor is now published on pypi as "tutor".
- [Bugfix] Fix MySQL initialisation in docker-compose==2.0.0beta4.
- [Improvement] Tutor is now published on PyPI as "tutor".
## v12.0.1 (2021-06-22)
- [Bugfix] Fix double pulling mongodb image when upgrading from Koa to Lilac.
- [Bugfix] Fix double pulling MongoDB image when upgrading from Koa to Lilac.
- [Improvement] Better logging during `plugins disable`.
- [Bugfix] Fix "upstream sent too big header" error during login of existing users after a Koa to Lilac upgrade.
- [Feature] Added the ability to skip `config.yml` file modification while running `tutor config save` command with `-e` or `--env-only` flag.
@ -200,7 +200,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v11.2.11 (2021-05-18)
- [Feature] Add redis database configuration for both cache and celery.
- [Feature] Add Redis database configuration for both cache and celery.
## v11.2.10 (2021-05-17)
@ -240,11 +240,11 @@ Note: Breaking changes between versions are indicated by "💥".
- [Improvement] Annotate types all over the Tutor code base.
- [Bugfix] Fix parsing of YAML CLI arguments that include equal "=" signs.
- [Bugfix] Fix minor edge case in `long_to_base64` utility function.
- [Improvement] Add openedx patches to add settings during build process.
- [Improvement] Add openedx patches to add settings during the build process.
## v11.2.3 (2021-02-20)
- [Bugfix] Make LMS celery workers actually process LMS tasks, and not CMS tasks.
- [Bugfix] Make LMS celery workers actually process LMS tasks and not CMS tasks.
## v11.2.2 (2021-02-17)
@ -326,12 +326,12 @@ Note: Breaking changes between versions are indicated by "💥".
- The ``NGINX_HTTPS_PORT`` setting is deprecated.
- Architectural changes:
- Use Caddy as a web proxy for automated SSL/TLS certificate generation:
- Nginx no longer listens to port 443 for https traffic.
- Nginx no longer listens to port 443 for HTTPS traffic.
- The Caddy configuration file comes with a new ``caddyfile`` patch for much simpler SSL/TLS management.
- Configuration files for web proxies are no longer provided.
- Kubernetes deployment no longer requires setting up a custom Ingress resource or custom manager.
- Gunicorn and Whitenoise are replaced by uwsgi: this increases boostrap performance and makes it no longer necessary to mount media folders in the Nginx container.
- Replace memcached and rabbitmq by redis.
- Gunicorn and Whitenoise are replaced with uwsgi: this increases bootstrap performance and makes it no longer necessary to mount media folders in the Nginx container.
- Replace Memcached and RabbitMQ with Redis.
- Additional features:
- Make it possible to disable all plugins at once with ``plugins disable all``.
- Add ``tutor k8s wait`` command to wait for a pod to become ready.
@ -339,7 +339,7 @@ Note: Breaking changes between versions are indicated by "💥".
- Deprecation: proxy files for Apache and Nginx are no longer provided out of the box.
- Removed plugin `{{ patch (...) }}` statements:
- "https-create", "k8s-ingress-rules", "k8s-ingress-tls-hosts": these are no longer necessary. Instead, declare your app in the "caddyfile" patch.
- "local-docker-compose-nginx-volumes": this patch was primarily used to serve media assets. The recommended is now to serve assets with uwsgi.
- "local-docker-compose-nginx-volumes": this patch was primarily used to serve media assets. The recommended solution is now to serve assets with uwsgi.
## v10.5.3 (2020-12-09)
@ -352,7 +352,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v10.5.1 (2020-11-30)
- [Bugfix] Fix Dockerfile parsing on Windows.
- [Improvement] Add option to patch lms and cms nginx server blocks.
- [Improvement] Add option to patch lms and cms Nginx server blocks.
## v10.5.0 (2020-11-19)
@ -408,7 +408,7 @@ Note: Breaking changes between versions are indicated by "💥".
- [Improvement] Add CORS basic configuration to LMS for subdomains of the LMS.
- [Feature] Add support for `images build --add-host` option (thanks @grinderz!).
- [Bugfix] Fix podman compatibility by replacing `docker-compose rm` command by `docker-compose stop` when stopping containers.
- [Bugfix] Fix podman compatibility by replacing `docker-compose rm` command with `docker-compose stop` when stopping containers.
- [Improvement] Improve plugin data deletion.
- [Improvement] Introduce the `OPENEDX_COMMON_VERSION` setting.
- [Bugfix] Make it possible to run init jobs without starting the entire platform.
@ -426,9 +426,9 @@ Note: Breaking changes between versions are indicated by "💥".
- [Bugfix] Fix Samesite=None Secure=False cookie error for users accessing the LMS with the latest release of Google Chrome.
- [Security] Apply javascript security patch ([pull request](https://github.com/openedx/edx-platform/pull/24762)).
- [Bugfix] Fix "FileError" on Scorm package upload in Scorm XBlock.
- 💥[Improvement] Serve openedx static assets with [whitenoise](http://whitenoise.evans.io/en/stable/) instead of nginx. This removes the `k8s-deployments-nginx-init-containers` patch. Plugins are encouraged to implement static asset serving with Whitenoise as well.
- [Bugfix] Fix dependency on mysql service when mysql is not activated.
- [Improvement] Improve openedx Docker image build time and size with multi-stage build.
- 💥[Improvement] Serve openedx static assets with [whitenoise](http://whitenoise.evans.io/en/stable/) instead of Nginx. This removes the `k8s-deployments-nginx-init-containers` patch. Plugins are encouraged to implement static asset serving with Whitenoise as well.
- [Bugfix] Fix dependency on MySQL service when MySQL is not activated.
- [Improvement] Improve openedx Docker image build time and size with the multi-stage build.
- 💥[Feature] Get rid of outdated sysadmin dashboard in LMS at /sysadmin.
## v10.1.0 (2020-07-23)
@ -445,7 +445,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v10.0.10 (2020-07-01)
- [Bugfix] Fix pycontracts installation error when building openedx Docker image.
- [Bugfix] Fix access to dicussion forum in development mode.
- [Bugfix] Fix access to the discussion forum in development mode.
## v10.0.9 (2020-07-01)
@ -479,7 +479,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v10.0.2 (2020-06-17)
- [Bugfix] Fix crash when viewing problem in LMS.
- [Bugfix] Fix crash when viewing the problem in LMS.
- [Bugfix] Fix missing webpack-stats.json in openedx Docker image.
## v10.0.1 (2020-06-15)
@ -489,19 +489,19 @@ Note: Breaking changes between versions are indicated by "💥".
## v10.0.0 (2020-06-15)
- 💥[Improvement] Upgrade to Juniper 🍾.
- [Bugfix] Fix nginx resolver address to address container restarts.
- [Feature] Add `--limit=myplugin` option to `init` commands to limit execution of initialisation to certain services and plugins.
- [Bugfix] Fix Nginx resolver address to address container restarts.
- [Feature] Add `--limit=myplugin` option to `init` commands to limit the execution of initialisation to certain services and plugins.
## v3.12.6 (2020-06-01)
- [Improvement] Add `dig`, `ping` utilities to openedx-dev Docker image.
- [Bugfix] Resolve "Can't connect to MySQL server" on init.
- [Improvement] Make it possible to customize the MySQL root username, for connecting to external MySQL databases.
- [Improvement] Make it possible to customise the MySQL root username, for connecting to external MySQL databases.
## v3.12.5 (2020-05-20)
- [Improvement] Upgrade Android app to v2.21.1 and enable many features, such as downloading videos to SD card. Thanks for the help @ejklock!.
- [Bugfix] Fix Android app crash when accessing course.
- [Bugfix] Fix Android app crash when accessing the course.
## v3.12.4 (2020-05-18)
@ -524,7 +524,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v3.12.0 (2020-04-26)
- 💥[Improvement] Do not deploy an ingress or SSL/TLS certificate issuer ressource by default in Kubernetes.
- 💥[Improvement] Do not deploy an ingress or SSL/TLS certificate issuer resource by default in Kubernetes.
- [Improvement] Fix tls certificate generation in k8s.
- 💥[Improvement] Radically change the way jobs are run: we no longer "exec", but instead run a dedicated container.
- 💥[Improvement] Upgrade k8s certificate issuer to cert-manager.io/v1alpha2.
@ -551,7 +551,7 @@ Note: Breaking changes between versions are indicated by "💥".
## v3.11.8 (2020-04-06)
- [Feature] Add `encrypt` template filter to conveniently add htpasswd-based authentication to nginx.
- [Feature] Add `encrypt` template filter to conveniently add htpasswd-based authentication to Nginx.
- [Bugfix] Fix "missing tty" during init in cron jobs.
## v3.11.7 (2020-04-01)
@ -563,20 +563,20 @@ Note: Breaking changes between versions are indicated by "💥".
- [Bugfix] Fix "Unable to resolve dependency" error during forum initialisation.
- [Feature] Add `settheme` command to easily assign a theme to a domain name.
- [Improvement] Modify nginx access logs to include request scheme and server name (plugin developers should use the "tutor" log format).
- [Improvement] Modify Nginx access logs to include request scheme and server name (plugin developers should use the "tutor" log format).
- [Bugfix] Fix DNS resolution of restarted service.
- [Feature] Restart multiple services with `local restart`.
- [Feature] Make it possible to easily reload openedx gunicorn process with `tutor local exec lms reload-gunicorn`.
- [Feature] Make it possible to easily reload the openedx gunicorn process with `tutor local exec lms reload-gunicorn`.
- [Improvement] Rename lms/cms_worker to lms/cms-worker in local deployment.
- [Improvement] Add the management plugin to the rabbitmq container.
- [Improvement] Make it possible to run an Elasticsearch service on https.
- [Improvement] Add the management plugin to the RabbitMQ container.
- [Improvement] Make it possible to run an Elasticsearch service on HTTPS.
## v3.11.5 (2020-02-27)
- [Improvement] Switch edx-platform from open-release/ironwood.2 tag to the open-release/ironwood.master branch.
- [Security] Upgrade django to 1.11.28.
- [Improvement] Make it possible to configure the elasticsearch heap size.
- [Bugfix] Fix broken elasticsearch environment variables.
- [Improvement] Make it possible to configure the Elasticsearch heap size.
- [Bugfix] Fix broken Elasticsearch environment variables.
- [Improvement] Restore more recent Android app version (#289).
## v3.11.4 (2020-02-16)
@ -589,7 +589,7 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.11.2 (2020-01-17)
- [Bugfix] Make sure `docker-compose.override.yml` are loaded in dev and local contexts.
- [Bugfix] Make sure `docker-compose.override.yml` is loaded in dev and local contexts.
## 3.11.1 (2020-01-16)
@ -606,7 +606,7 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.10.0 (2020-01-10)
- [Bugfix] Fix oauth authentication in dev mode.
- [Bugfix] Fix OAuth authentication in dev mode.
- [Improvement] Upgrade to the 3.7 docker-compose syntax.
- [Improvement] The `dev runserver` command can now be run for just any service.
- 💥[Feature] `dev run/exec` commands now support generic options which are passed to docker-compose. Consequently, defining the `TUTOR_EDX_PLATFORM_PATH` environment variable no longer works. Instead, users are encouraged to explicitly pass the `-v` option, define a command alias or create a `docker-compose.override.yml` file.
@ -631,14 +631,14 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.8.0 (2019-11-22)
- [Improvement] Add `k8s-deployments-nginx-volume-mounts` patch.
- [Bugfix] Fix running forum locally when both elasticsearch and mongodb are not activated (#266).
- [Bugfix] Fix MongoDb url in forum when running separate service (#267).
- [Bugfix] Fix running forum locally when both Elasticsearch and MongoDB are not activated (#266).
- [Bugfix] Fix MongoDB URL in the forum when running a separate service (#267).
- 💥[Improvement] Better `dev` commands, with dedicated development docker image. One of the consequences is that the `dev watchthemes` command is replaced by `dev run lms watchthemes`.
- [Improvement] `images` commands now accept multiple `image` arguments.
## 3.7.4 (2019-10-19)
- [Bugfix] Fix missing requirements file in pypi package (#261).
- [Bugfix] Fix missing requirements file in PyPI package (#261).
- [Improvement] Add missing cms/lms production/development setting patches.
- [Improvement] Allow SigV4 authentication for video upload to S3.
- [Bugfix] Fix cms development settings.
@ -674,7 +674,7 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.6.2 (2019-08-07)
- [Bugfix] Fix missing templates in bundled plugins.
- [Bugfix] Enable html certificate view.
- [Bugfix] Enable HTML certificate view.
## 3.6.1 (2019-07-27)
@ -683,7 +683,7 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.6.0 (2019-07-11)
- [Feature] Modify ``createuser`` commands to define a password from the command line.
- [Improvement] Better yaml value parsing from command line.
- [Improvement] Better YAML value parsing from the command line.
- [Feature] Add `dev exec` command.
- [Bugfix] Fix incorrect notes settings definition.
- [Improvement] Make it possible to start/stop/reboot a selection of services.
@ -719,8 +719,8 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.4.1 (2019-06-23)
- [Bugfix] Fix install from pypi.
- [Improvement] Get rid of kubernetes python package dependency.
- [Bugfix] Fix install from PyPI.
- [Improvement] Get rid of Kubernetes python package dependency.
## 3.4.0 (2019-06-17)
@ -728,7 +728,7 @@ Note: Breaking changes between versions are indicated by "💥".
- [Feature] Kubernetes support out of beta.
- [Improvement] Switch to pinned image tags for easier upgrades.
- 💥[Improvement] Remove the `-y/--yes` option: `tutor config save` is now non-interactive by default. Use `-i/--interactive` to force interactive mode.
- 💥[Improvement] Replace the `databases` command by `init`.
- 💥[Improvement] Replace the `databases` command with `init`.
- [Improvement] Upgrade to ironwood.2.
- [Improvement] Add `-y/--yes` option to `local quickstart` for non-interactive quickstart.
- [Improvement] Persist LMS/CMS logs to disk by default (with collaboration from @silviot 💪).
@ -755,13 +755,13 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.3.6 (2019-04-27)
- [Bugfix] Fix KeyError on first quickstart.
- [Improvement] De-duplication of prod/dev settings. Thanks @silviot! 😺.
- [Bugfix] Fix KeyError on the first quickstart.
- [Improvement] De-duplication of prod/dev settings. Thanks, @silviot! 😺.
## 3.3.5 (2019-04-22)
- [Feature] Pluggable LMS/CMS/forum.
- [Improvement] Safer environment overwrite. Thanks @silviot! 👐.
- [Improvement] Safer environment overwrite. Thanks, @silviot! 👐.
- [Security] Fix Jinja2 vulnerability.
- [Improvement] Improve CLI cold start performance.
- [Improvement] Allow uppercase "Y" and "N" as answers to boolean questions.
@ -769,7 +769,7 @@ Note: Breaking changes between versions are indicated by "💥".
## 3.3.4 (2019-04-09)
- [Improvement] Rename `--silent` option to `-y/--yes`.
- [Bugfix] Fix (again) login from studio when https is activated (#193).
- [Bugfix] Fix (again) login from studio when HTTPS is activated (#193).
## 3.3.3 (2019-03-29)
@ -794,8 +794,8 @@ Note: Breaking changes between versions are indicated by "💥".
- [Feature] Multiple platforms on a single server \o/.
- [Feature] Easily configure web proxy on the host.
- [Bugfix] Fix `images pull all` command which failed on "all" image.
- [Improvement] Add configurable mongodb, SMTP and rabbitmq authentication.
- [Improvement] Harmonize mysql username/password configuration parameters.
- [Improvement] Add configurable MongoDB, SMTP and RabbitMQ authentication.
- [Improvement] Harmonize MySQL username/password configuration parameters.
- [Feature] Configurable and pluggable data storage backends (#114).
## 3.2.1 (2019-03-19)
@ -807,7 +807,7 @@ Note: Breaking changes between versions are indicated by "💥".
- [Improvement] `images pull` now also pulls vendor images.
- [Feature] Add convenient `config printvalue` command.
- [Feature] Customize docker registry.
- [Feature] Customise docker registry.
- [Feature] Load configuration parameters from the system environment.
- [Improvement] Automatic environment re-generation after re-configuration.
- [Improvement] Error and interrupt handling in UI and web UI.
@ -839,33 +839,33 @@ Note: Breaking changes between versions are indicated by "💥".
- [Minor] Minimum required `click` version is 7.0 (#171).
- [Bugfix] Fix `runserver` dev command (#172).
- [Minor] Fix non-https link to documentation in pypi.
- [Minor] Fix non-https link to documentation in PyPI.
- [Minor] Fix `createuser` documentation.
## 3.0.3 (2019-02-12)
- [Bugfix] Add missing template data to pypi package.
- [Bugfix] Add missing template data to the PyPI package.
- [Bugfix] Fix quickstart on Kubernetes (#164).
- [Improvement] Add datatases task to Kubernetes quickstart (#167).
- [Improvement] Add databases task to Kubernetes quickstart (#167).
## 3.0.2 (2019-02-12)
- [Bugfix] Fix import paths -- 🚀 thanks @silviot!.
- [Bugfix] Properly set docker project name in mysql logs -- 🦊 thanks again @silviot!.
- [Bugfix] Properly set docker project name in MySQL logs -- 🦊 thanks again @silviot!.
## 3.0.1 (2019-02-11)
- [Bugfix] fix mysql initialisation (#159, #160).
- [Bugfix] fix MySQL initialisation (#159, #160).
- [Improvement] Better handling of continuous integration.
- [Bugfix] fix `tutor --version` (#156).
- [Improvement] Absolute settings imports -- 📯 thanks @tonytan4ever!.
## 3.0.0 (2019-02-09)
- [Improvement] Complete rewrite of Tutor: switch from a make-based project to a single binary which runs all commands.
- [Improvement] Complete rewrite of Tutor: switch from a make-based project to a single binary that runs all commands.
- [Feature] An web user interface can be created with `tutor webui start`.
- [Bugfix] Add missing elasticsearch to Kubernetes deployment (#147).
- [Improvement] Upload `tutor-openedx` to pypi.
- [Bugfix] Add missing Elasticsearch to Kubernetes deployment (#147).
- [Improvement] Upload `tutor-openedx` to PyPI .
## Older changes
@ -886,10 +886,10 @@ Note: Breaking changes between versions are indicated by "💥".
- 2018-11-25 [Feature] Use local filesystem for open assessment file upload.
- 2018-11-23 [Improvement] Faster container bootstrapping without "chmod", as suggested by @silviot.
- 2018-11-20 [Bugfix] Fix cross-platform theme assets generation.
- 2018-11-17 [Improvement] Custom nginx port mapping. :crossed_swords: @frob @frohro.
- 2018-11-17 [Improvement] Custom Nginx port mapping. :crossed_swords: @frob @frohro.
- 2018-11-17 [Improvement] Add "make restart-openedx" command. :+1: @frob.
- 2018-11-13 [Improvement] Facilitate install of extra XBlocks. Thanks @frob!.
- 2018-10-30 [Bugfix] Fix rabbitmq restart policy.
- 2018-10-30 [Bugfix] Fix RabbitMQ restart policy.
- 2018-10-03 [Improvement/Bugfix] Fix and accelerate Android application build.
- 2018-10-02 [Improvement] Bump Open edX version to hawthorn.2.
- 2018-09-30 [Bugfix] Fix CMS celery worker, including export tasks.
@ -907,6 +907,6 @@ Note: Breaking changes between versions are indicated by "💥".
- 2018-09-02 [Bugfix] Get HTTPS to work for CMS. Thanks @flytreeleft!.
- 2018-08-28 [Bugfix] Fix certbot image updating.
- 2018-08-27 [Improvement] Add development requirements to openedx image.
- 2018-08-27 [Bugfix] Upgrade mongodb.
- 2018-08-27 [Bugfix] Upgrade MongoDB.
- 2018-08-19 [Improvement] Make Xqueue an optional feature.
- 2018-08-16 [Feature] Add HTTPS support.

2
README.rst
View File

@ -38,7 +38,7 @@ Tutor: the Docker-based Open edX distribution designed for peace of mind
:alt: Follow us on Youtube
:target: https://www.youtube.com/c/OverhangIO
**Tutor** is the official Docker-based `Open edX <https://openedx.org>`_ distribution, both for production and local development. The goal of Tutor is to make it easy to deploy, customize, upgrade and scale Open edX. Tutor is reliable, fast, extensible, and it is already used to deploy hundreds of Open edX platforms around the world.
**Tutor** is the official Docker-based `Open edX <https://openedx.org>`_ distribution, both for production and local development. The goal of Tutor is to make it easy to deploy, customise, upgrade and scale Open edX. Tutor is reliable, fast, extensible, and it is already used to deploy hundreds of Open edX platforms around the world.
Do you need professional assistance setting up or managing your Open edX platform? Overhang.IO provides online support as part of its `Long Term Support (LTS) offering <https://overhang.io/tutor/pricing>`__.

18
docs/configuration.rst
View File

@ -3,7 +3,7 @@
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 installation can be customized:
Tutor offers plenty of possibilities for platform customisation out of the box. There are two main ways in which the base Open edX installation can be customised:
a. Modifying the Tutor :ref:`configuration parameters <configuration>`.
b. Modifying the :ref:`Open edX docker image <customise>` that runs the Open edX platform.
@ -86,12 +86,12 @@ This defines the default version that will be pulled from all Open edX git repos
- ``OPENEDX_CMS_UWSGI_WORKERS`` (default: ``2``)
- ``OPENEDX_LMS_UWSGI_WORKERS`` (default: ``2``)
By default there are 2 `uwsgi worker processes <https://uwsgi-docs.readthedocs.io/en/latest/Options.html#processes>`__ to serve requests for the LMS and the CMS. However, each workers requires upwards of 500 Mb of RAM. You should reduce this value to 1 if your computer/server does not have enough memory.
By default, there are 2 `uwsgi worker processes <https://uwsgi-docs.readthedocs.io/en/latest/Options.html#processes>`__ to serve requests for the LMS and the CMS. However, each worker requires upwards of 500 Mb of RAM. You should reduce this value to 1 if your computer/server does not have enough memory.
- ``OPENEDX_CELERY_REDIS_DB`` (default: ``0``)
- ``OPENEDX_CACHE_REDIS_DB`` (default: ``1``)
These two configuration parameters define which redis database to use for Open edX cache and celery task.
These two configuration parameters define which Redis database to use for Open edX cache and celery task.
.. _openedx_extra_pip_requirements:
@ -119,7 +119,7 @@ MySQL
- ``MYSQL_ROOT_USERNAME`` (default: ``"root"``)
- ``MYSQL_ROOT_PASSWORD`` (default: randomly generated) Note that you are responsible for creating the root user if you are using a managed database.
By default, a running Open edX platform deployed with Tutor includes all necessary 3rd-party services, such as MySQL, MongoDb, etc. But it's also possible to store data on a separate database, such as `Amazon RDS <https://aws.amazon.com/rds/>`_. For instance, to store data on an external MySQL database, set the following configuration::
By default, a running Open edX platform deployed with Tutor includes all necessary 3rd-party services, such as MySQL, MongoDb, etc. But it's also possible to store data on a separate database, such as `Amazon RDS <https://aws.amazon.com/rds/>`_. For instance, to store data on an external MySQL database set the following configuration::
RUN_MYSQL: false
MYSQL_HOST: yourhost
@ -137,7 +137,7 @@ Elasticsearch
- ``ELASTICSEARCH_PORT`` (default: ``9200``)
- ``ELASTICSEARCH_HEAP_SIZE`` (default: ``"1g"``)
Mongodb
MongoDB
*******
- ``RUN_MONGODB`` (default: ``true``)
@ -238,7 +238,7 @@ Would you like to include custom xblocks, or extra requirements to your Open edX
- "git+https://github.com/open-craft/xblock-poll.git"
.. warning::
Specifying extra requirements through ``config.yml`` overwrites :ref:`the default extra requirements<openedx_extra_pip_requirements>`. You might need to add them to the list, if your configuration depends on them.
Specifying extra requirements through ``config.yml`` overwrites :ref:`the default extra requirements<openedx_extra_pip_requirements>`. You might need to add them to the list if your configuration depends on them.
- or add the dependency to ``private.txt``::
@ -254,7 +254,7 @@ Then, the ``openedx`` docker image must be rebuilt::
Installing extra requirements from private repositories
*******************************************************
When installing extra xblock or requirements from private repositories, ``private.txt`` file should be used, because it allows to install dependencies without adding git credentials to the Docker image. By adding your git credentials to the Docker image, you're risking leaking your git credentials, if you were to publish (intentionally or unintentionally) the Docker image in a public place.
When installing extra xblock or requirements from private repositories, ``private.txt`` file should be used, because it allows installing dependencies without adding git credentials to the Docker image. By adding your git credentials to the Docker image, you're risking leaking your git credentials, if you were to publish (intentionally or unintentionally) the Docker image in a public place.
To install xblocks from a private repository that requires authentication, you must first clone the repository inside the ``openedx/requirements`` folder on the host::
@ -290,7 +290,7 @@ If you don't create your fork from this tag, you *will* have important compatibi
Adding custom translations
~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are not running Open edX in English, chances are that some strings will not be properly translated. In most cases, this is because not enough contributors have helped translate Open edX in your language. It happens! With Tutor, available translated languages include those that come bundled with `edx-platform <https://github.com/openedx/edx-platform/tree/open-release/maple.master/conf/locale>`__ as well as those from `openedx-i18n <https://github.com/openedx/openedx-i18n/tree/master/edx-platform/locale>`__.
If you are not running Open edX in English, chances are that some strings will not be properly translated. In most cases, this is because not enough contributors have helped translate Open edX into your language. It happens! With Tutor, available translated languages include those that come bundled with `edx-platform <https://github.com/openedx/edx-platform/tree/open-release/maple.master/conf/locale>`__ as well as those from `openedx-i18n <https://github.com/openedx/openedx-i18n/tree/master/edx-platform/locale>`__.
Tutor offers a relatively simple mechanism to add custom translations to the openedx Docker image. You should create a folder that corresponds to your language code in the "build/openedx/locale" folder of the Tutor environment. This folder should contain a "LC_MESSAGES" folder. For instance::
@ -347,7 +347,7 @@ Then you will have to re-build the openedx Docker image::
tutor images build openedx
Beware that this will take a long time! Unfortunately it's difficult to accelerate this process, as translation files need to be compiled prior to collecting the assets. In development it's possible to accelerate the iteration loop -- but that exercise is left to the reader.
Beware that this will take a long time! Unfortunately, it's difficult to accelerate this process, as translation files need to be compiled before collecting the assets. In development it's possible to accelerate the iteration loop -- but that exercise is left to the reader.
Running a different ``openedx`` Docker image

12
docs/dev.rst
View File

@ -9,9 +9,9 @@ The following commands assume you have previously launched a :ref:`local <local>
tutor local quickstart
In order to run the platform in development mode, you **must** answer no ("n") to the question "Are you configuring a production platform".
To run the platform in development mode, you **must** answer no ("n") to the question "Are you configuring a production platform".
Note that the local.overhang.io `domain <https://dnschecker.org/#A/local.overhang.io>`__ and its `subdomains <https://dnschecker.org/#CNAME/studio.local.overhang.io>`__ all point to 127.0.0.1. This is just a domain name that was setup to conveniently access a locally running Open edX platform.
Note that the local.overhang.io `domain <https://dnschecker.org/#A/local.overhang.io>`__ and its `subdomains <https://dnschecker.org/#CNAME/studio.local.overhang.io>`__ all point to 127.0.0.1. This is just a domain name that was set up to conveniently access a locally running Open edX platform.
Once the local platform has been configured, you should stop it so that it does not interfere with the development environment::
@ -23,7 +23,7 @@ Finally, you should build the ``openedx-dev`` docker image::
This ``openedx-dev`` development image differs from the ``openedx`` production image:
- The user that runs inside the container has the same UID as the user on the host, in order to avoid permission problems inside mounted volumes (and in particular in the edx-platform repository).
- The user that runs inside the container has the same UID as the user on the host, to avoid permission problems inside mounted volumes (and in particular in the edx-platform repository).
- Additional python and system requirements are installed for convenient debugging: `ipython <https://ipython.org/>`__, `ipdb <https://pypi.org/project/ipdb/>`__, vim, telnet.
- The edx-platform `development requirements <https://github.com/openedx/edx-platform/blob/open-release/maple.master/requirements/edx/development.in>`__ are installed.
@ -115,7 +115,7 @@ You are then free to bind-mount any directory to any container. For instance, to
This override file will be loaded when running any ``tutor dev ..`` command. The edx-platform repo mounted at the specified path will be automatically mounted inside all LMS and CMS containers. With this file, you should no longer specify the ``-v/--volume`` option from the command line with the ``run`` or ``runserver`` commands.
.. note::
The ``tutor local`` commands loads the ``docker-compose.override.yml`` file from the ``$(tutor config printroot)/env/local/docker-compose.override.yml`` directory.
The ``tutor local`` commands load the ``docker-compose.override.yml`` file from the ``$(tutor config printroot)/env/local/docker-compose.override.yml`` directory.
Common tasks
------------
@ -160,7 +160,7 @@ To debug a local edx-platform repository, add a ``import ipdb; ipdb.set_trace()`
XBlock and edx-platform plugin development
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some cases you will have to develop features for packages that are pip-installed next to edx-platform. This is quite easy with Tutor. Just add your packages to the ``$(tutor config printroot)/env/build/openedx/requirements/private.txt`` file. To avoid re-building the openedx Docker image at every change, you should add your package in editable mode. For instance::
In some cases, you will have to develop features for packages that are pip-installed next to the edx-platform. This is quite easy with Tutor. Just add your packages to the ``$(tutor config printroot)/env/build/openedx/requirements/private.txt`` file. To avoid re-building the openedx Docker image at every change, you should add your package in editable mode. For instance::
echo "-e ./mypackage" >> "$(tutor config printroot)/env/build/openedx/requirements/private.txt"
@ -183,7 +183,7 @@ Loading custom edx-platform settings
By default, tutor settings files are mounted inside the docker images at ``/openedx/edx-platform/lms/envs/tutor/`` and ``/openedx/edx-platform/cms/envs/tutor/``. In the various ``dev`` commands, the default ``edx-platform`` settings module is set to ``tutor.development`` and you don't have to do anything to set up these settings.
If, for some reason, you want to use different settings, you will need to define the ``TUTOR_EDX_PLATFORM_SETTINGS`` environment variable.
If for some reason, you want to use different settings, you will need to define the ``TUTOR_EDX_PLATFORM_SETTINGS`` environment variable.
For instance, let's assume you have created the ``/path/to/edx-platform/lms/envs/mysettings.py`` and ``/path/to/edx-platform/cms/envs/mysettings.py`` modules. These settings should be pretty similar to the following files::

14
docs/faq.rst
View File

@ -20,15 +20,15 @@ To make it possible to deploy, administer and upgrade Open edX anywhere, easily.
What's the difference with the official "native" installation?
--------------------------------------------------------------
The `native installation <https://openedx.atlassian.net/wiki/spaces/OpenOPS/pages/146440579/Native+Open+edX+Ubuntu+16.04+64+bit+Installation>`_ maintained by edX relies on `Ansible scripts <https://github.com/openedx/configuration/>`_ to deploy Open edX on one or multiple servers. These scripts suffer from a couple issues that Tutor tries to address:
The `native installation <https://openedx.atlassian.net/wiki/spaces/OpenOPS/pages/146440579/Native+Open+edX+Ubuntu+16.04+64+bit+Installation>`_ maintained by edX relies on `Ansible scripts <https://github.com/openedx/configuration/>`_ to deploy Open edX on one or multiple servers. These scripts suffer from a couple of issues that Tutor tries to address:
1. Complexity: the scripts contain close to 35k lines of code spread over 780 files. They are really hard to understand, debug, and modify, and they are extremly slow. As a consequence, Open edX is often wrongly perceived as a project that is overly complex to manage. In contrast, Tutor generates mostly ``Dockerfile`` and ``docker-compose.yml`` files that make it easy to understand what is going on. Also, the whole installation should take about 10 minutes.
1. Complexity: the scripts contain close to 35k lines of code spread over 780 files. They are really hard to understand, debug, and modify, and they are extremely slow. As a consequence, Open edX is often wrongly perceived as a project that is overly complex to manage. In contrast, Tutor generates mostly ``Dockerfile`` and ``docker-compose.yml`` files that make it easy to understand what is going on. Also, the whole installation should take about 10 minutes.
2. Isolation from the OS: Tutor barely needs to touch your server because the entire platform is packaged inside Docker containers. You are thus free to run other services on your server without fear of indirectly crashing your Open edX platform.
3. Compatibility: Open edX is only compatible with Ubuntu 16.04, but that shouldn't mean you are forced to run this specific OS. With Tutor, you can deploy Open edX on just any server you like: Ubuntu 18.04, Red Hat, Debian... All docker-compatible platforms are supported.
4. Security: because you are no longer bound to a single OS, with Tutor you are now free to install security-related upgrades as soon as they become available.
5. Portability: Tutor makes it easy to move your platform from one server to another. Just zip-compress your Tutor project root, send it to another server and you're done.
There are also many features that are not included in the native installation, such as a `web user interface <https://github.com/overhangio/tutor-webui>`__ for remotely installing the platform, :ref:`Kubernetes deployment <k8s>`, additional languages, etc. You'll discover these differences as you explore Tutor :)
Many features that are not included in the native installation, such as a `web user interface <https://github.com/overhangio/tutor-webui>`__ for remotely installing the platform, :ref:`Kubernetes deployment <k8s>`, additional languages, etc. You'll discover these differences as you explore Tutor :)
What's the difference with the official devstack?
-------------------------------------------------
@ -38,21 +38,21 @@ The `devstack <https://github.com/openedx/devstack>`_ is meant for development o
Is Tutor officially supported by edX?
-------------------------------------
Yes: as of the Open edX Maple release (December 9th 2021), Tutor is the only officially supported installation methods for Open edX: see the `official installation instructions <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/open-release-maple.master/installation/index.html>`__.
Yes: as of the Open edX Maple release (December 9th 2021), Tutor is the only officially supported installation method for Open edX: see the `official installation instructions <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/open-release-maple.master/installation/index.html>`__.
What features are missing from Tutor?
-------------------------------------
Tutor tries very hard to support all major Open edX features, notably in the form of :ref:`plugins <existing_plugins>`. If you are interested in sponsoring the development of a new plugin, please `get in touch <mailto:worktogether@overhang.io>`__!
It should be noted that the `Insights <https://github.com/openedx/edx-analytics-pipeline>`__ stack is currently unsupported, because of its complexity, lack of support and extensibility. To replace it, Overhang.IO developed `Cairn <https://overhang.io/tutor/plugin/cairn>`__ the next-generation analytics solution for Open edX, part of the `Tutor Wizard Edition <https://overhang.io/tutor/wizardedition>`__. You should check it out 😉
It should be noted that the `Insights <https://github.com/openedx/edx-analytics-pipeline>`__ stack is currently unsupported, because of its complexity, lack of support, and extensibility. To replace it, Overhang.IO developed `Cairn <https://overhang.io/tutor/plugin/cairn>`__ the next-generation analytics solution for Open edX, part of the `Tutor Wizard Edition <https://overhang.io/tutor/wizardedition>`__. You should check it out 😉
Are there people already running this in production?
----------------------------------------------------
Yes: system administrators all around the world use Tutor to run their Open edX platforms, from single-class school teachers to renowned universities, Open edX SaaS providers and nation-wide learning platforms.
Yes: system administrators all around the world use Tutor to run their Open edX platforms, from single-class school teachers to renowned universities, Open edX SaaS providers, and nation-wide learning platforms.
Why should I trust software written by some random guy on the Internet?
-----------------------------------------------------------------------
You shouldn't :) Tutor is actively maintained by `Overhang.IO <https://overhang.io>`_, a France-based company founded by `Régis Behmo <https://github.com/regisb/>`_. Régis has been working on Tutor since early 2018; he has been a contributor of the Open edX project since 2015. In particular, he has worked for 2 years at `FUN-MOOC <https://www.fun-mooc.fr/>`_, one of the top 5 largest Open edX platforms in the world. In addition, the Tutor project is a community-led project with many contributions from its :ref:`project maintainers <maintainers>`.
You shouldn't :) Tutor is actively maintained by `Overhang.IO <https://overhang.io>`_, a France-based company founded by `Régis Behmo <https://github.com/regisb/>`_. Régis has been working on Tutor since early 2018; he has been a contributor to the Open edX project since 2015. In particular, he has worked for 2 years at `FUN-MOOC <https://www.fun-mooc.fr/>`_, one of the top 5 largest Open edX platforms in the world. In addition, the Tutor project is a community-led project with many contributions from its :ref:`project maintainers <maintainers>`.

12
docs/install.rst
View File

@ -66,7 +66,7 @@ To inspect the Tutor source code, install Tutor from `the Github repository <htt
Configuring DNS records
-----------------------
When running a server in production, it is necessary to define `DNS records <https://en.wikipedia.org/wiki/Domain_Name_System#Resource_records>`__ which will make it possible to access your Open edX platform by name in your browser. The precise procedure to create DNS records vary from one provider to the next and is beyond the scope of these docs. You should create a record of type A with a name equal to your LMS hostname (given by ``tutor config printvalue LMS_HOST``) and a value that indicates the IP address of your server. Applications other than the LMS, such as the studio, ecommerce, etc. typically reside in subdomains of the LMS. Thus, you should also create a CNAME record to point all subdomains of the LMS to the LMS_HOST.
When running a server in production, it is necessary to define `DNS records <https://en.wikipedia.org/wiki/Domain_Name_System#Resource_records>`__ which will make it possible to access your Open edX platform by name in your browser. The precise procedure to create DNS records varies from one provider to the next and is beyond the scope of these docs. You should create a record of type A with a name equal to your LMS hostname (given by ``tutor config printvalue LMS_HOST``) and a value that indicates the IP address of your server. Applications other than the LMS, such as the studio, ecommerce, etc. typically reside in subdomains of the LMS. Thus, you should also create a CNAME record to point all subdomains of the LMS to the LMS_HOST.
For instance, the demo Open edX server that runs at https://demo.openedx.overhang.io has the following DNS records::
@ -99,7 +99,7 @@ Then run the ``quickstart`` command again. Depending on your deployment target,
Upgrading with custom Docker images
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you run :ref:`customised <configuration_customisation>` Docker images, you need to rebuild them prior to running ``quickstart``::
If you run :ref:`customised <configuration_customisation>` Docker images, you need to rebuild them before running ``quickstart``::
tutor config save
tutor images build all # specify here the images that you need to build
@ -108,7 +108,7 @@ If you run :ref:`customised <configuration_customisation>` Docker images, you ne
Upgrading to a new Open edX release
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Major Open edX releases are published twice a year, in June and December, by the Open edX `Build/Test/Release working group <https://discuss.openedx.org/c/working-groups/build-test-release/30>`__. When a new Open edX release comes out, Tutor gets a major version bump (see :ref:`versioning`). Such an upgrade typically includes multiple breaking changes. Any upgrade is final, because downgrading is not supported. Thus, when upgrading your platform from one major version to the next, it is strongly recommended to do the following:
Major Open edX releases are published twice a year, in June and December, by the Open edX `Build/Test/Release working group <https://discuss.openedx.org/c/working-groups/build-test-release/30>`__. When a new Open edX release comes out, Tutor gets a major version bump (see :ref:`versioning`). Such an upgrade typically includes multiple breaking changes. Any upgrade is final because downgrading is not supported. Thus, when upgrading your platform from one major version to the next, it is strongly recommended to do the following:
1. Read the changes listed in the `CHANGELOG.md <https://github.com/overhangio/tutor/blob/master/CHANGELOG.md>`__ file. Breaking changes are identified by a "💥".
2. Perform a backup. On a local installation, this is typically done with::
@ -120,7 +120,7 @@ Major Open edX releases are published twice a year, in June and December, by the
4. Test the new release in a sandboxed environment.
5. If you are running edx-platform, or some other repository from a custom branch, then you should rebase (and test) your changes on top of the latest release tag (see :ref:`edx_platform_fork`).
The process for upgrading from one major release to the next works similarly to any other upgrade, with the ``quickstart`` command (see above). The single difference is that if the ``quickstart`` command detects that your tutor environment was generated with an older release, it will perform a few release-specific upgrade steps. These extra upgrade steps will be performed just once. But they will be ignored if you updated your local environment (for instance: with ``tutor config save``) prior to running ``quickstart``. This situation typically occurs if you need to re-build some Docker images (see above). In such a case, you should make use of the ``upgrade`` command. For instance, to upgrade a local installation from Lilac to Maple and rebuild some Docker images, run::
The process for upgrading from one major release to the next works similarly to any other upgrade, with the ``quickstart`` command (see above). The single difference is that if the ``quickstart`` command detects that your tutor environment was generated with an older release, it will perform a few release-specific upgrade steps. These extra upgrade steps will be performed just once. But they will be ignored if you updated your local environment (for instance: with ``tutor config save``) before running ``quickstart``. This situation typically occurs if you need to re-build some Docker images (see above). In such a case, you should make use of the ``upgrade`` command. For instance, to upgrade a local installation from Lilac to Maple and rebuild some Docker images, run::
tutor config save
tutor images build all # list the images that should be rebuilt here
@ -147,14 +147,14 @@ After opening a new shell, you can test auto-completion by typing::
Uninstallation
--------------
It is fairly easy to completely uninstall Tutor and to delete the Open edX platforms that is running locally.
It is fairly easy to completely uninstall Tutor and to delete the Open edX platforms that are running locally.
First of all, stop any locally-running platform and remove all Tutor containers::
tutor local dc down --remove-orphans
tutor dev dc down --remove-orphans
Then, delete all data associated to your Open edX platform::
Then, delete all data associated with your Open edX platform::
# WARNING: this step is irreversible
sudo rm -rf "$(tutor config printroot)"

14
docs/intro.rst
View File

@ -6,7 +6,7 @@ Concepts
What is Open edX?
-----------------
`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. Open edX comes with an LMS (Learning Management System) where students access course contents, a CMS (Content Management System) that course staff uses to design courses, and a few other components to provide more services to students, course staff and platform administrators.
`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. Open edX comes with an LMS (Learning Management System) where students access course contents, a CMS (Content Management System) that course staff uses to design courses, and a few other components to provide more services to students, course staff, and platform administrators.
Should I use Open edX?
----------------------
@ -18,19 +18,19 @@ Open edX competitors include `Moodle <https://moodle.org/>`__, `Instructure's Ca
* Multiple extension points for comprehensive customization
* Modern, intuitive user interface to keep students engaged
Open edX is a safe bet: it is backed by edX.org, a US-based non-profit that is committed to open source and which runs Open edX to service its millions of learners. With Open edX you can be sure that the features you need will be available. If it's good enough for Harvard, the MIT or the French government, then it will probably also work for you.
Open edX is a safe bet: it is backed by edX.org, a US-based non-profit that is committed to open source and which runs Open edX to service its millions of learners. With Open edX you can be sure that the features you need will be available. If it's good enough for Harvard, the MIT, or the French government, then it will probably also work for you.
Should I self-host Open edX or rely on a hosting provider?
----------------------------------------------------------
Third-party Open edX providers can provide you with custom, closed-source features that they developed internally. However, their pricing is usually per-seat: that makes it difficult to predict how much running Open edX will actually cost you if you don't know in advance how many students will connect to your platform. And once you start scaling up and adding many students, running the platform will become very expensive.
On the other hand, running Open edX on your own servers will help you keep your costs under control. Because you own your servers and data, you will always be able to migrate your platform, either to a different cloud provider or an Open edX service provider. This is the true power of open source.
On the other hand, running Open edX on your own servers will help you keep your costs under control. Because you own your servers and data, you will always be able to migrate your platform, either to a different cloud provider or an Open edX service provider. This is the true power of the open source.
Should I use Tutor?
-------------------
Running software on premises is cheaper only if your management costs don't go through the roof. You do not want to hire a full-time devops team just for managing your online learning platform. This is why we created Tutor: to make it easy to run a state-of-the-art online learning platform without breaking the bank. Historically, it's always been difficult to install Open edX with the native installation scripts. For instance, there are no official instructions for upgrading an existing Open edX platform: the `recommended approach <https://docs.bitnami.com/azure/apps/edx/administration/upgrade/>`__ is to backup all data, trash the server and create a new one. As a consequence, people tend not to upgrade their platform and keep running on deprecated releases. Tutor makes it possible even to non-technical users to launch, manage and upgrade Open edX at any scale. Should you choose at some point that Tutor is not the right solution for you, you always have an escape route: because Tutor is open source software, you can easily dump your data and switch to a different installation method. But we are confident you will not do that 😉
Running software on-premises is cheaper only if your management costs don't go through the roof. You do not want to hire a full-time devops team just for managing your online learning platform. This is why we created Tutor: to make it easy to run a state-of-the-art online learning platform without breaking the bank. Historically, it's always been difficult to install Open edX with native installation scripts. For instance, there are no official instructions for upgrading an existing Open edX platform: the `recommended approach <https://docs.bitnami.com/azure/apps/edx/administration/upgrade/>`__ is to backup all data, trash the server, and create a new one. As a consequence, people tend not to upgrade their platform and keep running on deprecated releases. Tutor makes it possible even for non-technical users to launch, manage and upgrade Open edX at any scale. Should you choose at some point that Tutor is not the right solution for you, you always have an escape route: because Tutor is open source software, you can easily dump your data and switch to a different installation method. But we are confident you will not do that 😉
To learn more about Tutor, watch this 7-minute lightning talk that was made at the 2019 Open edX conference in San Diego, CA (with `slides <https://regisb.github.io/openedx2019/>`_):
@ -44,7 +44,7 @@ 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>`_.
3. Providing user-friendly, reliable commands for common administration tasks, including upgrades and monitoring.
4. Using a simple :ref:`plugin system <plugins>` that makes it easy to extend and customize Open edX.
4. Using a simple :ref:`plugin system <plugins>` that makes it easy to extend and customise Open edX.
.. image:: https://overhang.io/static/img/openedx-plus-docker-is-tutor.png
:alt: Open edX + Docker = Tutor
@ -76,7 +76,7 @@ How does Tutor work?
Tutor is a piece of software that takes care of exactly three things:
1. Project configuration: user-specific settings (such as secrets) are stored in a single ``config.yml`` file.
2. Template rendering: all the files that are necessary to run your platform are generated from a set of templates and the user-specific settings.
2. Template rendering: all the files that are necessary to run your platform are generated from a set of templates and user-specific settings.
3. Command-line interface (CLI): frequently-used administration commands are gathered in a convenient, unified CLI.
You can experiment with Tutor very quickly: start by `installing <install>`_ Tutor. Then run::
@ -99,7 +99,7 @@ You can now take advantage of the Tutor-powered CLI (item #3) to bootstrap your
tutor local quickstart
Under the hood, Tutor simply runs ``docker-compose`` and ``docker`` commands to launch your platform. These commands are printed in the standard output, such that you are free to replicate the same behaviour by simply copy/pasting the same commands.
Under the hood, Tutor simply runs ``docker-compose`` and ``docker`` commands to launch your platform. These commands are printed in the standard output, such that you are free to replicate the same behaviour by simply copying/pasting the same commands.
I'm ready, where do I start?
----------------------------

18
docs/k8s.rst
View File

@ -22,7 +22,7 @@ Memory
In the following, we assume you have access to a working Kubernetes cluster. ``kubectl`` should use your cluster configuration by default. To launch a cluster locally, you may try out Minikube. Just follow the `official installation instructions <https://kubernetes.io/docs/setup/minikube/>`__.
The Kubernetes cluster should have at least 4Gb of RAM on each node. When running Minikube, the virtual machine should have that much allocated memory. See below for an example with VirtualBox:
The Kubernetes cluster should have at least 4Gb of RAM on each node. When running Minikube, the virtual machine should have that much-allocated memory. See below for an example with VirtualBox:
.. image:: img/virtualbox-minikube-system.png
:alt: Virtualbox memory settings for Minikube
@ -34,7 +34,7 @@ By default, Tutor deploys a `LoadBalancer <https://kubernetes.io/docs/concepts/s
tutor k8s start caddy
Get the external IP of this services::
Get the external IP of this service::
kubectl --namespace openedx get services/caddy
@ -42,14 +42,14 @@ Use this external IP to configure your DNS records. Once the DNS records are con
tutor k8s logs -f caddy
If, for some reason, you would like to deploy your own load balancer, you should set ``ENABLE_WEB_PROXY=false`` just like in the :ref:`local installation <web_proxy>`. Then, point your load balancer at the "caddy" service, which will be a `ClusterIP <https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types>`__.
If for some reason, you would like to deploy your own load balancer, you should set ``ENABLE_WEB_PROXY=false`` just like in the :ref:`local installation <web_proxy>`. Then, point your load balancer at the "caddy" service, which will be a `ClusterIP <https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types>`__.
S3-like object storage with `MinIO <https://www.minio.io/>`__
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Like many web applications, Open edX needs to persist data. In particular, it needs to persist files uploaded by students and course designers. In the local installation, these files are persisted to disk, on the host filesystem. But on Kubernetes, it is difficult to share a single filesystem between different pods. This would require persistent volume claims with `ReadWriteMany` access mode, and these are difficult to setup.
Like many web applications, Open edX needs to persist data. In particular, it needs to persist files uploaded by students and course designers. In the local installation, these files are persisted to disk, on the host filesystem. But on Kubernetes, it is difficult to share a single filesystem between different pods. This would require persistent volume claims with `ReadWriteMany` access mode, and these are difficult to set up.
Luckily, there is another solution: at `edx.org <edx.org>`_, uploaded files are persisted on AWS S3: Open edX is compatible out-of-the-box with the S3 API for storing user-generated files. The problem with S3 is that it introduces a dependency on AWS. To solve this problem, Tutor comes with a plugin that emulates the S3 API but stores files on premises. This is achieved thanks to `MinIO <https://www.minio.io/>`__. If you want to deploy a production platform to Kubernetes, you will most certainly need to enable the ``minio`` plugin::
Luckily, there is another solution: at `edx.org <edx.org>`_, uploaded files are persisted on AWS S3: Open edX is compatible out-of-the-box with the S3 API for storing user-generated files. The problem with S3 is that it introduces a dependency on AWS. To solve this problem, Tutor comes with a plugin that emulates the S3 API but stores files on-premises. This is achieved thanks to `MinIO <https://www.minio.io/>`__. If you want to deploy a production platform to Kubernetes, you will most certainly need to enable the ``minio`` plugin::
tutor plugins enable minio
@ -58,7 +58,7 @@ The "minio.LMS_HOST" domain name will have to point to your Kubernetes cluster.
Kubernetes dashboard
~~~~~~~~~~~~~~~~~~~~
This is not a requirement per se, but it's very convenient to have a visual interface of the Kubernetes cluster. We suggest the official `Kubernetes dashboard <https://github.com/kubernetes/dashboard/>`__. Depending on your Kubernetes provider, you may need to install a dashboard yourself. There are generic instructions on the `project's README <https://github.com/kubernetes/dashboard/blob/master/README.md>`__. AWS provides `specific instructions <https://docs.aws.amazon.com/eks/latest/userguide/dashboard-tutorial.html>`__.
This is not a requirement per se, but it's very convenient to have a visual interface of the Kubernetes cluster. We suggest the official `Kubernetes dashboard <https://github.com/kubernetes/dashboard/>`__. Depending on your Kubernetes provider, you may need to install a dashboard yourself. There are general instructions on the `project's README <https://github.com/kubernetes/dashboard/blob/master/README.md>`__. AWS provides `specific instructions <https://docs.aws.amazon.com/eks/latest/userguide/dashboard-tutorial.html>`__.
On Minikube, the dashboard is already installed. To access the dashboard, run::
@ -67,7 +67,7 @@ On Minikube, the dashboard is already installed. To access the dashboard, run::
Technical details
-----------------
Under the hood, Tutor wraps ``kubectl`` commands to interact with the cluster. The various commands called by Tutor are printed in the console, so that you can reproduce and modify them yourself.
Under the hood, Tutor wraps ``kubectl`` commands to interact with the cluster. The various commands called by Tutor are printed in the console so that you can reproduce and modify them yourself.
Basically, the whole platform is described in manifest files stored in ``$(tutor config printroot)/env/k8s``. There is also a ``kustomization.yml`` file at the project root for `declarative application management <https://kubectl.docs.kubernetes.io/guides/config_management/introduction/#declarative-application-management>`__. This allows us to start and update resources with commands similar to ``kubectl apply -k $(tutor config printroot) --selector=...`` (see the ``kubectl apply`` `official documentation <https://kubectl.docs.kubernetes.io/references/kubectl/apply/>`__).
@ -88,7 +88,7 @@ Launch the platform on Kubernetes in one command::
tutor k8s quickstart
All Kubernetes resources are associated to the "openedx" namespace. If you don't see anything in the Kubernetes dashboard, you are probably looking at the wrong namespace... 😉
All Kubernetes resources are associated with the "openedx" namespace. If you don't see anything in the Kubernetes dashboard, you are probably looking at the wrong namespace... 😉
.. image:: img/k8s-dashboard.png
:alt: Kubernetes dashboard ("openedx" namespace)
@ -102,7 +102,7 @@ As with the :ref:`local installation <local>`, there are multiple commands to ru
tutor k8s -h
In particular, the ``tutor k8s start`` command restarts and reconfigures all services by running ``kubectl apply``. That means that you can delete containers, deployments or just any other kind of resources, and Tutor will re-create them automatically. You should just beware of not deleting any persistent data stored in persistent volume claims. For instance, to restart from a "blank slate", run::
In particular, the ``tutor k8s start`` command restarts and reconfigures all services by running ``kubectl apply``. That means that you can delete containers, deployments, or just any other kind of resources, and Tutor will re-create them automatically. You should just beware of not deleting any persistent data stored in persistent volume claims. For instance, to restart from a "blank slate", run::
tutor k8s stop
tutor k8s start

6
docs/local.rst
View File

@ -31,7 +31,7 @@ A fully-functional platform can be configured and run in one command::
tutor local quickstart
But you may want to run commands one at a time: it's faster when you need to run only part of the local deployment process, and it helps you understand how your platform works. In the following we decompose the ``quickstart`` command.
But you may want to run commands one at a time: it's faster when you need to run only part of the local deployment process, and it helps you understand how your platform works. In the following, we decompose the ``quickstart`` command.
Configuration
~~~~~~~~~~~~~
@ -111,7 +111,7 @@ You will most certainly need to create a user to administer the platform. Just r
tutor local createuser --staff --superuser yourusername user@email.com
You will asked to set the user password interactively.
You will be asked to set the user password interactively.
.. _democourse:
@ -156,7 +156,7 @@ After modifying Open edX settings, for instance when running ``tutor config save
Customizing the deployed services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You might want to customize the docker-compose services listed in ``$(tutor config printroot)/env/local/docker-compose.yml``. To do so, you should create a ``docker-compose.override.yml`` file in that same folder::
You might want to customise the docker-compose services listed in ``$(tutor config printroot)/env/local/docker-compose.yml``. To do so, you should create a ``docker-compose.override.yml`` file in that same folder::
vim $(tutor config printroot)/env/local/docker-compose.override.yml

4
docs/plugins.rst
View File

@ -12,9 +12,9 @@ Tutor comes with a plugin system that allows anyone to customise the deployment
# 3) Reconfigure and restart the platform
tutor local quickstart
For simple changes, it may be extremely easy to create a Tutor plugin: even non-technical users may get started with :ref:`simple yaml plugins <plugins_yaml>`.
For simple changes, it may be extremely easy to create a Tutor plugin: even non-technical users may get started with :ref:`simple YAML plugins <plugins_yaml>`.
In the following we learn how to use and create Tutor plugins.
In the following, we learn how to use and create Tutor plugins.
Commands
--------

10
docs/plugins/api.rst
View File

@ -7,7 +7,7 @@ Plugins can affect the behaviour of Tutor at multiple levels. They can:
* Add new templates to the Tutor project environment or modify existing ones (see :ref:`patches <plugin_patches>`, :ref:`templates <plugin_templates>` and :ref:`hooks <plugin_hooks>`).
* Add custom commands to the Tutor CLI (see :ref:`command <plugin_command>`).
There exists two different APIs to create Tutor plugins: either with YAML files or Python packages. YAML files are more simple to create, but are limited to just configuration and template patches.
There exist two different APIs to create Tutor plugins: either with YAML files or Python packages. YAML files are more simple to create but are limited to just configuration and template patches.
.. _plugin_config:
@ -16,7 +16,7 @@ config
The ``config`` attribute is used to modify existing and add new configuration parameters:
* ``config["add"]`` are key/values that should be added to the user-specific ``config.yml`` configuration. Add there passwords, secret keys and other values that do not have a default value.
* ``config["add"]`` are key/values that should be added to the user-specific ``config.yml`` configuration. Add their passwords, secret keys, and other values that do not have a default value.
* ``config["defaults"]`` are default key/values for this plugin. These values can be accessed even though they are not added to the ``config.yml`` user file. Users can override them manually with ``tutor config save --set ...``.
* ``config["set"]`` are existing key/values that should be modified. Be very careful what you add there! Different plugins may define conflicting values for some parameters.
@ -92,7 +92,7 @@ During initialisation, "myservice1" and "myservice2" will be run in sequence wit
To initialise a "foo" service, Tutor runs the "foo-job" service that is found in the ``env/local/docker-compose.jobs.yml`` file. By default, Tutor comes with a few services in this file: mysql-job, lms-job, cms-job. If your plugin requires running custom services during initialisation, you will need to add them to the ``docker-compose.jobs.yml`` template. To do so, just use the "local-docker-compose-jobs-services" patch.
In Kubernetes, the approach is the same, except that jobs are implemented as actual job objects in the ``k8s/jobs.yml`` template. To add your own services there, your plugin should implement the "k8s-jobs" patch.
In Kubernetes, the approach is the same, except that jobs are implemented as actual job objects in the ``k8s/jobs.yml`` template. To add your services there, your plugin should implement the "k8s-jobs" patch.
``pre-init``
++++++++++++
@ -146,7 +146,7 @@ or::
templates
~~~~~~~~~
In order to define plugin-specific hooks, a plugin should also have a template directory that includes the plugin hooks. The ``templates`` attribute should point to that directory.
To define plugin-specific hooks, a plugin should also have a template directory that includes the plugin hooks. The ``templates`` attribute should point to that directory.
Example::
@ -155,7 +155,7 @@ Example::
With the above declaration, you can store plugin-specific templates in the ``templates/myplugin`` folder next to the ``plugin.py`` file.
In Tutor, templates are `Jinja2 <https://jinja.palletsprojects.com/en/2.11.x/>`__-formatted files that will be rendered in the Tutor environment (the ``$(tutor config printroot)/env`` folder) when running ``tutor config save``. The environment files are overwritten every time the environment is saved. Plugin developers can create templates that make use of the built-in `Jinja2 API <https://jinja.palletsprojects.com/en/2.11.x/api/>`__. In addition, a couple additional filters are added by Tutor:
In Tutor, templates are `Jinja2 <https://jinja.palletsprojects.com/en/2.11.x/>`__-formatted files that will be rendered in the Tutor environment (the ``$(tutor config printroot)/env`` folder) when running ``tutor config save``. The environment files are overwritten every time the environment is saved. Plugin developers can create templates that make use of the built-in `Jinja2 API <https://jinja.palletsprojects.com/en/2.11.x/api/>`__. In addition, a couple of additional filters are added by Tutor:
* ``common_domain``: Return the longest common name between two domain names. Example: ``{{ "studio.demo.myopenedx.com"|common_domain("lms.demo.myopenedx.com") }}`` is equal to "demo.myopenedx.com".
* ``encrypt``: Encrypt an arbitrary string. The encryption process is compatible with `htpasswd <https://httpd.apache.org/docs/2.4/programs/htpasswd.html>`__ verification.

6
docs/plugins/gettingstarted.rst
View File

@ -14,7 +14,7 @@ YAML files that are stored in the tutor plugins root folder will be automaticall
On Linux, this points to ``~/.local/share/tutor-plugins``. The location of the plugin root folder can be modified by setting the ``TUTOR_PLUGINS_ROOT`` environment variable.
YAML plugins must define two special top-level keys: ``name`` and ``version``. Then, YAML plugins may use two more top-level keys to customize Tutor's behavior: ``config`` and ``patches``. Custom CLI commands, templates, and hooks are not supported by YAML plugins.
YAML plugins must define two special top-level keys: ``name`` and ``version``. Then, YAML plugins may use two more top-level keys to customise Tutor's behaviour: ``config`` and ``patches``. Custom CLI commands, templates, and hooks are not supported by YAML plugins.
Let's create a simple plugin that adds your own `Google Analytics <https://analytics.google.com/>`__ tracking code to your Open edX platform. We need to add the ``GOOGLE_ANALYTICS_ACCOUNT`` and ``GOOGLE_ANALYTICS_TRACKING_ID`` settings to both the LMS and the CMS settings. To do so, we will only have to create the ``openedx-common-settings`` patch, which is shared by the development and the production settings both for the LMS and the CMS. First, create the plugin directory::
@ -58,7 +58,7 @@ That's it! And it's very easy to share your plugins. Just upload them to your Gi
Python package
~~~~~~~~~~~~~~
Creating a plugin as a Python package allows you to define more complex logic and to store your patches in a more structured way. Python Tutor plugins are regular Python packages that define an entrypoint within the ``tutor.plugin.v0`` group:
Creating a plugin as a Python package allows you to define more complex logic and store your patches in a more structured way. Python Tutor plugins are regular Python packages that define an entry point within the ``tutor.plugin.v0`` group:
Example::
@ -70,7 +70,7 @@ Example::
},
)
The ``myplugin/plugin.py`` Python module can then define the attributes ``config``, ``patches``, ``hooks``, and ``templates`` to specify the plugin's behavior. The attributes may be defined either as dictionaries or as zero-argument callables returning dictionaries; in the latter case, the callable will be evaluated upon plugin load. Finally, the ``command`` attribute can be defined as an instance of ``click.Command`` to define the plugin's command line interface.
The ``myplugin/plugin.py`` Python module can then define the attributes ``config``, ``patches``, ``hooks``, and ``templates`` to specify the plugin's behaviour. The attributes may be defined either as dictionaries or as zero-argument callables returning dictionaries; in the latter case, the callable will be evaluated upon plugin load. Finally, the ``command`` attribute can be defined as an instance of ``click.Command`` to define the plugin's command line interface.
Example::

2
docs/quickstart.rst
View File

@ -24,6 +24,6 @@ Yes :) This is what happens when you run ``tutor local quickstart``:
4. Docker containers are provisioned.
5. A full, production-ready Open edX platform (`Maple <https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/open-release-maple.master/platform_releases/maple.html>`__ release) 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.
The whole procedure should require less than 10 minutes, on a server with 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 learn more about what you can do with Tutor and Open edX, check out the :ref:`whatnext` section. If the quickstart installation method above somehow didn't work for you, check out the :ref:`troubleshooting` guide.

12
docs/troubleshooting.rst
View File

@ -12,7 +12,7 @@ What should you do if you have a problem?
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 <https://github.com/overhangio/tutor/issues?utf8=%E2%9C%93&q=is%3Aissue>`_.
4. Search for your problem in the `community forums <https://discuss.overhang.io>`__.
5. If, despite all your efforts, you can't solve the problem by yourself, you should discuss it in the `community forums <https://discuss.overhang.io>`__. Please give as much details about your problem as possible! As a rule of thumb, **people will not dedicate more time to solving your problem than you took to write your question**.
5. If despite all your efforts, you can't solve the problem by yourself, you should discuss it in the `community forums <https://discuss.overhang.io>`__. Please give as many details about your problem as possible! As a rule of thumb, **people will not dedicate more time to solving your problem than you took to write your question**.
6. If you are *absolutely* positive that you are facing a technical issue with Tutor, and not with Open edX, not with your server, not your custom configuration, then, and only then, should you open an issue on `Github <https://github.com/overhangio/tutor/issues/>`__. You *must* follow the instructions from the issue template!!! If you do not follow this procedure, your Github issues will be mercilessly closed 🤯.
Do you need professional assistance with your tutor-managed Open edX platform? Overhang.IO offers online support as part of its `Long Term Support (LTS) offering <https://overhang.io/tutor/pricing>`__.
@ -31,7 +31,7 @@ To view the logs from all containers use the ``tutor local logs`` command, which
tutor local logs --follow
To view the logs from just one container, for instance the web server::
To view the logs from just one container, for instance, the webserver::
tutor local logs --follow caddy
@ -46,7 +46,7 @@ If you'd rather use a graphical user interface for viewing logs, you are encoura
"Cannot start service caddy: driver failed programming external connectivity"
-----------------------------------------------------------------------------
The containerized Caddy needs to listen to ports 80 and 443 on the host. If there is already a webserver, such as Apache, Caddy or Nginx, running on the host, the caddy container will not be able to start. To solve this issue, check the section on :ref:`how to setup a web proxy <web_proxy>`.
The containerized Caddy needs to listen to ports 80 and 443 on the host. If there is already a webserver, such as Apache, Caddy, or Nginx, running on the host, the caddy container will not be able to start. To solve this issue, check the section on :ref:`how to setup a web proxy <web_proxy>`.
"Couldn't connect to docker daemon"
-----------------------------------
@ -55,14 +55,14 @@ This is not an error with Tutor, but with your Docker installation. This is freq
docker run --rm hello-world
If the above command does not work, you should fix your Docker installation. Some people will suggest to run Docker as root, or with ``sudo``; **do not do this**. Instead, what you should probably do is to add your user to the "docker" group. For more information, check out the `official Docker installation instructions <https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user>`__.
If the above command does not work, you should fix your Docker installation. Some people will suggest running Docker as root, or with ``sudo``; **do not do this**. Instead, what you should probably do is add your user to the "docker" group. For more information, check out the `official Docker installation instructions <https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user>`__.
.. _migrations_killed:
"Running migrations... Killed!" / "Command failed with status 137: docker-compose"
----------------------------------------------------------------------------------
Open edX requires at least 4 GB RAM, in particular to run the SQL migrations. If the ``tutor local quickstart`` command dies after displaying "Running migrations", you most probably need to buy more memory or add swap to your machine.
Open edX requires at least 4 GB RAM, in particular, to run the SQL migrations. If the ``tutor local quickstart`` command dies after displaying "Running migrations", you most probably need to buy more memory or add swap to your machine.
On macOS, by default, Docker allocates at most 2 GB of RAM to containers. ``quickstart`` tries to check your current allocation and outputs a warning if it can't find a value of at least 4 GB. You should follow `these instructions from the official Docker documentation <https://docs.docker.com/docker-for-mac/#advanced>`__ to allocate at least 4-5 GB to the Docker daemon.
@ -109,7 +109,7 @@ This will occur if you try to run a development environment without patching the
The chosen default language does not display properly
-----------------------------------------------------
By default, Open edX comes with a `limited set <https://github.com/openedx/edx-platform/blob/master/conf/locale/config.yaml>` of translation/localization files. To complement these languages, we add locales from the `openedx-i18n project <https://github.com/openedx/openedx-i18n/blob/master/edx-platform/locale/config-extra.yaml>`_. But not all supported locales are downloaded. In some cases, the chosen default language will not display properly because if was not packaged in either edx-platform or openedx-i18n. If you feel like your language should be packaged, please `open an issue on the openedx-i18n project <https://github.com/openedx/openedx-i18n/issues>`_.
By default, Open edX comes with a `limited set <https://github.com/openedx/edx-platform/blob/master/conf/locale/config.yaml>` of translation/localization files. To complement these languages, we add locales from the `openedx-i18n project <https://github.com/openedx/openedx-i18n/blob/master/edx-platform/locale/config-extra.yaml>`_. But not all supported locales are downloaded. In some cases, the chosen default language will not display properly because it was not packaged in either edx-platform or openedx-i18n. If you feel like your language should be packaged, please `open an issue on the openedx-i18n project <https://github.com/openedx/openedx-i18n/issues>`_.
When I make changes to a course in the CMS, they are not taken into account by the LMS
--------------------------------------------------------------------------------------

2
docs/tutor.rst
View File

@ -69,7 +69,7 @@ Releasing a new version
~~~~~~~~~~~~~~~~~~~~~~~
- Bump the ``__version__`` value in ``tutor/__about__.py``. (see :ref:`versioning` below)
- Replace "Unreleased" by the version name and date in CHANGELOG.md.
- Replace "Unreleased" with the version name and date in CHANGELOG.md.
- Create a commit with the version changelog.
- Run ``make release``: this will push to the default repo/branch for the current branch.

4
docs/tutorials/arm64.rst
View File

@ -5,7 +5,7 @@ Running Tutor on ARM-based systems
Tutor can be used on ARM64 systems, although support for that platform is currently experimental.
There are generally two ways to run Tutor on am ARM system - using qemu to run x86_64 images using emulation or running native ARM images. Since emulation can be quite slow, this Tutorial will focus on using native images where possible.
There are generally two ways to run Tutor on an ARM system - using qemu to run x86_64 images using emulation or running native ARM images. Since emulation can be quite slow, this Tutorial will focus on using native images where possible.
There are currently no official ARM64 images provided for Tutor, but Tutor makes it easy to build them yourself.
@ -36,7 +36,7 @@ Change the database server
The version of MySQL that Open edX uses by default does not support the ARM architecture. Our current recommendation is to use MariaDB instead, which should be largely compatible.
.. warning::
Note that using MariaDB is experimental and incompatibilites may exist, so this should only be used for local development - not for production instances.
Note that using MariaDB is experimental and incompatibilities may exist, so this should only be used for local development - not for production instances.
Configure Tutor to use MariaDB::

2
docs/tutorials/datamigration.rst
View File

@ -8,7 +8,7 @@ With Tutor, all data are stored in a single folder. This means that it's extreme
tutor local stop
3. Transfer the configuration, environment and platform data from server 1 to server 2::
3. Transfer the configuration, environment, and platform data from server 1 to server 2::
rsync -avr "$(tutor config printroot)/" username@server2:/tmp/tutor/

2
docs/tutorials/google-smtp.rst
View File

@ -6,7 +6,7 @@ By default, Tutor comes with a simple SMTP server for sending emails. Such a ser
.. warning::
Google Mail SMTP servers come with their own set of limitations. For instance, you are limited to sending 500 emails a day. Reference: https://support.google.com/mail/answer/22839
You should authorize third party to access your Google Mail account. In your Google Mail account, select "Manage Account", "Security", and turn on "Less Secure App Access". Check the Google documentation for more information on "less secure apps": https://support.google.com/accounts/answer/6010255
You should authorize third-party to access your Google Mail account. In your Google Mail account, select "Manage Account", "Security", and turn on "Less Secure App Access". Check the Google documentation for more information on "less secure apps": https://support.google.com/accounts/answer/6010255
Then, check that you can reach the Google Mail SMTP service from your own server::

4
docs/tutorials/multiplatforms.rst
View File

@ -3,9 +3,9 @@ Running multiple Open edX platforms on a single server
With Tutor, it is easy to run multiple Open edX instances on a single server. To do so, the following configuration parameters must be different for all platforms:
- ``TUTOR_ROOT``: so that configuration, environment and data are not mixed up between platforms.
- ``TUTOR_ROOT``: so that configuration, environment, and data are not mixed up between platforms.
- ``LOCAL_PROJECT_NAME``: the various docker-compose projects cannot share the same name.
- ``CADDY_HTTP_PORT``: exposed ports cannot be shared by two different containers.
- ``LMS_HOST``, ``CMS_HOST``: the different platforms must be accessible from different domain (or subdomain) names.
In addition, a web proxy must be setup on the host, as described :ref:`in the corresponding tutorial <web_proxy>`.
In addition, a web proxy must be set up on the host, as described :ref:`in the corresponding tutorial <web_proxy>`.

6
docs/tutorials/nightly.rst
View File

@ -3,7 +3,7 @@
Running Open edX on the master branch ("nightly")
=================================================
Tutor was designed to make it easy for everyone to run the latest release of Open edX. But sometimes, you want to run the latest, bleeding edge version of Open edX. This is what we call "running master", as opposed to running the release branch. Running the master branch in production is strongly **not** recommended, unless you are an Open edX expert and you really know what you are doing. But Open edX developers frequently need to run the master branch locally to implement and test new features. Thus, Tutor makes it easy to run Open edX on the master branch: this is called "Tutor Nightly".
Tutor was designed to make it easy for everyone to run the latest release of Open edX. But sometimes, you want to run the latest, bleeding-edge version of Open edX. This is what we call "running master", as opposed to running the release branch. Running the master branch in production is strongly **not** recommended unless you are an Open edX expert and you really know what you are doing. But Open edX developers frequently need to run the master branch locally to implement and test new features. Thus, Tutor makes it easy to run Open edX on the master branch: this is called "Tutor Nightly".
Installing Tutor Nightly
------------------------
@ -20,7 +20,7 @@ All Tutor plugins that you wish to use should likewise be installed from the "ni
git clone --branch=nightly https://github.com/overhangio/tutor-mfe.git
pip install -e ./tutor-mfe
You can then run the usual ``tutor`` commands ::
You can then run the usual ``tutor`` commands::
tutor local quickstart
tutor local stop
@ -59,7 +59,7 @@ When running Tutor Nightly, you usually do not want to override your existing Tu
Making changes to Tutor Nightly
-------------------------------
In general pull requests should be open on the "master" branch of Tutor: the "master" branch is automatically merged on the "nightly" branch at every commit, such that changes made to Tutor releases find their way to Tutor Nightly as soon as they are merged. However, sometimes you want to make changes to Tutor Nightly exclusively, and not to the Tutor releases. This might be the case for instance when upgrading the running version of a third party service (for instance: Elasticsearch, Mysql), or when the master branch requires specific changes. In that case, you should follow the instructions from the :ref:`contributing` section of the docs, with the following differences:
In general pull requests should be open on the "master" branch of Tutor: the "master" branch is automatically merged on the "nightly" branch at every commit, such that changes made to Tutor releases find their way to Tutor Nightly as soon as they are merged. However, sometimes you want to make changes to Tutor Nightly exclusively, and not to the Tutor releases. This might be the case for instance when upgrading the running version of a third-party service (for instance: Elasticsearch, MySQL), or when the master branch requires specific changes. In that case, you should follow the instructions from the :ref:`contributing` section of the docs, with the following differences:
- Open your pull request on top of the "nightly" branch instead of "master".
- Add a description of your changes to CHANGELOG-nightly.md instead of CHANGELOG.md

6
docs/tutorials/podman.rst
View File

@ -3,7 +3,7 @@ Running Tutor with Podman
You have the option of running Tutor with `Podman <https://podman.io/>`__, instead of the native Docker tools. This has some practical advantages: it does not require a running Docker daemon, and it enables you to run and build Docker images without depending on any system component running ``root``. As such, it is particularly useful for building Tutor images from CI pipelines.
The ``podman`` CLI aims to be fully compatible with the ``docker`` CLI, and ``podman-compose`` is meant to be a fully-compatible alias of ``docker-compose``. This means that you should be able to use together with Tutor, without making any changes to Tutor itself.
The ``podman`` CLI aims to be fully compatible with the ``docker`` CLI and ``podman-compose`` is meant to be a fully-compatible alias of ``docker-compose``. This means that you should be able to use it together with Tutor, without making any changes to Tutor itself.
.. warning::
Since this was written, it was discovered that there are major compatibility issues between ``podman-compose`` and ``docker-compose``. Thus, podman cannot be considered a drop-in replacement of Docker in the context of Tutor -- at least for running Open edX locally.
@ -17,7 +17,7 @@ Enabling Podman
Podman is supported on a variety of development platforms, see the `installation instructions <https://podman.io/getting-started/installation>`_ for details.
Once you have installed Podman and its dependencies on the platform of your choice, you'll need to make sure that its ``podman`` binary, usually installed as ``/usr/bin/podman``, is aliased to ``docker``, and is included as such in your system ``$PATH``. On some CentOS and Fedora releases you can install a package named ``podman-docker`` to do this for you, but on other platforms you'll need to take of this yourself.
Once you have installed Podman and its dependencies on the platform of your choice, you'll need to make sure that its ``podman`` binary, usually installed as ``/usr/bin/podman``, is aliased to ``docker``, and is included as such in your system ``$PATH``. On some CentOS and Fedora releases, you can install a package named ``podman-docker`` to do this for you, but on other platforms, you'll need to take of this yourself.
- If ``$HOME/bin`` is in your ``$PATH``, you can create a symbolic link there::
@ -31,7 +31,7 @@ Once you have installed Podman and its dependencies on the platform of your choi
Enabling podman-compose
~~~~~~~~~~~~~~~~~~~~~~~
``podman-compose`` is available as a package from PyPI, and can thus be installed with ``pip``. See `its README <https://github.com/containers/podman-compose/blob/devel/README.md>`_ for installation instructions. Note that if you have installed Tutor in its own virtualenv, you'll need to run ``pip install podman-compose`` in that same virtualenv.
``podman-compose`` is available as a package from PyPI, and can thus be installed with ``pip``. See `its README <https://github.com/containers/podman-compose/blob/devel/README.md>`_ for installation instructions. Note that if you have installed Tutor in its virtualenv, you'll need to run ``pip install podman-compose`` in that same virtualenv.
Once installed, you'll again need to create a symbolic link that aliases ``docker-compose`` to ``podman-compose``.

2
docs/tutorials/proxy.rst
View File

@ -7,7 +7,7 @@ The containerized web server (`Caddy <https://caddyserver.com/>`__) needs to lis
tutor config save --set ENABLE_WEB_PROXY=false --set CADDY_HTTP_PORT=81
In this example, the caddy container port would be mapped to 81 instead of 80. You must then configure the web proxy on the host. As of v11.0.0, configuration files are no longer provided for automatic configuration of your web proxy. Basically, you should setup a reverse proxy to `localhost:CADDY_HTTP_PORT` from the following hosts: LMS_HOST, PREVIEW_LMS_HOST, CMS_HOST, as well as any additional host exposed by your plugins.
In this example, the caddy container port would be mapped to 81 instead of 80. You must then configure the web proxy on the host. As of v11.0.0, configuration files are no longer provided for the automatic configuration of your web proxy. You should set up a reverse proxy to `localhost:CADDY_HTTP_PORT` from the following hosts: LMS_HOST, PREVIEW_LMS_HOST, CMS_HOST, as well as any additional host exposed by your plugins.
.. warning::
In this setup, the Caddy HTTP port will be exposed to the world. Make sure to configure your server firewall to block unwanted connections to your server's ``CADDY_HTTP_PORT``. Alternatively, you can configure the Caddy container to accept only local connections::

16
docs/tutorials/scale.rst
View File

@ -23,14 +23,14 @@ Fortunately, Open edX was designed to run at scale -- most notably at `edX.org <
Increasing web server capacity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As the server CPU and memory are increased, the request throughput can be increased by adjusting the number of uWSGI workers (see :ref:`configuration docs <openedx_configuration>`). By default, the "lms" and "cms" containers each spawn 2 uWSGI workers. The number of workers should be increased if you observe an increase of the latency of user requests but CPU usage remains below 100%. To increase the number of workers for the LMS and the CMS, run for example::
As the server CPU and memory are increased, the request throughput can be increased by adjusting the number of uWSGI workers (see :ref:`configuration docs <openedx_configuration>`). By default, the "lms" and "cms" containers each spawn 2 uWSGI workers. The number of workers should be increased if you observe an increase in the latency of user requests but CPU usage remains below 100%. To increase the number of workers for the LMS and the CMS, run for example::
tutor config save \
--set OPENEDX_LMS_UWSGI_WORKERS=8 \
--set OPENEDX_CMS_UWSGI_WORKERS=4
tutor local restart lms cms
The right values will very much depend on your server available memory and CPU performance, as well as the maximum number of simultaneous users who use your platform. As an example data point, it was reported that a large Open edX platform can serve up to 500k unique users per week on a virtual server with 8 vCPU and 16 GB memory.
The right values will very much depend on your server's available memory and CPU performance, as well as the maximum number of simultaneous users who use your platform. As an example data point, it was reported that a large Open edX platform can serve up to 500k unique users per week on a virtual server with 8 vCPU and 16 GB memory.
Offloading data storage
~~~~~~~~~~~~~~~~~~~~~~~
@ -39,14 +39,14 @@ Aside from web workers, the most resource-intensive services are in the data per
- `Elasticsearch <https://www.elastic.co/elasticsearch/>`__: indexing of course contents and forum topics, mostly for search. Elasticsearch is never a source of truth in Open edX, and the data can thus be trashed and re-created safely.
- `MySQL <https://www.mysql.com>`__: structured, consistent data storage which is the default destination of all data.
- `Mongodb <https://www.mongodb.com>`__: structured storage of course data.
- `MongoDB <https://www.mongodb.com>`__: structured storage of course data.
- `Redis <https://redis.io/>`__: caching and asynchronous task management.
- `MinIO <https://min.io>`__: S3-like object storage for user-uploaded files, which is enabled by the `tutor-minio <https://github.com/overhangio/tutor-minio>`__ plugin. It is possible to replace MinIO by direct filesystem storage (the default), but scaling will then become much more difficult down the road.
When attempting to scale a single-server deployment, we recommend to start by offloading some of these stateful data storage components, in the same order of priority. There are multiple benefits:
When attempting to scale a single-server deployment, we recommend starting by offloading some of these stateful data storage components, in the same order of priority. There are multiple benefits:
1. It will free up some resource both for the web workers and the data storage components.
2. It is a first step towards horizontal scaling of the web workers.
1. It will free up some resources both for the web workers and the data storage components.
2. It is the first step towards horizontal scaling of the web workers.
3. It becomes possible to either install every component as a separate service or rely on 3rd-party SaaS with high availability.
Moving each of the data storage components is a fairly straightforward process, although details vary for every component. For instance, for the MySQL database, start by disabling the locally running MySQL instance::
@ -63,7 +63,7 @@ Then, migrate the data located at ``$(tutor config printroot)/data/mysql`` to th
The changes will be taken into account the next time the platform is restarted.
Beware that moving the data components to dedicated servers has the potential of creating new single points of failures (`SPOF <https://en.wikipedia.org/wiki/Single_point_of_failure>`__). To avoid this situation, each component should be installed as a highly available service (or as highly available SaaS).
Beware that moving the data components to dedicated servers has the potential of creating new single points of failure (`SPOF <https://en.wikipedia.org/wiki/Single_point_of_failure>`__). To avoid this situation, each component should be installed as a highly available service (or as a highly available SaaS).
Scaling with multiple servers
-----------------------------
@ -73,7 +73,7 @@ Horizontally scaling web services
As the number of users of a web platform increases, they put increased pressure on the web workers that respond to their requests. Thus, in most cases, web worker performance is the first bottleneck that system administrators have to face when their service becomes more popular. Initially, any given Kubernetes-based Tutor platform ships with one replica for each deployment. To increase (or reduce) the number of replicas for any given service, run ``tutor k8s scale <name> <number of replicas>``. Behind the scenes, this command will trigger a ``kubectl scale --replicas=...`` command that will seamlessly increase the number of pods for that deployment.
In Open edX there are multiple web services that are exposed to the outside world. The ones that usually receive the most traffic are, in decreasing order, the LMS, the CMS and the forum (assuming the `tutor-forum <https://github.com/overhangio/tutor-forum>`__ plugin was enabled). As an example, all three deployment replicas can be scaled by running::
In Open edX multiple web services are exposed to the outside world. The ones that usually receive the most traffic are, in decreasing order, the LMS, the CMS, and the forum (assuming the `tutor-forum <https://github.com/overhangio/tutor-forum>`__ plugin was enabled). As an example, all three deployment replicas can be scaled by running::
tutor k8s scale lms 8
tutor k8s scale cms 4

2
docs/tutorials/theming.rst
View File

@ -6,7 +6,7 @@ Changing the appearance of Open edX
Installing a custom theme
-------------------------
Comprehensive theming is enabled by default, but only the default theme is compiled. `Indigo <https://github.com/overhangio/indigo>`__ is a better, ready-to-run theme which you can start using today.
Comprehensive theming is enabled by default, but only the default theme is compiled. `Indigo <https://github.com/overhangio/indigo>`__ is a better, ready-to-run theme that you can start using today.
To compile your own theme, add it to the ``env/build/openedx/themes/`` folder::

4
docs/whatnext.rst
View File

@ -3,12 +3,12 @@
What next?
==========
You have gone through the :ref:`Quickstart installation <quickstart>`: at this point you should have a running Open edX platform. If you don't, please follow the instructions from the :ref:`Troubleshooting <troubleshooting>` section.
You have gone through the :ref:`Quickstart installation <quickstart>`: at this point, you should have a running Open edX platform. If you don't, please follow the instructions from the :ref:`Troubleshooting <troubleshooting>` section.
Logging-in as administrator
---------------------------
Out of the box, Tutor does not create any user for you. You will want to create a user yourself with staff and administrator privileges in order to access the studio. There is a :ref:`simple command for that <createuser>`.
Out of the box, Tutor does not create any user for you. You will want to create a user yourself with staff and administrator privileges to access the studio. There is a :ref:`simple command for that <createuser>`.
Importing a demo course
-----------------------

2
tutor/commands/plugins.py
View File

@ -14,7 +14,7 @@ from .context import Context
@click.group(
name="plugins",
short_help="Manage Tutor plugins",
help="Manage Tutor plugins to add new features and customize your Open edX platform",
help="Manage Tutor plugins to add new features and customise your Open edX platform",
)
def plugins_command() -> None:
"""

2
tutor/plugins.py
View File

@ -37,7 +37,7 @@ class BasePlugin:
`hooks` (dict str->list[str]): hooks are commands that will be run at various points
during the lifetime of the platform. For instance, to run `service1` and `service2`
in sequence during initialization, you should define:
in sequence during initialisation, you should define:
hooks["init"] = ["service1", "service2"]

2
tutor/templates/k8s/deployments.yml
View File

@ -348,7 +348,7 @@ spec:
- name: mysql
image: {{ DOCKER_IMAGE_MYSQL }}
# Note the ignore-db-dir: this is because ext4 volumes are created with a lost+found directory in them, which causes mysql
# initialization to fail
# initialisation to fail
args: ["mysqld", "--character-set-server=utf8", "--collation-server=utf8_general_ci", "--ignore-db-dir=lost+found"]
env:
- name: MYSQL_ROOT_PASSWORD