### Install and Enable a Tutor Plugin

Source: https://github.com/overhangio/tutor/blob/release/docs/plugins/index.rst

Steps to install a new plugin, enable it, and reconfigure the platform.

```bash
pip install tutor-myapp
tutor plugins enable myapp
tutor local launch
```

--------------------------------

### Start Tutor Platform with Data

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/datamigration.rst

Start the Tutor platform on the new server with the migrated data. The -d flag is used to start in detached mode.

```bash
tutor local start -d
```

--------------------------------

### Install a Specific Tutor Plugin

Source: https://github.com/overhangio/tutor/blob/release/docs/plugins/index.rst

Command to install a plugin, such as the 'notes' plugin, from an index.

```bash
tutor plugins install notes
```

--------------------------------

### Install and Enable a Tutor Plugin

Source: https://context7.com/overhangio/tutor/llms.txt

Steps to install a plugin by placing its Python file in the plugins root, enabling it via the CLI, and verifying its configuration.

```bash
# Auto-discovered if placed in the plugins root
ls "$(tutor plugins printroot)/myplugin.py"

# Enable it
tutor plugins enable myplugin

# Verify configuration
tutor config printvalue MYPLUGIN_HOST
# → myservice.local.openedx.io

# Build the image
tutor images build myservice

# Run full init
tutor local do init --limit=myservice

# Build and start
tutor local launch
```

--------------------------------

### Download and Install Tutor Binary

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/download/binary.rst

Use these commands to download the Tutor binary and place it in your system's PATH. Ensure you have sudo privileges for installation.

```bash
sudo curl -L "https://github.com/overhangio/tutor/releases/download/v|tutor_version|/tutor-$(uname -s)_$(uname -m)" -o /usr/local/bin/tutor
```

```bash
sudo chmod 0755 /usr/local/bin/tutor
```

--------------------------------

### List Installed Tutor Plugins

Source: https://github.com/overhangio/tutor/blob/release/docs/plugins/index.rst

Command to display all currently installed Tutor plugins.

```bash
tutor plugins list
```

--------------------------------

### Start Development Environment (Detached)

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/openedx.rst

Start the development environment containers in detached mode (background). This is a faster startup than 'launch' after the initial setup.

```bash
tutor dev start -d
```

--------------------------------

### Save and Render Tutor Configuration

Source: https://context7.com/overhangio/tutor/llms.txt

Manage Tutor configuration with `tutor config save`. Use `--interactive` for a guided setup, `--set` to modify individual keys, `--append` or `--remove` for list settings, and `--unset` to revert to defaults. Multiple operations can be chained. `tutor config printvalue` displays a specific setting, `tutor config edit` opens the editor, and `tutor config printroot` shows the project directory.

```bash
# Interactive questionnaire
tutor config save --interactive

# Set individual keys non-interactively
tutor config save --set LMS_HOST=lms.myplatform.org
tutor config save --set CMS_HOST=studio.myplatform.org
tutor config save --set ENABLE_HTTPS=true

# Append to a list setting (idempotent)
tutor config save --append PLUGINS=myplugin

# Remove from a list setting
tutor config save --remove PLUGINS=myplugin

# Unset a key (reverts to default)
tutor config save --unset MY_CUSTOM_KEY

# Multiple operations in one call
tutor config save \
  --set LMS_HOST=lms.example.com \
  --set ENABLE_HTTPS=true \
  --set PLATFORM_NAME="My Open edX"

# Print a single value
tutor config printvalue LMS_HOST
# → lms.example.com

# Open config.yml in the system editor
tutor config edit

# Print the project root directory
tutor config printroot
# → /home/user/.local/share/tutor
```

--------------------------------

### Test Docker Installation

Source: https://github.com/overhangio/tutor/blob/release/docs/troubleshooting.rst

Before running Tutor, ensure your Docker installation is working correctly by running this command. If it fails, you likely have a Docker configuration or permission issue.

```bash
docker run --rm hello-world
```

--------------------------------

### Install Documentation Requirements

Source: https://github.com/overhangio/tutor/blob/release/docs/tutor.rst

Install the Python packages required for building the project's documentation.

```bash
pip install -r requirements/docs.txt
```

--------------------------------

### Create and use a local plugin index for development

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/indexes.rst

This workflow demonstrates setting up a local directory for plugin indexes, adding local plugins via editable installs, and then installing them. Local indexes have higher priority.

```bash
# Create the plugin index directory
mkdir -p ~/localindex/ulmo/
# Edit the index
vim ~/localindex/ulmo/plugins.yml

- name: myplugin1
  src: -e /path/to/tutor-myplugin1
- name: myplugin2
  src: -e /path/to/tutor-myplugin2

# Then add the index:
tutor plugins index add ~/localindex/

# Install the plugins:
tutor plugins install myplugin1 myplugin2

# Re-install all plugins:
tutor plugins upgrade all
```

--------------------------------

### Import Open edX Demo Course

