You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: Move almost everything out of the README and into docs/
(This breaks many links; fixed in next commit to keep diff clean for
review.)
The readme was too large and was focused on setup, which meant that people
weren't aware of other important files such as workflow.rst. Breaking out
the contents into separate files will help ensure people actually visit
the (easier to navigate, better discoverability) Read The Docs site.
openedx-unsupported/devstack#1030
The Devstack runs as multiple containers with `Docker Compose`_ at its core.
13
-
14
-
A Devstack installation includes the following Open edX components by default:
15
-
16
-
* The Learning Management System (LMS)
17
-
* The Learning micro-frontend (A.K.A the new Courseware experience)
18
-
* Open Response Assessments (ORA2), among other LMS plug-ins.
19
-
* Open edX Studio
20
-
* Discussion Forums
21
-
* E-Commerce
22
-
* Credentials
23
-
* Notes
24
-
* Course Discovery
25
-
* Open edX Search
26
-
* A demonstration Open edX course
27
-
* The Publisher and Gradebook micro-frontends
28
-
29
-
It also includes the following extra components:
30
-
31
-
* XQueue
32
-
* The Program Console micro-frontend
33
-
* The Library Authoring micro-frontend
34
-
* edX Registrar service.
35
-
* The course-authoring micro-frontend
36
-
* The enhanced staff grader (ora-grading) micro-frontend
37
-
38
-
39
12
.. contents:: **Table of Contents:**
40
13
41
14
Where to Find Help
@@ -67,332 +40,6 @@ Notices
67
40
68
41
**NOTE:** LMS is now using MySql 5.7 by default. You have to run ``make dev.pull.lms`` and ``make dev.provision.lms`` (more details in `Getting Started`_) to fetch latest images and reprovision local copies of databases in order for an existing devstack setup to keep working.
69
42
70
-
71
-
Getting Started
72
-
---------------
73
-
74
-
Prerequisites
75
-
~~~~~~~~~~~~~
76
-
77
-
You will need to have the following installed:
78
-
79
-
- make
80
-
- Python 3.8
81
-
- Docker
82
-
83
-
This project requires **Docker 17.06+ CE**. We recommend Docker Stable, but
84
-
Docker Edge should work as well.
85
-
86
-
**NOTE:** Switching between Docker Stable and Docker Edge will remove all images and
87
-
settings. Don't forget to restore your memory setting and be prepared to
88
-
provision.
89
-
90
-
For macOS users, please use `Docker for Mac`_. Previous Mac-based tools (e.g.
91
-
boot2docker) are *not* supported. Please be aware that the `licensing terms`_ for
92
-
Docker for Mac (aka Docker Desktop) may mean that it is no longer
93
-
free for your organization's use.
94
-
95
-
Since a Docker-based devstack runs many containers,
96
-
you should configure Docker with a sufficient
97
-
amount of resources. We find that `configuring Docker for Mac`_
98
-
with a minimum of **2 CPUs, 8GB of memory, and a disk image size of 96GB**
99
-
does work.
100
-
101
-
`Docker for Windows`_ may work but has not been tested and is *not* supported.
102
-
103
-
If you are using Linux, use the ``overlay2`` storage driver, kernel version
104
-
4.0+ and *not* ``overlay``. To check which storage driver your
105
-
``docker-daemon`` uses, run the following command.
106
-
107
-
.. code:: sh
108
-
109
-
docker info | grep -i 'storage driver'
110
-
111
-
Please note
112
-
~~~~~~~~~~~
113
-
114
-
You should run all ``make`` commands described below on your local machinge, *not*
115
-
from within a Virtual Machine, as these commands are meant to stand up a VM-like environment using
116
-
Docker containers.
117
-
118
-
However, you may want to run the ``make`` commands from within a Python 3 virtual
119
-
environment, as described in `Getting Started`_. This will keep the Python packages required for Devstack separate from
120
-
the ones installed globally on your system.
121
-
122
-
Directions to setup devstack
123
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
124
-
125
-
The default devstack services can be run by following the steps below.
126
-
127
-
**Note:** This will set up a large number of services, more than you are likely to need to work with, but that's only necessary for first-time provisioning. See `Service List`_ and the `most common development workflow`_ for how to run and update devstack with just the services you need, rather than the ``large-and-slow`` default set.
128
-
129
-
#. Install the requirements inside of a `Python virtualenv`_.
130
-
131
-
.. code:: sh
132
-
133
-
make requirements
134
-
135
-
This will install docker-compose and other utilities into your virtualenv.
136
-
137
-
#. The Docker Compose file mounts a host volume for each service's executing
138
-
code. The host directory defaults to be a sibling of this directory. For
139
-
example, if this repo is cloned to ``~/workspace/devstack``, host volumes
140
-
will be expected in ``~/workspace/course-discovery``,
141
-
``~/workspace/ecommerce``, etc. These repos can be cloned with the command
142
-
below.
143
-
144
-
.. code:: sh
145
-
146
-
make dev.clone # or, `make dev.clone.https` if you don't have SSH keys set up.
147
-
148
-
You may customize where the local repositories are found by setting the
149
-
``DEVSTACK_WORKSPACE`` environment variable.
150
-
151
-
(macOS only) Share the cloned service directories in Docker, using
152
-
**Docker -> Preferences -> File Sharing** in the Docker menu.
153
-
154
-
#. Pull any changes made to the various images on which the devstack depends.
155
-
156
-
.. code:: sh
157
-
158
-
make dev.pull.large-and-slow
159
-
160
-
Note -
161
-
If you are setting up devstack to develop on Open edx named releases, see this `document on developing on named releases`_ before following this step 3.
162
-
163
-
.. _document on developing on named releases: https://edx.readthedocs.io/projects/open-edx-devstack/en/latest/developing_on_named_release_branches.html
164
-
165
-
#. Run the provision command, if you haven't already, to configure the various
166
-
services with superusers (for development without the auth service) and
167
-
tenants (for multi-tenancy).
168
-
169
-
**NOTE:** When running the provision command, databases for ecommerce and edxapp
170
-
will be dropped and recreated.
171
-
172
-
The username and password for the superusers are both ``edx``. You can access
173
-
the services directly via Django admin at the ``/admin/`` path, or login via
174
-
single sign-on at ``/login/``.
175
-
176
-
Default:
177
-
178
-
.. code:: sh
179
-
180
-
make dev.provision
181
-
182
-
This is expected to take a while, produce a lot of output from a bunch of steps, and finally end with ``Provisioning complete!``
183
-
184
-
185
-
#. Start the desired services. This command will mount the repositories under the
186
-
``DEVSTACK_WORKSPACE`` directory.
187
-
188
-
**NOTE:** it may take up to 60 seconds for the LMS to start, even after the ``dev.up.*`` command outputs ``done``.
189
-
190
-
Default:
191
-
192
-
.. code:: sh
193
-
194
-
make dev.up.large-and-slow
195
-
196
-
To stop a service, use ``make dev.stop.<service>``, and to both stop it
197
-
and remove the container (along with any changes you have made
198
-
to the filesystem in the container) use ``make dev.down.<service>``.
199
-
200
-
After the services have started, if you need shell access to one of the
201
-
services, run ``make dev.shell.<service>``. For example to access the
202
-
Catalog/Course Discovery Service, you can run:
203
-
204
-
.. code:: sh
205
-
206
-
make dev.shell.discovery
207
-
208
-
To see logs from containers running in detached mode, you can either use
209
-
"Kitematic" (available from the "Docker for Mac" menu), or by running the
210
-
following:
211
-
212
-
.. code:: sh
213
-
214
-
make dev.logs
215
-
216
-
To view the logs of a specific service container run ``make dev.logs.<service>``.
217
-
For example, to access the logs for Ecommerce, you can run:
218
-
219
-
.. code:: sh
220
-
221
-
make dev.logs.ecommerce
222
-
223
-
For information on the supported ``make`` commands, you can run:
224
-
225
-
.. code:: sh
226
-
227
-
make help
228
-
229
-
Devstack collects some basic usage metrics to help gain a better understanding of how devstack is used and to surface any potential issues on local devstack environments. To learn more, read `0003-usage-metrics.rst ADR <./docs/decisions/0003-usage-metrics.rst>`_.
230
-
231
-
This data collection is behind a consent flag, so please help devstack's maintainers by enabling metrics collection by running the following:
232
-
233
-
.. code:: sh
234
-
235
-
make metrics-opt-in
236
-
237
-
Now that you're up and running, read about the `most common development workflow`_.
238
-
239
-
Usernames and Passwords
240
-
-----------------------
241
-
242
-
The provisioning script creates a Django superuser for every service.
- A student account that you can use to access the LMS for testing honor
272
-
code certificates.
273
-
274
-
Service List
275
-
------------
276
-
277
-
These are the edX services that Devstack can provision, pull, run, attach to, etc.
278
-
Each service is accessible at ``localhost`` on a specific port.
279
-
The table below provides links to the homepage, API root, or API docs of each service,
280
-
as well as links to the repository where each service's code lives.
281
-
282
-
Most developers will be best served by working with specific combinations of these services, for example ``make dev.pull.studio`` or ``make dev.up.ecommerce``. These will pull in dependencies as needed—starting ecommerce will also start lms, and lms will pull in forums, discovery, and others. If you need multiple, they can be listed like ``make dev.up.studio+ecommerce``. After the service table below there is a list of some common combinations.
283
-
284
-
Instead of a service name or list, you can also run commands like ``make dev.provision`` / ``make dev.pull.large-and-slow`` / ``make dev.up.large-and-slow``. This is a larger list than most people will need for most of their work, and includes all of the services marked "Default" in the below table. (Some of these targets use ``large-and-slow`` in their name as a warning; others may be changed to use this over time.) However, you can change this list by modifying the ``DEFAULT_SERVICES`` option as described in the `Advanced Configuration Options`_ section.
The file ``options.mk`` sets several configuration options to default values.
373
-
For example ``DEVSTACK_WORKSPACE`` (the folder where your Git repos are expected to be)
374
-
is set to this directory's parent directory by default,
375
-
and ``DEFAULT_SERVICES`` (the list of services that are provisioned and run by default)
376
-
is set to a fairly long list of services out of the box.
377
-
For more detail, refer to the comments in the file itself.
378
-
379
-
If you're feeling brave, you can create an git-ignored overrides file called
380
-
``options.local.mk`` in the same directory and set your own values. In general,
381
-
it's good to bring down containers before changing any settings.
382
-
383
-
Changing the Docker Compose Project Name
384
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
385
-
386
-
The ``COMPOSE_PROJECT_NAME`` variable is used to define Docker namespaced volumes
387
-
and network based on this value, so changing it will give you a separate set of databases.
388
-
This is handled for you automatically by setting the ``OPENEDX_RELEASE`` environment variable in ``options.mk``
389
-
(e.g. ``COMPOSE_PROJECT_NAME=devstack-juniper.master``. Should you want to manually override this, edit the ``options.local.mk`` in the root of this repo and create the file if it does not exist. Change the devstack project name by adding the following line::
As a specific example, if ``OPENEDX_RELEASE`` is set in your environment as ``juniper.master``, then ``COMPOSE_PROJECT_NAME`` will default to ``devstack-juniper.master`` instead of ``devstack``.
0 commit comments