Blueprint Reference: All Steps, Fields, and Options

This is the complete technical reference for Moodle Playground blueprint files. For a hands-on introduction and step-by-step walkthrough, see the Overview. For ready-to-run files you can open immediately, see the Examples. Version selection and Docker portability are covered in Runtime & Versions. The machine-readable JSON Schema is published at blueprint-schema.json — add it to your editor for autocomplete and inline validation. A blueprint is a JSON document describing the desired state of an instance at boot. Steps run sequentially in array order.

{
  "$schema": "https://ateeducacion.github.io/moodle-playground/assets/blueprints/blueprint-schema.json",
  "preferredVersions": { "php": "8.3", "moodle": "5.0" },
  "landingPage": "/my/",
  "constants": { "SITE_NAME": "My Moodle" },
  "steps": [
    { "step": "installMoodle", "options": { "siteName": "{{SITE_NAME}}" } },
    { "step": "login", "username": "admin" }
  ]
}

Top-level fields

Field	Type	Required	Description
`steps`	array	yes	Ordered list of step objects. Each object must include a `step` name string.
`constants`	object	no	`{{KEY}}` → string map. Every placeholder is substituted deeply across all fields before steps run.
`resources`	object	no	Named file descriptors referenced as `@name` from step fields.
`runtime`	object	no	Boot-time `config.php` settings: `debug` (`0`/`5`/`15`/`32767`) and `debugdisplay` (`0`/`1`).
`phpConstants`	object	no	PHP constants defined in `config.php` before `lib/setup.php`. Name → boolean / string / number.
`landingPage`	string	no	Path opened after boot. Must start with `/`.
`preferredVersions`	object	no	`{ "php": "8.3", "moodle": "5.0" }` — preferred runtime, subject to compatibility fallback.
`$schema`	string	no	Informational schema reference for editor validation.

Constants

constants defines {{KEY}} placeholders that are replaced deeply in every string value before any step executes.

{
  "constants": { "ADMIN_EMAIL": "admin@example.com" },
  "steps": [
    { "step": "installMoodle", "options": { "adminEmail": "{{ADMIN_EMAIL}}" } }
  ]
}

Context constants {{REPO}}, {{OWNER}}, {{REF}} / {{BRANCH}} are derived from the repo, owner, and branch (alias ref) URL parameters and merged over the blueprint’s own constants. This lets a committed blueprint target the branch it is currently previewing without hardcoding the branch name. See URL parameters.

PHP constants

phpConstants defines PHP constants in the booted Moodle’s config.php, before require_once(lib/setup.php), so they are available on every request. Each entry is emitted as a guarded define():

{
  "phpConstants": {
    "MY_FLAG": true,
    "MY_LABEL": "demo",
    "MY_LIMIT": 50
  }
}

produces, in config.php:

if (!defined('MY_FLAG'))  { define('MY_FLAG',  true); }
if (!defined('MY_LABEL')) { define('MY_LABEL', 'demo'); }
if (!defined('MY_LIMIT')) { define('MY_LIMIT', 50); }

Values may be boolean, string, or number. Constant names must match ^[A-Z_][A-Z0-9_]*$ — names that do not match are silently skipped. This lets a plugin’s own blueprint enable plugin-specific configuration without the playground engine needing to know any plugin-specific details. For example, mod_exelearning declares "phpConstants": { "EXELEARNING_UNSAFE_LEGACY_IFRAME": true } so its demo renders the content iframe same-origin.

Resources

A resource is a named file descriptor with exactly one source key. Reference it from any step with the string "@name", or inline the descriptor directly in the step field.

Key	Value
`url`	Fetch over HTTP(S). ~30 s timeout, ~50 MB cap.
`base64`	Inline base64-encoded data.
`data-url`	A `data:` URI.
`bundled`	Path relative to the app bundle.
`vfs`	Path already present in the runtime filesystem.
`literal`	Inline string or object value.

{
  "resources": {
    "backup": { "url": "https://example.com/course.mbz" }
  },
  "steps": [
    { "step": "restoreCourse", "data": "@backup", "category": "Demo" }
  ]
}

Steps

Legend:

(HTTP) — runs over an HTTP request (preserves session cookies).
(marker) — records options for boot; does no runtime work itself.
(non-fatal) — reports a failure but does not abort the remaining steps.
Batch steps — accept an array under the named field and process each entry.
All other steps abort the blueprint on error.

Install and auth

`installMoodle` (marker)

Records install options consumed at boot time. The actual installation is performed by bootstrap.js before steps run; this step passes configuration into that process.