Source: https://github.com/overhangio/tutor/blob/release/docs/local.rst

Run this command after a fresh installation to import the demo course into your platform.

```bash
tutor local do importdemocourse
```

--------------------------------

### Start Development Environment (Attached)

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/openedx.rst

Start the development environment containers in attached mode (foreground). Logs will be visible in the current terminal.

```bash
tutor dev start
```

--------------------------------

### Build and Start Openedx Image

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/edx-platform.rst

Build the 'openedx' Docker image and start it in detached mode for production-like environments.

```bash
tutor images build openedx
tutor local start -d
```

--------------------------------

### Start Local Development Server

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/themes.rst

Launch the local development server for the LMS. The LMS will then be accessible at http://local.openedx.io:8000.

```bash
tutor dev start lms
```

--------------------------------

### Launch Tutor Platform

Source: https://context7.com/overhangio/tutor/llms.txt

Use `tutor local launch` for initial platform setup. It handles configuration, image building, and database initialization. Use `--non-interactive` and `--pullimages` for automated or CI environments. `--skip-build` can be used if images are already present.

```bash
# Interactive first-time setup
tutor local launch

# Fully automated / CI setup (no prompts, pull latest images first)
tutor local launch --non-interactive --pullimages

# Skip image build if images are already present
tutor local launch --non-interactive --skip-build

# Expected output (abbreviated):
# ============================== Interactive platform configuration ==============================
# ...
# ============================== Building Docker images ==============================
# ...
# ============================== Starting the platform in detached mode ==============================
# ...
# ============================== Database creation and migrations ==============================
# ...
# The platform is now running and can be accessed at the following urls:
#     http://local.openedx.io
#     http://studio.local.openedx.io
```

--------------------------------

### Install Tutor Main from Source

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/main.rst

Clone the Tutor repository's main branch and install it in editable mode. This is recommended for developers needing the latest features. Ensure you are in a Python virtual environment.

```bash
git clone --branch=main https://github.com/overhangio/tutor.git
pip install -e "./tutor[full]"
```

--------------------------------

### Install Tutor from Source

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Clones the Tutor repository and installs it in editable mode using pip. This method is suitable for inspecting or modifying the source code.

```bash
git clone https://github.com/overhangio/tutor
cd tutor
pip install -e .
```

--------------------------------

### Install Tutor for Open edX Teak Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 20 with full features for the Open edX Teak release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=20.0.0,<21.0.0'
```

--------------------------------

### Start Caddy Load Balancer

Source: https://github.com/overhangio/tutor/blob/release/docs/k8s.rst

Start the Caddy load balancer service to expose the Caddy deployment. This is necessary for generating SSL/TLS certificates at runtime.

```bash
tutor k8s start caddy
```

--------------------------------

### Manage Plugins and Configuration with Tutor CLI

Source: https://context7.com/overhangio/tutor/llms.txt

Commands to list installed plugins, enable a specific plugin, and print configuration values. Useful for verifying plugin status and settings.

```bash
tutor plugins list
# → myplugin   installed   /home/user/.local/share/tutor-plugins/myplugin.yml

tutor plugins enable myplugin
tutor config printvalue MYPLUGIN_GREETING
# → Hello
```

--------------------------------

### Install Development Requirements

Source: https://github.com/overhangio/tutor/blob/release/docs/tutor.rst

Install the necessary Python packages for development using the provided requirements file.

```bash
pip install -r requirements/dev.txt
```

--------------------------------

### Manage Tutor Plugins

Source: https://context7.com/overhangio/tutor/llms.txt

Commands for listing, enabling, disabling, searching, installing, and upgrading Tutor plugins. Use `list --enabled` to see active plugins. Installation supports local files and URLs.

```bash
tutor plugins list --enabled
```

```bash
tutor plugins enable mfe
```

```bash
tutor plugins disable mfe
```

```bash
tutor plugins disable all
```

```bash
tutor plugins printroot
```

```bash
tutor plugins search credentials
```

```bash
tutor plugins search ""          # list all indexed plugins
```

```bash
tutor plugins show mfe
```

```bash
tutor plugins install mfe
```

```bash
tutor plugins install /path/to/myplugin.py
```

```bash
tutor plugins install https://example.com/myplugin.py
```

```bash
tutor plugins upgrade all
```

--------------------------------

### Install Tutor for Open edX Quince Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 17 with full features for the Open edX Quince release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=17.0.0,<18.0.0'
```

--------------------------------

### Tutor CLI Mode-Specific Subcommands

Source: https://github.com/overhangio/tutor/blob/release/docs/cli.rst

Examples of common subcommands used within different deployment modes (local, k8s, dev) to manage Open edX instances.

```bash
tutor local logs  # View logs of a local deployment.
```

```bash
tutor k8s logs    # View logs of a Kubernetes-managed deployment.
```

```bash
tutor dev logs    # View logs of a development platform.
```

--------------------------------

### Start Open edX Containers

Source: https://github.com/overhangio/tutor/blob/release/docs/local.rst

