diff --git a/README.rst b/README.rst index 707cb7e860..f9ba7db116 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,63 @@ Open edX Devstack |Build Status| ================================ +Tahoe Devstack Docs +=================== +To run a Tahoe devstack, follow the same instructions in the "Prerequisites" section, +but use ``$ make tahoe.up`` instead of ``$ make dev.up`` to use the Tahoe specific +features and environment settings. + +Environment Files +----------------- +The environment files are now stored in the ``src/edxapp-envs`` directory near the ``edx-platform`` +so it can be edited using layman editors such as PyCharm and VSCode. + +Why? By default to edit the ``lms.env.json`` file and other JSON files, +one need to SSH into the container and edit the file. Anyway, changes don't really persist after restarting the +devstack. + +``$ tahoe.up`` command brings those files outside the container. + +Theme +----- +Tahoe themes are copied and available in the directory ``src/themes/edx-codebase-theme`` near the ``edx-platform``. + +How to Solve a Devstack Problem +------------------------------- +If something goes wrong, you can use ``$ make tahoe.reset.light`` to do a lightweight reset for the environment +files and the theme. This will remove all of the local changes in the theme, so push to GitHub first. + +If it's not fixed, use ``$ make tahoe.reset.full`` for a full reset +including removing all of the local changes that are not being pushed to GitHub. + +Other Tahoe Make Commands +------------------------- +There's a couple of other shortcuts specific for Tahoe, run ``$ make help | grep tahoe`` for a full list or checkout +the ``tahoe.mk`` file to see the source code. Currently the commands like like this: + + +.. code:: + + $ make help | grep tahoe + tahoe.chown Fix an annoying docker permission issue in both `edx-platform` and `src` + tahoe.clone-theme Clone the theme with Tahoe versions + tahoe.exec.edxapp Execute a command in both LMS and Studio (edxapp containers) + tahoe.exec.single Execute a command inside a devstack docker container + tahoe.init Make the devstack more Tahoe'ish + tahoe.init.provision-script Execute the `provision-tahoe.py` script in both of LMS and Studio + tahoe.install-pip.edxapp Install a pip package in both of LMS and Studio + tahoe.reset.light Resets the Tahoe settings including a fresh theme copy and new environment files + tahoe.restart Restarts both of LMS and Studio python processes while keeping the same container + tahoe.up Run the devstack with proper Tahoe settings, use instead of `$ make dev.up` + + +Enterprise Devstack Docs +======================== +TBD + +Open edX Docs +============= + Get up and running quickly with Open edX services. If you are seeking info on the Vagrant-based devstack, please see diff --git a/provision-tahoe.py b/provision-tahoe.py new file mode 100755 index 0000000000..56a03424de --- /dev/null +++ b/provision-tahoe.py @@ -0,0 +1,89 @@ +#!/usr/bin/env python +""" +This file belongs to `appsembler/devstack` repo, only edit that version. +Otherwise your changes will be overridden each time devstack is started. +""" +from os import makedirs, unlink +from shutil import move +from path import Path +from os import symlink +import json + + +ENVIRONMENT_FILES = [ + 'lms.env.json', + 'lms.auth.json', + 'cms.env.json', + 'cms.auth.json', +] + +SRC_DIR = Path('/edx/src/') +ENVS_DIR = SRC_DIR / 'edxapp-envs' +EDXAPP_DIR = Path('/edx/app/edxapp') + + +def update_lms_env_with_tahoe_prefs(): + """ + Apply a couple of patches to the lms.env.json files to match Tahoe needs. + + TODO: Move inside the Docker images, via Ansible. + """ + lms_env_file = ENVS_DIR / 'lms.env.json' + with open(lms_env_file, 'r') as lms_env_fd: + lms_env = json.load(lms_env_fd, encoding='utf-8') + + # Theme is enabled by default, can be disabled from within the lms.env.json file + lms_env.update({ + 'COMPREHENSIVE_THEME_DIRS': ['/edx/src/themes'], + 'DEFAULT_SITE_THEME': 'edx-theme-codebase', + 'ENABLE_COMPREHENSIVE_THEMING': True, + }) + + # Disable by default. Can be enabled from within the lms.env.json file + lms_env['FEATURES'].update({ + 'ENABLE_TIERS_APP': False, # TODO: Fix the tiers app in devstack + }) + + lms_env_encoded = json.dumps(lms_env, ensure_ascii=False, indent=4).encode('utf-8') + + with open(lms_env_file, 'w') as lms_env_fd: + lms_env_fd.write(lms_env_encoded) + + +def move_environment_files_to_host(): + """ + Move the json environment files to the host so they're editable. + """ + for filename in ENVIRONMENT_FILES: + container_path = EDXAPP_DIR / filename + src_path = ENVS_DIR / filename # The mounted directory in + + newly_copied = False + if not src_path.exists(): + if container_path.islink(): + raise Exception( + 'Unable to correctly move the environmet files, please shut down the ' + 'container `$ make down` and try again with `$ make tahoe.up`' + ) + + move(container_path, src_path) + newly_copied = True + + if src_path.exists(): + if container_path.exists(): + container_path.unlink() + + symlink(src_path, container_path) + + if newly_copied and filename == 'lms.env.json': + update_lms_env_with_tahoe_prefs() + + +def main(): + if not ENVS_DIR.exists(): + makedirs(ENVS_DIR) + + move_environment_files_to_host() + + +main() diff --git a/tahoe.mk b/tahoe.mk new file mode 100644 index 0000000000..7334420eae --- /dev/null +++ b/tahoe.mk @@ -0,0 +1,71 @@ +DEVSTACK_WORKSPACE ?= .. +THEMES_DIR = $(DEVSTACK_WORKSPACE)/src/themes +CUSTOMER_THEME_DIR = $(THEMES_DIR)/edx-theme-codebase/customer_specific + +tahoe.exec.single: ## Execute a command inside a devstack docker container + docker exec -t edx.devstack.$(SERVICE) \ + bash -c 'source /edx/app/edxapp/edxapp_env && cd /edx/app/edxapp/edx-platform/ && $(COMMAND)' + +tahoe.exec.edxapp: ## Execute a command in both LMS and Studio (edxapp containers) + make COMMAND='$(COMMAND)' SERVICE=lms tahoe.exec.single + make COMMAND='$(COMMAND)' SERVICE=studio tahoe.exec.single + +tahoe.install-pip.edxapp: ## Install a pip package in both of LMS and Studio + make COMMAND='pip install $(PACKAGE)' SERVICE=lms tahoe.exec.single + make COMMAND='pip install $(PACKAGE)' SERVICE=studio tahoe.exec.single + +tahoe.chown: ## Fix an annoying docker permission issue in both `edx-platform` and `src` + sudo chown -R $(USER):$(USER) $(DEVSTACK_WORKSPACE)/edx-platform/ + sudo chown -R $(USER):$(USER) $(DEVSTACK_WORKSPACE)/src/ + +tahoe.theme.compile: ## Compile the static assets of the theme + make COMMAND='make requirements' tahoe.exec.edxapp + make lms-static + make studio-static + +tahoe.theme.clone: ## Clone the theme with Tahoe branches + make tahoe.chown + rm -rf $(THEMES_DIR) + + git clone git@github.com:appsembler/edx-theme-codebase.git $(THEMES_DIR)/edx-theme-codebase + cd $(THEMES_DIR)/edx-theme-codebase && git checkout hawthorn/master + + git clone git@github.com:appsembler/edx-theme-customers.git $(CUSTOMER_THEME_DIR) + cd $(CUSTOMER_THEME_DIR) && git checkout hawthorn/amc + + make tahoe.chown + +tahoe.init.provision-script: ## Execute the `provision-tahoe.py` script in both of LMS and Studio + cat $(DEVSTACK_WORKSPACE)/devstack/provision-tahoe.py > $(DEVSTACK_WORKSPACE)/src/provision-tahoe.py + make COMMAND='python /edx/src/provision-tahoe.py' tahoe.exec.edxapp + rm $(DEVSTACK_WORKSPACE)/src/provision-tahoe.py + +tahoe.init: ## Make the devstack more Tahoe'ish + make tahoe.init.provision-script + # TODO: Install within the Tahoe Open edX images + make PACKAGE='git+https://github.com/appsembler/edx-organizations.git@0.4.10-appsembler3' tahoe.install-pip.edxapp + make tahoe.restart || true + +tahoe.up: ## Run the devstack with proper Tahoe settings, use instead of `$ make dev.up` + make tahoe.chown + make dev.up + @sleep 1 + make tahoe.init + test -d $(CUSTOMER_THEME_DIR) || (make tahoe.theme.clone && tahoe.theme.compile) + make tahoe.chown + +tahoe.reset.light: ## Resets the Tahoe settings including a fresh theme copy and new environment files. + make down + sudo rm -rf $(DEVSTACK_WORKSPACE)/src/edxapp-envs + make tahoe.theme.clone + @sleep 1 + make tahoe.up + make tahoe.theme.compile + +tahoe.reset.full: ## Does a full reset for everything known to devstack. Will loose all git and database changes. + make dev.reset + make tahoe.reset.light + +tahoe.restart: ## Restarts both of LMS and Studio python processes while keeping the same container + make lms-restart + make studio-restart