0
# Tutor
1

2
The Docker-based Open edX distribution designed for peace of mind. Tutor is the official Open edX distribution that simplifies deployment, customization, upgrading, and scaling of Open edX platforms through complete Docker containerization and extensible plugin architecture.
3

4
## Package Information
5

6
- **Package Name**: tutor
7
- **Language**: Python
8
- **Installation**: `pip install tutor`
9
- **CLI Command**: `tutor`
10

11
## Core Imports
12

13
```python
14
import tutor
15
```
16

17
For working with configuration:
18
```python
19
from tutor import config
20
from tutor.types import Config, ConfigValue
21
```
22

23
For plugin development:
24
```python
25
from tutor import hooks
26
from tutor.plugins import base
27
from tutor.core.hooks import Action, Filter, Context
28
```
29

30
For environment and template rendering:
31
```python
32
from tutor import env
33
from tutor.env import JinjaEnvironment, Renderer
34
```
35

36
For CLI and task execution:
37
```python
38
from tutor.commands.context import Context, BaseTaskContext
39
from tutor.tasks import BaseTaskRunner, BaseComposeTaskRunner
40
```
41

42
For utilities and formatting:
43
```python
44
from tutor import utils, fmt
45
from tutor.exceptions import TutorError
46
```
47

48
## Basic Usage
49

50
### Command Line Interface
51

52
```bash
53
# Initialize and launch Open edX platform locally
54
tutor local launch
55

56
# Configure the platform
57
tutor config save --interactive
58

59
# Install and enable plugins
60
tutor plugins install discovery
61
tutor plugins enable discovery
62

63
# Run in development mode
64
tutor dev launch
65

66
# Deploy to Kubernetes
67
tutor k8s launch
68
```
69

70
### Programmatic Configuration
71

72
```python
73
from tutor import config
74
from tutor.commands.context import Context
75

76
# Load configuration
77
context = Context("/path/to/tutor/root")
78
config_data = config.load(context.root)
79

80
# Update configuration
81
config_data["PLATFORM_NAME"] = "My Open edX Platform"
82
config.save_config_file(context.root, config_data)
83
```
84

85
## Architecture
86

87
Tutor's architecture enables flexible Open edX deployment across multiple environments:
88

89
- **CLI Commands**: User-facing commands for deployment, configuration, and management
90
- **Hooks System**: Event-driven plugin architecture with Actions and Filters
91
- **Plugin Framework**: Extensible system supporting v0 (YAML) and v1 (Python) plugins
92
- **Environment Rendering**: Jinja2-based template system for generating configuration files
93
- **Task Runners**: Environment-specific execution contexts (Local, Dev, Kubernetes)
94

95
This design provides a unified interface for Open edX deployment while supporting extensive customization through plugins and configuration templates.
96

97
## Capabilities
98

99
### Command Line Interface
100

101
Complete CLI for Open edX deployment and management with commands for local development, production deployment, configuration management, plugin administration, and image building.
102

103
```python { .api }
104
def main() -> None: ...
105
class TutorCli(click.Group): ...
106
def cli(context: click.Context, root: str, show_help: bool) -> None: ...
107
```
108

109
[CLI Commands](./cli-commands.md)
110

111
### Configuration Management
112

113
Centralized configuration system with support for defaults, user overrides, environment variables, and interactive setup.
114

115
```python { .api }
116
def load(root: str) -> Config: ...
117
def load_defaults() -> Config: ...
118
def load_minimal(root: str) -> Config: ...
119
def save(context: Context, **kwargs) -> None: ...
120
```
121

122
[Configuration](./configuration.md)
123

124
### Hooks and Plugin System
125

126
Event-driven plugin architecture enabling extensibility through Actions, Filters, and Contexts for lifecycle management and data transformation.
127

128
```python { .api }
129
class Action[T]:
130
    def add(self, priority: int = None) -> Callable: ...
131
    def do(self, *args, **kwargs) -> None: ...
132

133
class Filter[T1, T2]:
134
    def add(self, priority: int = None) -> Callable: ...
135
    def apply(self, value: T1, *args, **kwargs) -> T2: ...
136
```
137

138
[Hooks and Plugins](./hooks-plugins.md)
139

140
### Environment and Templates
141

142
Template rendering system using Jinja2 for generating Docker Compose configurations, Kubernetes manifests, and application settings.
143

144
```python { .api }
145
def render_file(config: Config, *path: str) -> str: ...
146
def save_file(root: str, filename: str, content: str) -> None: ...
147
```
148

149
[Environment Management](./environment.md)
150

151
### Task Execution
152

153
Abstract task runner framework supporting different deployment contexts (Local, Dev, Kubernetes) with Docker Compose integration.
154

155
```python { .api }
156
class BaseTaskRunner:
157
    def run_task(self, service: str, command: str) -> int: ...
158
    def render(self, *path: str) -> str: ...
159
```
160

161
[Task Execution](./task-execution.md)
162

163
### Utilities and Types
164

165
Core utilities for encryption, file operations, string processing, bind mount management, YAML serialization, and type definitions for configuration management.
166

167
```python { .api }
168
ConfigValue = Union[str, float, None, bool, List[str], List[Any], Dict[str, Any], Dict[Any, Any]]
169
Config = Dict[str, ConfigValue]
170

171
def encrypt(text: str) -> str: ...
172
def random_string(length: int) -> str: ...
173
def parse_mount(value: str) -> list[tuple[str, str, str]]: ...
174
def load(stream: Union[str, IO[str]]) -> Any: ...
175
```
176

177
[Utilities](./utilities.md)
178

179
## Types
180

181
```python { .api }
182
# Standard library imports for type annotations
183
from typing import Union, Dict, List, Any, Optional, Callable, IO, Iterator, Iterable
184
from _io import TextIOWrapper
185
import click
186

187
# Core configuration types
188
ConfigValue = Union[str, float, None, bool, List[str], List[Any], Dict[str, Any], Dict[Any, Any]]
189
Config = Dict[str, ConfigValue]
190

191
# Context type for CLI operations
192
class Context:
193
    def __init__(self, root: str): ...
194
    @property
195
    def root(self) -> str: ...
196

197
class BaseTaskContext(Context):
198
    def job_runner(self, config: Config) -> BaseTaskRunner: ...
199

200
# Base exception
201
class TutorError(Exception): ...
202

203
# Task runner base classes
204
class BaseTaskRunner:
205
    def __init__(self, root: str, config: Config): ...
206
    def run_task(self, service: str, command: str) -> int: ...
207

208
class BaseComposeTaskRunner(BaseTaskRunner):
209
    def docker_compose(self, *command: str) -> int: ...
210

211
# Environment classes
212
class JinjaEnvironment:
213
    def read_str(self, template_name: str) -> str: ...
214
    def read_bytes(self, template_name: str) -> bytes: ...
215

216
class Renderer:
217
    def __init__(self, config: Optional[Config] = None): ...
218
    def render_str(self, text: str) -> str: ...
219
    def render_template(self, template_name: str) -> Union[str, bytes]: ...
220
```