Launch the Docker containers for your Open edX platform. Access LMS and Studio via the configured domain names.

```bash
tutor local start
```

--------------------------------

### Install Tutor for Open edX Olive Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 15 with full features for the Open edX Olive release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=15.0.0,<16.0.0'
```

--------------------------------

### Install Tutor for Open edX Ulmo Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 21 with full features for the Open edX Ulmo release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=21.0.0,<22.0.0'
```

--------------------------------

### Install Tutor for Open edX Sumac Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 19 with full features for the Open edX Sumac release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=19.0.0,<20.0.0'
```

--------------------------------

### Transfer Platform Data with rsync

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/datamigration.rst

Transfer the configuration, environment, and platform data from the source server to the destination server using rsync. Ensure Tutor is installed on both servers with the same version.

```bash
sudo rsync -avr "$(tutor config printroot)/" username@server2:/tmp/tutor/
```

--------------------------------

### Install a Custom Plugin for Tutor Main

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/main.rst

Clone a custom plugin's main branch and install it in editable mode. This is useful when developing or using custom plugins with Tutor Main.

```bash
git clone --branch=main https://github.com/myorganization/tutor-contrib-myplugin.git
pip install -e ./tutor-contrib-myplugin
```

--------------------------------

### Install Tutor for Open edX Nutmeg Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 14 with full features for the Open edX Nutmeg release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=14.0.0,<15.0.0'
```

--------------------------------

### Install Tutor for Open edX Koa Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 11 with full features for the Open edX Koa release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=11.0.0,<12.0.0'
```

--------------------------------

### Install Tutor for Open edX Maple Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 13 with full features for the Open edX Maple release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=13.0.0,<14.0.0'
```

--------------------------------

### Manage Tutor Platform Lifecycle

Source: https://context7.com/overhangio/tutor/llms.txt

Control the running state of the Docker Compose platform using `tutor local start`, `stop`, `restart`, and `reboot`. `start --detach` runs services in the background. Specific services can be targeted. `restart` reloads settings, while `reboot` performs a full stop/start.

```bash
# Start all services detached
tutor local start --detach

# Start only specific services
tutor local start lms cms

# Start and rebuild images
tutor local start --build

# Attach to a single service (useful for debugging)
tutor local start lms   # attaches stdin/stdout

# Stop all services
tutor local stop

# Stop only mysql and redis
tutor local stop mysql redis

# Reload settings without downtime
tutor local restart openedx   # restarts lms, cms, lms-worker, cms-worker

# Full stop + start cycle
tutor local reboot --detach
```

--------------------------------

### Install Plugin from Private Git Repository

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/indexes.rst

Install a plugin directly from a private Git repository. This format is compatible with pip's requirements file syntax.

```yaml
- name: myprivateplugin2
  src: -e git+https://git.mycompany.com/tutor-contrib-myplugin2.git
```

--------------------------------

### List Installed Tutor Plugins

Source: https://github.com/overhangio/tutor/blob/release/docs/uninstallation.rst

To manage Tutor plugins, first list all installed plugins that contain 'tutor' in their name. This helps identify which plugins you might want to uninstall.

```bash
# You can get a list of the installed plugins:
pip freeze | grep tutor
```

--------------------------------

### Install Tutor for Open edX Lilac Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 12 with full features for the Open edX Lilac release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=12.0.0,<13.0.0'
```

--------------------------------

### Start Podman Service and Set DOCKER_HOST

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/podman.rst

Enable the Podman socket for docker-compose compatibility, especially for rootless containers. This involves starting the podman service and exporting the DOCKER_HOST environment variable. For persistence, add the export command to your bashrc.

```bash
# To start the podman service
$ systemctl --user start podman.service
```

```bash
# To set the DOCKER_HOST environment variable
$ export DOCKER_HOST="unix://$XDG_RUNTIME_DIR/podman/podman.sock"
```

--------------------------------

### Install Tutor for Open edX Redwood Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 18 with full features for the Open edX Redwood release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=18.0.0,<19.0.0'
```

--------------------------------

### Install Tutor for Open edX Palm Release

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs Tutor version 16 with full features for the Open edX Palm release. Ensures compatibility between Open edX and Tutor versions.

```bash
pip install 'tutor[full]>=16.0.0,<17.0.0'
```

--------------------------------

### Manual Bind-Mount with Docker Volume Option

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/openedx.rst

For mounting existing local directories (like a cloned repository) into a container, use the `tutor dev run --volume` command. Be aware of limitations with multiple containers and `start` commands; prefer `persistent_mounts` when possible.

```bash
tutor dev run --volume=/path/to/edx-platform:/openedx/edx-platform lms bash
```

--------------------------------

### Install a Custom Theme

Source: https://github.com/overhangio/tutor/blob/release/docs/configuration.rst

Clone your custom theme into the themes directory and rebuild the openedx Docker image. After rebuilding, enable the theme using the `settheme` command and restart services.