options

object

Installation options object.

Show options fields

adminUser

string

Username for the admin account. Default: admin.

adminPass

string

Password for the admin account. Default: password.

adminEmail

string

Email for the admin account. Default: admin@example.com.

siteName

string

The site full name shown in the header. Default: Moodle Playground.

locale

string

Locale code for the default site language (e.g. en, es). Default: en.

timezone

string

PHP timezone string (e.g. UTC, Europe/Madrid). Default: UTC.

{ "step": "installMoodle", "options": { "siteName": "My Moodle", "locale": "en", "timezone": "UTC" } }

`setAdminAccount`

Updates the site admin account. All fields are optional.

password

string

New password for the admin.

string

New email address.

firstname

string

Admin first name.

lastname

string

Admin last name.

{ "step": "setAdminAccount", "password": "s3cret!", "email": "me@example.com" }

Starts an authenticated session. Subsequent HTTP steps (e.g. request, runPhpScript) will use this session’s cookies.

username

string

Username to log in as. Default: admin.

{ "step": "login", "username": "admin" }

Configuration

`setConfig`

Writes a single Moodle configuration value to mdl_config or mdl_config_plugins.

name

string

required

The config setting name (e.g. enablebadges, country).

value

string

The value to set. Default: "".

plugin

string

Plugin name for plugin-specific settings (e.g. theme_boost). Omit for core settings.

{ "step": "setConfig", "name": "enablebadges", "value": "1" }

`setConfigs` (batch)

Sets multiple config values in one step.

configs

array

required

Array of { "name": "...", "value": "...", "plugin": "..." } objects.

`setTheme`

Activates a Moodle theme by directory name.

name

string

required

Theme directory name, e.g. boost, moove, classic.

{ "step": "setTheme", "name": "moove" }

`setLandingPage` (marker)

Sets the page that opens after boot. Overrides the top-level landingPage field.

path

string

required

Site-relative path, must start with /. E.g. /my/, /course/index.php.

{ "step": "setLandingPage", "path": "/my/" }

Users

`createUser`

Creates a Moodle user account.

username

string

required

The login username.

password

string

Account password. Default: password.

string

Email address. Default: <username>@example.com.

firstname

string

First name. Default: the username value.

lastname

string

Last name. Default: User.

{ "step": "createUser", "username": "teacher1", "firstname": "Ada", "lastname": "Lovelace" }

`createUsers` (batch)

Creates multiple users in one step.

users

array

required

Array of user objects, each with the same fields as createUser.

string

required

Full course name displayed in headings.

shortname

string

required

Short name — the stable identifier used to reference this course in other steps.

`createCourses` (batch)

courses

array

required

Array of course objects.

`createSection`

Creates a named section inside an existing course.

course

string

required

Course shortname.

name

string

Section display name.

position

integer

Section position (0-indexed). Default: 0.

{ "step": "createSection", "course": "M101", "name": "Week 1", "position": 1 }

`createSections` (batch)

sections

array

required

Array of section objects.

Enrolment

`enrolUser`

Enrols a user in a course with a given role.

username

string

required

Username of the account to enrol.

course

string

required

Course shortname.

role

string

Moodle role shortname. Default: student. Common values: student, editingteacher, teacher, manager.

{ "step": "enrolUser", "username": "teacher1", "course": "M101", "role": "editingteacher" }

`enrolUsers` (batch)

enrolments

array

required

Array of { "username": "...", "course": "...", "role": "..." } objects.

Modules

`addModule`

Adds an activity or resource module to a course section. Any extra field beyond the documented ones is written directly to the module’s database record, so activity-specific settings can be set here.

module

string

required

Activity type name, e.g. label, assign, folder, page, quiz, board.

course

string

required

Course shortname.

section

integer

Section number (0-indexed). Default: 0.

name

string

Activity name shown in the course page.

intro

string

Activity description / introductory HTML.

files

array

Array of file attachments. Each entry requires filename and data (resource descriptor); optional: filearea (default content), itemid (default 0), filepath (default /).

Third-party modules must be installed with installMoodlePlugin before addModule can reference them.

{ "step": "addModule", "module": "assign", "course": "M101", "section": 1, "name": "Homework 1" }

Course restore

`restoreCourse` (non-fatal)

Restores a Moodle course from a .mbz backup file. This step is non-fatal — a failure is logged but does not stop remaining steps.

url

string

Direct URL to the .mbz file. Takes precedence over path and data.

path

string

