diff --git a/CHANGELOG.md b/CHANGELOG.md index ee7eac6b370..b644868ce6e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,8 @@ Note: Breaking changes between versions are indicated by "💥". ## Unreleased +- [Deprecation] Mark `tutor dev runserver` as deprecated in favor of `tutor dev start`. Since `start` now supports bind-mounting and breakpoint debugging, `runserver` is redundant and will be removed in a future release. +- [Improvement] Allow breakpoint debugging when attached to a service via `tutor dev start SERVICE`. - [Feature] Introduce the ``-m/--mount`` option in ``local`` and ``dev`` commands to auto-magically bind-mount folders from the host. - [Feature] Add `tutor dev quickstart` command, which is similar to `tutor local quickstart`, except that it uses dev containers instead of local production ones and includes some other small differences for the convience of Open edX developers. This should remove some friction from the Open edX development setup process, which previously required that users provision using local producation containers (`tutor local quickstart`) but then stop them and switch to dev containers (`tutor local stop && tutor dev start -d`). - 💥[Improvement] Make it possible to run `tutor k8s exec ` (#636). As a consequence, it is no longer possible to run quoted commands: `tutor k8s exec ""`. Instead, you should remove the quotes: `tutor k8s exec `. diff --git a/docs/dev.rst b/docs/dev.rst index deb76ca077c..36fad237cb2 100644 --- a/docs/dev.rst +++ b/docs/dev.rst @@ -97,7 +97,7 @@ The ``openedx-dev`` Docker image is based on the same ``openedx`` image used by If you are using a custom ``openedx`` image, then you will need to rebuild ``openedx-dev`` every time you modify ``openedx``. To so, run:: - tutor dev dc build lms + tutor dev dc build lmsru .. _bind_mounts: @@ -112,7 +112,7 @@ It may sometimes be convenient to mount container directories on the host, for i Bind-mount volumes with ``--mount`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The ``run``, ``runserver``, ``init`` and ``start`` subcommands of ``tutor dev`` and ``tutor local`` support the ``-m/--mount`` option (see :option:`tutor dev start -m`) which can take two different forms. The first is explicit:: +The ``run``, ``init`` and ``start`` subcommands of ``tutor dev`` and ``tutor local`` support the ``-m/--mount`` option (see :option:`tutor dev start -m`) which can take two different forms. The first is explicit:: tutor dev start --mount=lms:/path/to/edx-platform:/openedx/edx-platform lms @@ -171,7 +171,7 @@ The above solution may not work for you if you already have an existing director Override docker-compose volumes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The above solutions require that you explicitly pass the ``-m/--mount`` options to every ``run``, ``runserver``, ``start`` or ``init`` command, which may be inconvenient. To address these issues, you can create a ``docker-compose.override.yml`` file that will specify custom volumes to be used with all ``dev`` commands:: +The above solutions require that you explicitly pass the ``-m/--mount`` options to every ``run``, ``start`` or ``init`` command, which may be inconvenient. To address these issues, you can create a ``docker-compose.override.yml`` file that will specify custom volumes to be used with all ``dev`` commands:: vim "$(tutor config printroot)/env/dev/docker-compose.override.yml" @@ -207,7 +207,7 @@ Setting up a development environment for edx-platform Following the instructions :ref:`above ` on how to bind-mount directories from the host above, you may mount your own `edx-platform `__ fork in your containers by running:: - tutor dev runserver --mount=/path/to/edx-platform lms + tutor dev start -d --mount=/path/to/edx-platform lms But to achieve that, you will have to make sure that your fork works with Tutor. @@ -250,7 +250,7 @@ You will have to re-build the openedx Docker image once:: tutor images build openedx -You should then run the development server as usual, with ``runserver``. Every change made to the ``mypackage`` folder will be picked up and the development server will be automatically reloaded. +You should then run the development server as usual, with ``start``. Every change made to the ``mypackage`` folder will be picked up and the development server will be automatically reloaded. Running edx-platform unit tests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/tutorials/nightly.rst b/docs/tutorials/nightly.rst index ee29f29acc5..d9635183cbb 100644 --- a/docs/tutorials/nightly.rst +++ b/docs/tutorials/nightly.rst @@ -22,10 +22,9 @@ In addition to installing Tutor Nightly itself, this will install automatically Once Tutor Nightly is installed, you can run the usual ``tutor`` commands:: - tutor local quickstart - tutor local stop - tutor dev runserver lms - # ... + tutor dev quickstart + tutor dev run lms bash + # ... and so on Upgrading to the latest version of Open edX ------------------------------------------- diff --git a/docs/tutorials/plugin.rst b/docs/tutorials/plugin.rst index 784886fdbb5..43b92e67f75 100644 --- a/docs/tutorials/plugin.rst +++ b/docs/tutorials/plugin.rst @@ -260,6 +260,22 @@ Run this initialisation task with:: ++++++ done! All services initialised. +Tailoring services for development +---------------------------------- + +When you add services via :patch:`local-docker-compose-services`, those services will be available both in local production mode (``tutor local start``) and local development mode (``tutor dev start``). Sometimes, you may wish to further customize a service in ways that would not be suitable for production, but could be helpful for developers. To add in such customizations, implement the :patch:`local-docker-compose-dev-services` patch. For example, we can enable breakpoint debugging on the "myservice" development container by enabling the ``stdin_open`` and ``tty`` options:: + + hooks.Filters.ENV_PATCHES.add_item( + ( + "local-docker-compose-dev-services", + """ + myservice: + stdin_open: true + tty: true + """, + ) + ) + Final result ------------ @@ -311,6 +327,16 @@ Eventually, our plugin is composed of the following files, all stored within the """, ) ) + hooks.Filters.ENV_PATCHES.add_item( + ( + "local-docker-compose-dev-services", + """ + myservice-job: + stdin_open: true + tty: true + """, + ) + ) # Modify configuration hooks.Filters.CONFIG_DEFAULTS.add_item( diff --git a/docs/tutorials/theming.rst b/docs/tutorials/theming.rst index 77a6aa6e976..f9cb0712c4b 100644 --- a/docs/tutorials/theming.rst +++ b/docs/tutorials/theming.rst @@ -44,7 +44,7 @@ With Tutor, it's pretty easy to develop your own themes. Start by placing your f Then, run a local webserver:: - tutor dev runserver lms + tutor dev start -d lms The LMS can then be accessed at http://local.overhang.io:8000. You will then have to :ref:`enable that theme `:: diff --git a/tutor/commands/dev.py b/tutor/commands/dev.py index 9bfe54255b6..36da6d0dbc2 100644 --- a/tutor/commands/dev.py +++ b/tutor/commands/dev.py @@ -98,7 +98,7 @@ def quickstart(context: click.Context, non_interactive: bool, pullimages: bool) @click.command( - help="Run a development server", + help="DEPRECATED: Use 'tutor dev start ...' instead!", context_settings={"ignore_unknown_options": True}, ) @compose.mount_option @@ -111,6 +111,10 @@ def runserver( options: t.List[str], service: str, ) -> None: + depr_warning = "'runserver' is deprecated and will be removed in a future release. Use 'start' instead." + if "-v" in options or "--volume" in options or '--volume=' in options: + depr_warning += " Bind-mounts can be specified using '-m/--mount'." + fmt.echo_alert(depr_warning) config = tutor_config.load(context.obj.root) if service in ["lms", "cms"]: port = 8000 if service == "lms" else 8001 diff --git a/tutor/templates/dev/docker-compose.yml b/tutor/templates/dev/docker-compose.yml index 784a97e6103..c1cd3216229 100644 --- a/tutor/templates/dev/docker-compose.yml +++ b/tutor/templates/dev/docker-compose.yml @@ -8,6 +8,8 @@ x-openedx-service: target: development args: APP_USER_ID: "{{ HOST_USER_ID }}" + stdin_open: true + tty: true volumes: # Settings & config - ../apps/openedx/settings/lms:/openedx/edx-platform/lms/envs/tutor:ro