```bash
git clone https://github.com/me/myopenedxtheme.git \
  "$(tutor config printroot)/env/build/openedx/themes/myopenedxtheme"
tutor images build openedx
```

--------------------------------

### Plugin source options

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/indexes.rst

The 'src' field can specify a PyPI package, a local Python file, or a URL to a Python file. Examples include direct PyPI installs, version-specific installs, private indexes, remote Git repositories, and local editable packages.

```yaml
# Pypi package
src: tutor-mfe
```

```yaml
# Pypi package with version specification
src: tutor-mfe>=42.0.0,<43.0.0
```

```yaml
# Python package from a private index
src: |
    --index-url=https://pip.mymirror.org
    my-plugin>=10.0
```

```yaml
# Remote git repository
src: -e git+https://github.com/myusername/tutor-contrib-myplugin@v27.0.0#egg=tutor-contrib-myplugin
```

```yaml
# Local editable package
src: -e /path/to/my/plugin
```

--------------------------------

### Build 'openedx' image with custom EDX_PLATFORM_VERSION

Source: https://github.com/overhangio/tutor/blob/release/docs/configuration.rst

Specify build-time arguments when building the 'openedx' Docker image. This example sets a custom EDX_PLATFORM_VERSION.

```bash
tutor images build -a EDX_PLATFORM_VERSION=customsha1 openedx
```

--------------------------------

### Upgrade All Tutor Plugins

Source: https://github.com/overhangio/tutor/blob/release/docs/plugins/index.rst

Command to upgrade all installed Tutor plugins to their latest versions.

```bash
tutor plugins upgrade all
```

--------------------------------

### Manage plugins with `tutor plugins`

Source: https://context7.com/overhangio/tutor/llms.txt

Control the lifecycle of plugins, including discovery, installation, enabling, disabling, and querying their status and version. This command helps manage extensions to the Tutor environment.

```bash
# List all installed plugins with status and version
tutor plugins list
```

--------------------------------

### Define Dockerfile for Custom Image

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/creating.rst

Create a Dockerfile in the specified build directory for a new Docker image. This example uses a Debian slim image and a simple command.

```docker
FROM docker.io/debian:bullseye-slim
CMD echo "what an awesome plugin!"
```

--------------------------------

### Uninstall Tutor (Source Installation)

Source: https://github.com/overhangio/tutor/blob/release/docs/uninstallation.rst

If you installed Tutor from source using pip, use this command to uninstall it.

```bash
# If you installed tutor from source
pip uninstall tutor
```

--------------------------------

### Initialize Services

Source: https://github.com/overhangio/tutor/blob/release/docs/local.rst

Perform a one-time initialization of all applications within a running platform, including database table creation and migrations.

```bash
tutor local do init
```

--------------------------------

### Launch Development Environment with Image Pull

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/openedx.rst

Perform a full development environment setup, ensuring container images are up-to-date by pulling them. This command is idempotent and safe to run repeatedly.

```bash
tutor dev launch --pullimages
```

--------------------------------

### Uninstall Tutor (Binary Installation)

Source: https://github.com/overhangio/tutor/blob/release/docs/uninstallation.rst

If you installed Tutor using the pre-compiled binary, use this command to remove the Tutor executable from your system.

```bash
# If you downloaded the tutor binary
sudo rm /usr/local/bin/tutor
```

--------------------------------

### Perform release-specific upgrade tasks with `tutor local upgrade`

Source: https://context7.com/overhangio/tutor/llms.txt

Execute data migrations between named Open edX releases. Remember to run `launch` afterward to complete the upgrade process.

```bash
# Upgrade from the Sumac release to the current release
tutor local upgrade --from=sumac
```

```bash
# List recognised release names (shown in --help)
tutor local upgrade --help
```

--------------------------------

### Development mode operations with `tutor dev`

Source: https://context7.com/overhangio/tutor/llms.txt

Utilize development Docker images and bind-mounts for local development. This mode runs separately from the local platform, allowing for isolated development workflows. Includes commands for launching, starting services, running tests, and managing host services.

```bash
# Full dev setup with a local edx-platform checkout
tutor dev launch --non-interactive
```

```bash
# Bind-mount a local fork of edx-platform
tutor mounts add /path/to/edx-platform
tutor dev launch
```

```bash
# Run the LMS dev server
tutor dev start lms
```

```bash
# Run tests inside the openedx-dev image
tutor dev run lms pytest openedx/tests/
```

```bash
# List available host services and their status
tutor dev hosts
```

--------------------------------

### Launch Tutor After Upgrade

Source: https://github.com/overhangio/tutor/blob/release/docs/upgrading.rst

Run the 'launch' command after upgrading Tutor. Choose the appropriate command based on your deployment target.

```bash
tutor local launch
```

```bash
tutor dev launch
```

```bash
tutor k8s launch
```

--------------------------------

### Install Tutor Python Package Dependencies

Source: https://github.com/overhangio/tutor/blob/release/docs/gettingstarted/installation.rst