Filesystem path to the .mbz file inside the runtime. Takes precedence over data.

data

string | object

Resource descriptor or @name reference. Used if neither url nor path is given.

Roles

`createRole`

Creates a custom Moodle role.

shortname

string

required

Unique machine-readable role identifier.

name

string

Human-readable role name.

description

string

Role description.

archetype

string

Base archetype to derive default permissions from (e.g. editingteacher, student).

resetToArchetype

boolean

Reset capabilities to the archetype’s defaults before applying overrides.

contextlevels

array

List of context levels (names or integers) where the role can be assigned.

capabilities

object

Map of capability name → allow / prevent / prohibit / inherit.

allowAssign

array

Role shortnames this role may assign.

allowOverride

array

Role shortnames this role may override.

allowSwitch

array

Role shortnames this role may switch to.

allowView

array

Role shortnames this role may view.

{ "step": "createRole", "shortname": "coordinator", "archetype": "editingteacher", "name": "Course Coordinator" }

`createRoles` (batch)

roles

array | string

Array of role objects, a @resource reference, or a URL resolving to a JSON array.

`importRolePreset`

Imports a role from a Moodle XML role-preset file using Moodle’s built-in parser.

xml

string

Inline role-preset XML string.

resource

string | object

@name reference or resource descriptor resolving to XML.

{ "step": "importRolePreset", "resource": "@coordinatorXml" }

`importRoles` (batch)

roles

array

required

Array of XML references: @name, raw XML string, { "xml": "..." }, or a resource descriptor.

Scales

`createScale`

Creates a grading scale.

name

string

required

Scale display name.

items

array | string

required

Scale values from lowest to highest — as an array (["Not yet", "Competent"]) or comma-separated string.

description

string

Scale description.

course

string

Course shortname for a course-level scale. Omit for a site-wide scale.

{ "step": "createScale", "name": "Competency", "items": ["Not yet", "Approaching", "Competent"] }

`createScales` (batch)

scales

array | string

Array of scale objects, a @resource reference, a URL, or the { "format": "moodle-scale-export", "scales": [...] } export envelope.

Cohorts

`createCohort`

Creates a site cohort (system-wide group).

name

string

required

Cohort display name.

idnumber

string

Unique idnumber used as an idempotency key and for external sync.

description

string

Cohort description.

visible

boolean

Whether the cohort is visible in the UI. Default: true.

members

array

Array of existing usernames to add as members on creation.

{ "step": "createCohort", "name": "Staff 2026", "idnumber": "staff2026", "members": ["teacher1", "teacher2"] }

`createCohorts` (batch)

cohorts

array | string

Array of cohort objects, a @resource reference, or a URL.

Plugins and themes

`installMoodlePlugin`

Downloads and installs a Moodle plugin from a GitHub archive ZIP URL.

url

string

required

GitHub archive ZIP URL, e.g. https://github.com/org/moodle-mod_board/archive/refs/heads/MOODLE_405_STABLE.zip.

pluginType

string

Override the detected plugin type (e.g. mod, block, local). Auto-detected from the moodle-TYPE_NAME repo-name convention.

pluginName

string

Override the detected plugin name. Auto-detected from the repo name.

{
  "step": "installMoodlePlugin",
  "url": "https://github.com/brickfield/moodle-mod_board/archive/refs/heads/MOODLE_405_STABLE.zip"
}

`installTheme`

Downloads and installs a Moodle theme. Files are placed in theme/<name>/ but the theme is not activated — pair with setTheme to activate it.

url

string

required

GitHub archive ZIP URL.

pluginName

string

Override the detected theme name.

{
  "step": "installTheme",
  "url": "https://github.com/willianmano/moodle-theme_moove/archive/refs/heads/MOODLE_500_STABLE.zip"
}

Languages

`installLanguagePack` (non-fatal)

Downloads and installs a Moodle language pack. This step is non-fatal — a download failure is logged but does not abort the blueprint.

language

string

A single language code (e.g. es, fr). Matches ^[a-z][a-z0-9_]*$.

languages

string | array

A comma-separated string or array of language codes.

lang

string | array

Alias for language / languages.

setDefault

boolean

Set this language as the site default. Default: false.

Setting the locale option in installMoodle already installs that pack on boot. Use installLanguagePack only for additional languages or to install a pack without changing the site default.

{ "step": "installLanguagePack", "language": "es", "setDefault": true }

File-backed config settings

These steps register a file with Moodle’s File API and point a config setting at it. This is required for logos, favicons, and theme images — setConfig alone cannot do this because those settings reference file record IDs, not raw paths.

