Skip to content
This repository has been archived by the owner on May 14, 2024. It is now read-only.

docs: add local plugin dev to README #256

Merged
merged 4 commits into from
May 30, 2023
Merged

docs: add local plugin dev to README #256

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8cea0fa
Update README.rst
connorhaugh May 25, 2023
0d7320a
docs: add provisioning steps
connorhaugh May 25, 2023
94b7c30
docs: add clarity
connorhaugh May 26, 2023
0553349
fix: remove LMS or studio admin from link text.
connorhaugh May 30, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 60 additions & 1 deletion README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,66 @@ By default, blockstore is run as an app inside of Open edX. Enable it using the
If you need to run blockstore as a separate service (e.g. for scalability or performance reasons), you can deploy blockstore in production using `the blockstore ansible role <https://github.com/openedx/configuration/tree/master/playbooks/roles/blockstore>`_.

-------------------------------------------------------
Running and testing as a separate service (development)
Development in Devstack
-------------------------------------------------------

If you want to develop blockstore as a local python package installed in edx-platform, use the following steps:

#. Prerequisite: Have an Open edX `Devstack <https://github.com/openedx/devstack>`_ properly installed and working. Your devstack must use the Nutmeg release of Open edX (or newer) or be tracking the ``master`` branch of ``edx-platform``.

#. To run blockstore as an app inside of Open edX, enable it by activating the waffle switch `blockstore.use_blockstore_app_api <https://edx.readthedocs.io/projects/edx-platform-technical/en/latest/featuretoggles.html#featuretoggle-blockstore.use_blockstore_app_api>`_ in LMS or Studio admin.

connorhaugh marked this conversation as resolved.
Show resolved Hide resolved
#. Clone this repo in the ``src/`` directory, a sibling directory of your devstack folder.

#. In your devstack directory, run the following commands in order:

.. code::

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there an assumption about virtual environments here? If using a virtual environment, should be activating it before these operations.

Copy link
Contributor Author

@connorhaugh connorhaugh May 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You actually totally could do this without a venv. I know this because I accidentally did. I wouldn't recommend it though...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is such a base assumption for working in openedx I don't feel like I need to include it.

# bring up the lms +studio containers
make dev.up.large-and-slow
# Bring up the studio shell
make dev.shell.studio
# Unistall the pypi blockstore
pip uninstall openedx-blockstore #You will need to confirm the unistall with "Y".
#Install your local blockstore.
connorhaugh marked this conversation as resolved.
Show resolved Hide resolved
pip install -e /edx/src/blockstore/
exit
connorhaugh marked this conversation as resolved.
Show resolved Hide resolved

# do the same in the LMS
make dev.shell.lms
# Unistall the pypi blockstore
pip uninstall openedx-blockstore #You will need to confirm the unistall with "Y".
#Install your local blockstore.
pip install -e /edx/src/blockstore/
exit

#restart the servers to bring in changes.
make dev.restart-devserver.lms dev.restart-devserver.studio

# you can see that your env is now installed openedx-blockstore from a local directory ``/edx/src/blockstore`` by running:
make dev.shell.lms
connorhaugh marked this conversation as resolved.
Show resolved Hide resolved
pip list


Seeing your changes will sometimes require running make requirements and then restarting the container.

You're probably also going to want to create a collection and organization for using content libraries from the devstack command line, using:

connorhaugh marked this conversation as resolved.
Show resolved Hide resolved
.. code::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are your assumptions about the existence and state of a blockstore container prior to this point? What about now?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This guide makes no assumptions that you ever ran blockstore as a separate service, and hence, assumes no container exists. There previously was an error which referenced such a container, but that was a copy-paste error.


# Create a "Collection" that new content libraries / xblocks can be created within:
docker exec -t edx.devstack.lms bash -c "source ~/.bashrc && echo \"from blockstore.apps.bundles.models import Collection; coll, _ = Collection.objects.get_or_create(title='Devstack Content Collection', uuid='11111111-2111-4111-8111-111111111111')\" | ./manage.py shell"
# Create an "Organization":
docker exec -t edx.devstack.lms bash -c "source /edx/app/edxapp/edxapp_env && echo \"from organizations.models import Organization; Organization.objects.get_or_create(short_name='DeveloperInc', defaults={'name': 'DeveloperInc', 'active': True})\" | python /edx/app/edxapp/edx-platform/manage.py lms shell"

connorhaugh marked this conversation as resolved.
Show resolved Hide resolved
The Library Authoring MFE will want to know about that collection id `using a ENV variable. <https://github.com/openedx/frontend-app-library-authoring/blob/d590aa2eb54c94b39d94f2ba12a6b458082c2e5e/.env#L19>`_

Then restart Studio and the LMS (``make dev.restart-devserver.lms dev.restart-devserver.studio``).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The testing part of the readme is still a bit thin. What steps to follow and what to look for to confirm that a) the IDA is no longer running; b) the Django app is; and c) the Django app blockstore is running as expected.

Copy link
Contributor Author

@connorhaugh connorhaugh May 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This guide doesn't care that you ever ran blockstore as a separate service. You could be running the blockstore service at the same time, but the waffle flag makes it such that it doesn't matter. This guide replaces blockstore as a service setup for local dev.
I added a part to direct the user to set up content libraries v2. That is how blockstore is used and the system's effectiveness can be tested.

You then can begin setting up the `library authoring MFE <https://github.com/openedx/frontend-app-library-authoring/>`_ to use the feature of blockstore for content libraries V2.

-------------------------------------------------------
Running and testing as a separate service
-------------------------------------------------------

Blockstore was initially developed as an independently deployed application, which runs in a separate container/proccess from the LMS. It is still possible to run blockstore that way, both in production and development.
Expand Down