Installs necessary system packages for building the Tutor Python package. Requires Python >= 3.9 with pip.

```bash
sudo apt install python3 python3-pip libyaml-dev
```

--------------------------------

### Launch Open edX Platform Locally with Tutor

Source: https://github.com/overhangio/tutor/blob/release/docs/howtutorworks.rst

Executes the command to launch the Open edX platform using Tutor's local environment. Tutor abstracts the underlying Docker Compose commands.

```bash
tutor local launch
```

--------------------------------

### Deploy and Manage Tutor on Kubernetes

Source: https://context7.com/overhangio/tutor/llms.txt

Commands for deploying and managing Tutor applications on Kubernetes. Sub-commands mirror `tutor local` functionality. Use `launch` for interactive deployment and `k8s exec` to run commands in pods.

```bash
# Launch on Kubernetes (interactive)
tutor k8s launch
```

```bash
# Start all services
tutor k8s start
```

```bash
# Run the init job
tutor k8s do init
```

```bash
# Execute a command in a running pod
tutor k8s exec lms ./manage.py lms shell
```

```bash
# View pod logs
tutor k8s logs --follow lms
```

```bash
# Apply kustomization manifests directly
tutor k8s apply
```

```bash
# Upgrade from a previous release
tutor k8s upgrade --from=sumac
```

```bash
# Wait for a pod to be ready
tutor k8s wait lms
```

```bash
# Delete all Kubernetes resources
tutor k8s delete
```

```bash
# Delete without removing the namespace
tutor k8s delete --no-delete-namespace
```

--------------------------------

### Install Plugin from Private Pip Index

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/indexes.rst

Install a plugin using a private pip index. This format is compatible with pip's requirements file syntax.

```yaml
- name: myprivateplugin1
  src: |
    --index-url=https://my-pip-index.mycompany.com/
    tutor-contrib-myprivateplugin
```

--------------------------------

### Set Tutor Configuration Parameters from Environment Variables

Source: https://github.com/overhangio/tutor/blob/release/docs/configuration.rst

Configure Tutor by setting system environment variables. Parameters are prefixed with 'TUTOR_' and follow the format TUTOR_PARAM1=VALUE1.

```bash
export TUTOR_PARAM1=VALUE1
```

--------------------------------

### Version Control Comment Example

Source: https://github.com/overhangio/tutor/blob/release/docs/tutor.rst

Example of a comment used in source code to indicate a feature or code that will be removed after a specific major version. This aids in tracking upcoming deprecations.

```python
# This has been replaced with SOME_NEW_HOOK (REMOVE-AFTER-V25).
SOME_OLD_HOOK = Filter()
```

--------------------------------

### Generate HTML Documentation

Source: https://github.com/overhangio/tutor/blob/release/docs/tutor.rst

Build the HTML version of the project's documentation. Navigate to the docs directory before running.

```bash
cd docs/
make html
```

--------------------------------

### Verify and Rebuild Docker Image

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/edx-platform.rst

After mounting a Python package, verify the mounts with `tutor mounts list` and then rebuild the `openedx-dev` Docker image to incorporate your local changes.

```bash
$ tutor mounts list
- name: /my/workspace/edx-ora2
build_mounts:
- image: openedx
    context: mnt-edx-ora2
- image: openedx-dev
    context: mnt-edx-ora2
compose_mounts:
- service: lms
    container_path: /mnt/edx-ora2
- service: cms
    container_path: /mnt/edx-ora2
- service: lms-worker
    container_path: /mnt/edx-ora2
- service: cms-worker
    container_path: /mnt/edx-ora2
- service: lms-job
    container_path: /mnt/edx-ora2
- service: cms-job
    container_path: /mnt/edx-ora2

tutor images build openedx-dev
```

--------------------------------

### Clone edx-platform Repository

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/edx-platform.rst

Clone the edx-platform repository to your local workspace. This is the first step before mounting it with Tutor.

```bash
cd /my/workspace/edx-platform
git clone https://github.com/openedx/edx-platform .
```

--------------------------------

### Launch Tutor with Automatic Image Rebuild

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/openedx.rst

Automatically rebuilds the openedx-dev Docker image on each launch. This is an alternative to manual rebuilding.

```bash
tutor dev launch
```

--------------------------------

### Migrate Data for v1/v2 Upgrade

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/oldreleases.rst

Create the Tutor project root and move configuration and data files when migrating from Tutor v1 or v2.

```bash
mkdir -p "$(tutor config printroot)"
mv config.json data/ "$(tutor config printroot)"
```

--------------------------------

### List all available patches

Source: https://github.com/overhangio/tutor/blob/release/docs/reference/patches/index.rst

Execute this command to list all available patches within the Tutor configuration. This is useful for an overview of patch options.

```bash
tutor config patches list
```

--------------------------------

### Mount edx-platform Repository with Tutor

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/edx-platform.rst

Use the `tutor mounts add` command to mount your local edx-platform repository. This makes your local changes available in Docker containers during build and runtime.