`setConfigFile`

plugin

string

required

Plugin or component name (e.g. theme_boost, core_admin).

name

string

required

Config setting name that will be set to the file’s item ID.

filename

string

required

Filename to store in the File API (e.g. logo.png).

data

string | object

required

Resource descriptor or @name reference to the file contents.

filearea

string

File area name. Default: same as name.

itemid

integer

File API item ID. Default: 0.

filepath

string

File path in the File API. Default: /.

replace

boolean

Replace an existing file at the same path. Default: true.

setConfigValue

boolean

Write the item ID to the config setting. Default: true.

purgeCaches

boolean

Purge Moodle caches after storing the file. Default: false.

author

string

Author metadata for the File API record.

license

string

License string for the File API record.

source

string

Source URL metadata for the File API record.

userid

integer

User ID to own the file. Default: site admin ID.

{
  "step": "setConfigFile",
  "plugin": "theme_boost",
  "name": "logo",
  "filename": "logo.png",
  "data": { "url": "https://example.com/logo.png" }
}

`setConfigFiles` (batch)

Stores multiple files under a single component+setting combination.

plugin

string

required

Plugin or component name.

name

string

required

Config setting name.

files

array

required

Non-empty array of { "filename": "...", "data": ... } objects. Top-level optional fields act as defaults; the config value is set to the first stored file’s item ID.

Filesystem

`mkdir`

Creates a directory (recursively, like mkdir -p).

path

string

required

Absolute path in the WASM filesystem.

`rmdir`

Removes a directory.

path

string

required

Absolute path to remove.

recursive

boolean

Remove contents recursively. Default: false.

`writeFile`

Writes data to a file, creating parent directories as needed.

path

string

required

Absolute path of the file to write.

data

string | object

required

Inline string, @reference, or resource descriptor.

{ "step": "writeFile", "path": "/www/moodle/local/note.txt", "data": "hello" }

`writeFiles` (batch)

files

array

required

Array of { "path": "...", "data": ... } objects.

`copyFile`

Copies a file within the WASM filesystem.

from

string

required

Source path.

string

required

Destination path.

`moveFile`

Moves (renames) a file within the WASM filesystem.

from

string

required

Source path.

string

required

Destination path.

`deleteFile`

Deletes a single file. Idempotent — a missing path is skipped without error.

path

string

required

Absolute path of the file to delete.

`deleteFiles` (batch)

files

array

required

Array of string paths or { "path": "..." } objects.

`unzip`

Extracts a ZIP archive into a destination directory.

data

string | object

required

Resource descriptor or @name reference to the ZIP file.

destination

string

required

Absolute path to extract into. Also accepted as path.

{ "step": "unzip", "data": "@archive", "destination": "/www/moodle/local/myext" }

Requests and code

`request` (HTTP)

Makes an HTTP request to the running Moodle site. Useful for triggering cron, flushing caches, or calling web services.

url

string

URL to request. Default: the site root.

method

string

HTTP method. Default: GET.

headers

object

HTTP request headers as a key-value map.

body

string

Request body (for POST/PUT).

expectOk

boolean

Abort the blueprint if the response status is ≥ 400. Default: true.

{ "step": "request", "url": "http://localhost:8080/admin/cron.php" }

`runPhpCode`

Executes arbitrary PHP code in CLI mode (CLI_SCRIPT). The <?php opening tag is optional.

code

string

required

PHP code to execute.

{ "step": "runPhpCode", "code": "set_config('country', 'ES');" }

`runPhpScript` (HTTP)

Writes PHP code to a temporary file and executes it over HTTP (session cookies are available).

code

string

required

PHP code to execute.

expectOk

boolean

Abort on HTTP status ≥ 400. Default: true.

PR overlay

`applyPrOverlay`

Fetches changed files from a GitHub pull request or branch comparison and overlays them on the running Moodle filesystem, then optionally runs the upgrade script and purges caches.

files

array

Pre-resolved file manifest (skips GitHub API). Takes highest precedence.

repo

string

GitHub repository in owner/repo format (e.g. moodle/moodle).

integer

Pull request number. Used with repo to resolve files from a PR.

base

string

Base branch for a branch comparison. Default: main. Used with repo + head.

head

string

Head branch or commit SHA for a branch comparison. Used with repo + base.

baseRef

string

Override the base commit ref used for diff resolution.

runUpgrade

string

Whether to run admin/cli/upgrade.php. One of off / on / auto. Default: auto (best-effort, non-fatal).