```bash
tutor mounts add /my/workspace/edx-platform
```

--------------------------------

### List Tutor Local Commands

Source: https://github.com/overhangio/tutor/blob/release/docs/local.rst

View all available local commands for Tutor by running the --help flag.

```bash
tutor local --help
```

--------------------------------

### Enable Tutor Plugin

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/creating.rst

Enable your newly created plugin using the 'tutor plugins enable' command. This action saves the configuration and generates the environment.

```bash
tutor plugins enable myplugin
```

--------------------------------

### View Tutor Kubernetes Commands

Source: https://github.com/overhangio/tutor/blob/release/docs/k8s.rst

Displays all available Tutor commands for Kubernetes operations.

```bash
tutor k8s -h
```

--------------------------------

### Enable a Custom Theme

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/themes.rst

Activate your newly developed or copied theme within the running LMS. Replace 'mythemename' with the actual name of your theme directory.

```bash
tutor dev do settheme mythemename
```

--------------------------------

### Get Enabled Plugins

Source: https://context7.com/overhangio/tutor/llms.txt

Retrieves a list of currently enabled plugin names from the configuration.

```python
# Get currently-enabled plugin names
enabled = tutor_config.get_enabled_plugins(config)
```

--------------------------------

### Save Configuration Setting

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/creating.rst

Modify and save a Tutor configuration setting, for example, to enable or disable a feature.

```bash
$ tutor config save --set MYPLUGIN_PLATFORM_IS_PUBLIC=True
```

--------------------------------

### Create Plugin Root Directory

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/creating.rst

Use this command to create the root directory for your Tutor plugins if it doesn't already exist.

```bash
mkdir -p "$(tutor plugins printroot)"
```

--------------------------------

### Execute commands in containers with `tutor local run` and `tutor local exec`

Source: https://context7.com/overhangio/tutor/llms.txt

Use `run` to spawn a fresh container or `exec` to run commands in an already running container. Supports interactive shells, management commands, and environment variable overrides.

```bash
# Open an interactive shell in the LMS container
tutor local run lms bash
```

```bash
# Run a Django management command
tutor local run lms ./manage.py lms shell
```

```bash
# Create a superuser non-interactively
tutor local run lms ./manage.py lms createsuperuser \
  --username admin --email admin@example.com --no-input
```

```bash
# Execute in a running container (no new container)
tutor local exec lms ./manage.py lms show_urls | head -20
```

```bash
# Run with extra environment variables
tutor local run -e DEBUG=1 lms bash
```

--------------------------------

### Get Config File Path

Source: https://context7.com/overhangio/tutor/llms.txt

Retrieves the absolute path to the config.yml file within the specified root directory.

```python
# Get the path to config.yml
path = tutor_config.config_path(root)
```

--------------------------------

### View Tutor Environment Files

Source: https://github.com/overhangio/tutor/blob/release/docs/configuration.rst

List the files within the Tutor environment directory. This directory contains all files required to manage an Open edX platform, such as Dockerfiles and settings files.

```bash
ls "$(tutor config printroot)/env"
```

--------------------------------

### Attach Debugger to LMS or CMS Container

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/edx-platform.rst

Start the development server for a specific service (LMS or CMS) to attach a debugger.

```bash
tutor dev start lms
```

```bash
tutor dev start cms
```

--------------------------------

### Start Open edX Containers in Detached Mode

Source: https://github.com/overhangio/tutor/blob/release/docs/local.rst

Run the Open edX services in the background. Use this for production environments.

```bash
tutor local start --detach
```

--------------------------------

### Upgrade Tutor with Specific Release

Source: https://github.com/overhangio/tutor/blob/release/docs/upgrading.rst

When upgrading to a new Open edX release, especially if rebuilding Docker images, use the 'upgrade' command with the '--from' flag to specify the previous release.

```bash
tutor config save
tutor images build all
tutor local upgrade --from=teak
tutor local launch
```

--------------------------------

### Stop and Start Kubernetes Services

Source: https://github.com/overhangio/tutor/blob/release/docs/k8s.rst

Stops all services on Kubernetes and then restarts and reconfigures them. This process deletes and re-creates non-persisting data.

```bash
tutor k8s stop
tutor k8s start
```

--------------------------------

### Add extra PIP requirements

Source: https://github.com/overhangio/tutor/blob/release/docs/configuration.rst

Append extra Python package requirements to the configuration. These will be installed in the 'openedx' Docker image.

```bash
tutor config save --append OPENEDX_EXTRA_PIP_REQUIREMENTS=git+https://github.com/open-craft/xblock-poll.git
```

--------------------------------

### Navigate to Tutor Root and List Files

Source: https://github.com/overhangio/tutor/blob/release/docs/howtutorworks.rst

Changes the current directory to Tutor's root directory and lists its contents. This is useful for inspecting generated configuration and environment files.

```bash
cd "$(tutor config printroot)"
ls
```

--------------------------------

### Check Plugin Dependencies

Source: https://context7.com/overhangio/tutor/llms.txt

Use this hook to check if other plugins are enabled at runtime. This example warns if the 'mfe' plugin is not enabled.

```python
# Check whether another plugin is enabled at runtime.
@hooks.Filters.PLUGINS_LOADED.add()
def check_dependency(plugins):
    if "mfe" not in plugins:
        print("Warning: mfe plugin is not enabled")
    return plugins
```

--------------------------------

### Customize Celery Worker Concurrency

Source: https://context7.com/overhangio/tutor/llms.txt

Customize the Celery worker startup parameters. This example increases the concurrency to 4 for the LMS worker.

```python
# Customise the Celery worker startup parameters.
@hooks.Filters.LMS_WORKER_COMMAND.add()
def set_lms_worker_concurrency(command):
    command += ["--concurrency", "4"]
    return command
```

--------------------------------

### Apply Common Settings Patch

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/creating.rst

Use patches to modify common settings, such as Django `FEATURES`. This example shows how to set `ALLOW_PUBLIC_ACCOUNT_CREATION`.

```python
hooks.Filters.ENV_PATCHES.add_item(("openedx-lms-common-settings", "FEATURES['ALLOW_PUBLIC_ACCOUNT_CREATION'] = False"))
```

```python
hooks.Filters.ENV_PATCHES.add_item(("openedx-lms-common-settings", "FEATURES['ALLOW_PUBLIC_ACCOUNT_CREATION'] = {% if MYPLUGIN_PLATFORM_IS_PUBLIC %}True{% else %}False{% endif %}"))
```

--------------------------------

### Checkout Python Package Version

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/edx-platform.rst

Checkout the specific version tag or branch of the Python package that is used by your edx-platform installation. This ensures compatibility.

```bash
git checkout <my-version-tag-or-branch>
```

--------------------------------

### Generate Tutor Executable Binary

Source: https://github.com/overhangio/tutor/blob/release/docs/tutor.rst

Build a self-contained executable binary for the Tutor application.

```bash
make bundle
```

--------------------------------

### Get Current Configuration Defaults

Source: https://context7.com/overhangio/tutor/llms.txt

Apply a filter manually to retrieve the current configuration defaults. This is useful for debugging or inspecting the configuration state.

```python
# Apply a filter manually to get the current value
current_defaults = hooks.Filters.CONFIG_DEFAULTS.apply([])
print(current_defaults)  # list of (key, value) tuples
```

--------------------------------

### List Tutor Mounts

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/edx-platform.rst

View the current mounts configured in Tutor. This command helps verify that your local repository has been successfully mounted.

```bash
$ tutor mounts list
- name: /home/data/regis/projets/overhang/repos/edx/edx-platform
build_mounts:
- image: openedx
    context: edx-platform
- image: openedx-dev
    context: edx-platform
compose_mounts:
- service: lms
    container_path: /openedx/edx-platform
- service: cms
    container_path: /openedx/edx-platform
- service: lms-worker
    container_path: /openedx/edx-platform
- service: cms-worker
    container_path: /openedx/edx-platform
- service: lms-job
    container_path: /openedx/edx-platform
- service: cms-job
    container_path: /openedx/edx-platform
```

--------------------------------

### Inject AWS Secrets with boto3

Source: https://context7.com/overhangio/tutor/llms.txt

Use this hook to fetch secrets from AWS Secrets Manager and inject them as environment variables. Requires boto3 to be installed.

```python
import boto3
@hooks.Filters.CONFIG_USER.add()
def inject_aws_secret(items):
    client = boto3.client("secretsmanager")
    secret = client.get_secret_value(SecretId="tutor/db-password")
    items.append(("MYSQL_ROOT_PASSWORD", secret["SecretString"]))
    return items
```

--------------------------------

### Initialization Script for MyPlugin

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/creating.rst

A sample shell script for initializing your plugin. This script is executed during the CLI initialization tasks.

```bash
echo "initialising my plugin..."
echo "done!"
```

--------------------------------

### Register Custom Jinja2 Filters

Source: https://context7.com/overhangio/tutor/llms.txt

Register custom Jinja2 filters that can be used within Tutor's templates. This example shows a base64 encoding filter.

```python
# Register custom Jinja2 filters available in all templates.
def base64_encode(value: str) -> str:
    import base64
    return base64.b64encode(value.encode()).decode()

hooks.Filters.ENV_TEMPLATE_FILTERS.add_item(("base64encode", base64_encode))
```

--------------------------------

### Clone Tutor Repository

Source: https://github.com/overhangio/tutor/blob/release/docs/tutor.rst

Clone the Tutor repository to your local machine and navigate into the project directory.

```bash
git clone https://github.com/overhangio/tutor.git
cd tutor/
```

--------------------------------

### Access Minikube Dashboard

Source: https://github.com/overhangio/tutor/blob/release/docs/k8s.rst