root

string

Filesystem root to overlay files into. Default: /www/moodle.

proxy

string

HTTP proxy URL for GitHub API requests.

maxFiles

integer

Abort if the PR touches more files than this. Default: 200.

maxFileBytes

integer

Skip individual files larger than this (bytes). Default: 5 MiB.

purgeCaches

boolean

Purge Moodle caches after applying the overlay. Default: true.

{ "step": "applyPrOverlay", "repo": "moodle/moodle", "pr": 532, "runUpgrade": "auto" }

`purgeMoodleCaches`

Resets all Moodle caches and the component registry. Run automatically by applyPrOverlay.

{ "step": "purgeMoodleCaches" }

Execution model

Steps in a blueprint run sequentially in array order. The execution model distinguishes four categories:

CLI steps — the majority of steps; run PHP in CLI_SCRIPT mode. A non-zero exit code aborts the blueprint.
HTTP steps (login, request, runPhpScript) — run over an HTTP request against the running Moodle site, allowing session cookies to persist across calls.
Marker steps (installMoodle, setLandingPage) — do no runtime work; they record configuration consumed during or after the boot sequence.
Non-fatal steps (restoreCourse, installLanguagePack) — report failures to the console but continue with the next step. For applyPrOverlay, individual oversized files are skipped and the upgrade/cache-purge phases are best-effort, but manifest resolution failures and exceeding maxFiles still abort.

The createRole, createScale, createCohort, and importRoles generators silently skip references to capabilities, roles, or users that do not exist at runtime, but a missing required field or a PHP error still aborts the blueprint. For complete, working examples see the Examples page.

Get Started

Blueprints

Integrations

Reference

Documentation Index

​Top-level fields

​Constants

​PHP constants

​Resources

​Steps

​Install and auth

​installMoodle (marker)

​setAdminAccount

​login (HTTP)

​Configuration

​setConfig

​setConfigs (batch)

​setTheme

​setLandingPage (marker)

​Users

​createUser

​createUsers (batch)

​Categories

​createCategory

​createCategories (batch)

​Courses

​createCourse

​createCourses (batch)

​createSection

​createSections (batch)

​Enrolment

​enrolUser

​enrolUsers (batch)

​Modules

​addModule

​Course restore

​restoreCourse (non-fatal)

​Roles

​createRole

​createRoles (batch)

​importRolePreset

​importRoles (batch)

​Scales

​createScale

​createScales (batch)

​Cohorts

​createCohort

​createCohorts (batch)

​Plugins and themes

​installMoodlePlugin

​installTheme

​Languages

​installLanguagePack (non-fatal)

​File-backed config settings

​setConfigFile

​setConfigFiles (batch)

​Filesystem

​mkdir

​rmdir

​writeFile

​writeFiles (batch)

​copyFile

​moveFile

​deleteFile

​deleteFiles (batch)

​unzip

​Requests and code

​request (HTTP)

​runPhpCode

​runPhpScript (HTTP)

​PR overlay

​applyPrOverlay

​purgeMoodleCaches

​Execution model

Build docs developers (and LLMs) love

Top-level fields

Constants

PHP constants

Resources

Steps

Install and auth

`installMoodle` (marker)

`setAdminAccount`

`login` (HTTP)

Configuration

`setConfig`

`setConfigs` (batch)

`setTheme`

`setLandingPage` (marker)

Users

`createUser`

`createUsers` (batch)

Categories

`createCategory`

`createCategories` (batch)

Courses

`createCourse`

`createCourses` (batch)

`createSection`

`createSections` (batch)

Enrolment

`enrolUser`

`enrolUsers` (batch)

Modules

`addModule`

Course restore

`restoreCourse` (non-fatal)

Roles

`createRole`

`createRoles` (batch)

`importRolePreset`

`importRoles` (batch)

Scales

`createScale`

`createScales` (batch)

Cohorts

`createCohort`

`createCohorts` (batch)

Plugins and themes

`installMoodlePlugin`

`installTheme`

Languages

`installLanguagePack` (non-fatal)

File-backed config settings

`setConfigFile`

`setConfigFiles` (batch)

Filesystem

`mkdir`

`rmdir`

`writeFile`

`writeFiles` (batch)

`copyFile`

`moveFile`

`deleteFile`

`deleteFiles` (batch)

`unzip`

Requests and code

`request` (HTTP)

`runPhpCode`

`runPhpScript` (HTTP)

PR overlay

`applyPrOverlay`

`purgeMoodleCaches`

Execution model