Launch the Minikube dashboard to get a visual interface of your Kubernetes cluster. This provides a convenient way to monitor nodes, workloads, and services.

```bash
minikube dashboard
```

--------------------------------

### Run Portainer Docker Container

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/portainer.rst

Execute this command to start a Portainer container. It maps the Docker socket, persists data to /tmp/portainer, and exposes the UI on port 9000.

```bash
docker run --rm \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    --volume=/tmp/portainer:/data \
    -p 9000:9000 \
    portainer/portainer-ce:latest --bind=:9000
```

--------------------------------

### Browse Generated Documentation

Source: https://github.com/overhangio/tutor/blob/release/docs/tutor.rst

Open the locally generated HTML documentation in your web browser.

```bash
make browse
```

--------------------------------

### Scale Specific Open edX Services

Source: https://github.com/overhangio/tutor/blob/release/docs/sysadmin/scale.rst

Examples of scaling the LMS, CMS, and forum services to a specified number of replicas. These are common services that receive significant traffic.

```bash
tutor k8s scale lms 8
```

```bash
tutor k8s scale cms 4
```

```bash
tutor k8s scale forum 2
```

--------------------------------

### Set a New Theme

Source: https://github.com/overhangio/tutor/blob/release/docs/local.rst

Switch to a different theme for your Open edX platform. 'mytheme' should be replaced with the name of the theme you wish to apply.

```bash
tutor local do settheme mytheme
```

--------------------------------

### Build and Launch Development Environment

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/openedx.rst

Build the specialized 'openedx-dev' Docker image and launch the development environment. This process configures the platform for local development, including disabling HTTPS and setting a local domain.

```bash
tutor images build openedx-dev
tutor dev launch
```

--------------------------------

### Get Caddy Service External IP

Source: https://github.com/overhangio/tutor/blob/release/docs/k8s.rst

Retrieve the external IP address of the Caddy service. This IP is required to configure your DNS records to point to the load balancer.

```bash
kubectl --namespace openedx get services/caddy
```

--------------------------------

### Tutor CLI Parameterized Commands

Source: https://github.com/overhangio/tutor/blob/release/docs/cli.rst

Demonstrates how to parameterize Tutor CLI commands to specify targets and options for viewing logs.

```bash
tutor local logs cms          # View logs of the CMS container in a local deployment.
```

```bash
tutor k8s logs mysql          # View logs of MySQL in Kubernetes-managed deployment.
```

```bash
tutor dev logs lms --tail 10  # View ten lines of logs of the LMS container in development mode.
```

--------------------------------

### Launch Platform on Kubernetes

Source: https://github.com/overhangio/tutor/blob/release/docs/k8s.rst

Launches the Open edX platform on Kubernetes. This command also handles upgrades to the latest version.

```bash
tutor k8s launch
```

--------------------------------

### Customize PersistentVolumeClaim Storage in Kubernetes

Source: https://github.com/overhangio/tutor/blob/release/docs/k8s.rst

Add this k8s-override patch to a Tutor plugin to change the storage size of a PersistentVolumeClaim. This example increases the MongoDB volume size from 5Gi to 10Gi.

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: mongodb
  labels:
    app.kubernetes.io/component: volume
    app.kubernetes.io/name: mongodb
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi
```

--------------------------------

### Register CLI Initialization Tasks

Source: https://context7.com/overhangio/tutor/llms.txt

Register shell scripts to run during `tutor local do init`. Each item is a (service_name, shell_script) tuple.

```python
hooks.Filters.CLI_DO_INIT_TASKS.add_item((
    "lms",
    """
./manage.py lms migrate
./manage.py lms create_sites_and_configurations
echo "LMS init complete"
""",
))
```

```python
# Run before other init tasks (higher priority = runs first)
hooks.Filters.CLI_DO_INIT_TASKS.add_item(
    ("lms", "echo 'pre-init hook'"),
    priority=hooks.priorities.HIGH,
)
```

--------------------------------

### Define Local Docker Compose Service

Source: https://github.com/overhangio/tutor/blob/release/docs/developing/plugins/creating.rst

Add this patch to include your custom service in the local Docker Compose setup. This makes the service available in both production and development modes.

```yaml
myservice:
    image: myservice:latest
```

--------------------------------

### List Tutor Plugin Indexes

Source: https://github.com/overhangio/tutor/blob/release/docs/plugins/index.rst

Command to display the list of plugin indexes Tutor is currently configured to use.

```bash
tutor plugins index list
```

--------------------------------

### Add Python Hook for Plugin Lifecycle

Source: https://context7.com/overhangio/tutor/llms.txt

Register a Python function to hook into the COMPOSE_PROJECT_STARTED action. This function is executed when the project composition starts, allowing for custom logic within your plugin.

```python
@hooks.Actions.COMPOSE_PROJECT_STARTED.add()
def on_start(root: str, config: dict, project_name: str) -> None:
    if config.get("MYPLUGIN_ENABLED"):
        print(f"myplugin started for project: {project_name}")
```