Moodle Docker Brew

Helper for running MoodleHQ’s official moodle-docker stack on macOS with OrbStack. Start multiple Moodle versions side-by-side, run Behat and PHPUnit, and iterate on plugins quickly. This make it easier to run a Moodle test environment with all tools a developer needs.

Highlights

Wrapper around the official Moodle developer Docker image (https://github.com/moodlehq/moodle-docker)
macOS + OrbStack optimized workflow (fast, simple)
Homebrew formula: moodle-docker
Run multiple Moodle and Workplace versions concurrently
- For WorkPlace a Git repository need to be configured currently this hardcode to [email protected]:moodle-source/moodle-workplace.git
Built-in runners for behat and phpunit
Safety checks before doing destructive actions
Persistent data under ~/moodle-docker-brew/moodle (when installed via Homebrew)
Supported versions: dev (latest), 5.0, 4.5, 4.4, 4.3, 4.2, 4.1, 4.0, 3.11, 3.10, 3.9
Port convention per version: web 80NN, DB 330NN, VNC 590NN (e.g., 8042/33042/59042 for 4.2)
Development version uses special ports: web 8099, DB 33099, VNC 59099
Default admin credentials: admin / test

Requirements

macOS
Docker via OrbStack (brew install orbstack)
git and unzip available on PATH
GitHub SSH key configured for upgrade (clones moodlehq/moodle-docker via SSH)
Access to a Workplace installation

Install

Homebrew (recommended)

brew install ldesignmedia/moodledocker/moodle-docker

More info about the tap: https://github.com/LdesignMedia/homebrew-moodle-docker

Local clone (for development)

git clone https://github.com/LdesignMedia/moodle-docker-brew.git
cd moodle-docker-brew
./moodle-docker help

Note: When installed via Homebrew, Moodle data lives under ~/moodle-docker-brew/moodle. Using moodle-docker destroy removes the data for the selected version.

Quick Start

# Start Moodle 4.2 (downloads Moodle, creates DB, launches containers)
moodle-docker start 42

# Start with a specific PHP version
moodle-docker start 42 --php=8.2

# Or try the latest development version
moodle-docker start dev

# Open your browser
open http://localhost:8042/  # For version 4.2
open http://localhost:8099/  # For dev version

# Stop containers (keeps data)
moodle-docker stop 42

# Remove containers and data for 4.2
moodle-docker destroy 42

Step‑by‑Step Usage

Start a Moodle version

Pick a supported version number (e.g., 42 for 4.2) and start it:

moodle-docker start 42

The script downloads Moodle, starts the containers, installs the DB, and initializes Behat + PHPUnit. Watch the output for the line beginning with Directory: — that path is where your Moodle files live for that version.

Open the site

Visit http://localhost:8042
Login with admin / test

Develop plugins (optional)

Place your plugin inside the working directory shown as Directory: in the terminal output, under the correct subfolder, e.g.:
- .../moodle/42/local/myplugin
- .../moodle/42/mod/myactivity
- .../moodle/42/blocks/myblock
Go to Site administration → Notifications to install/upgrade your plugin.
After adding or changing plugins, re-initialize test frameworks:

moodle-docker update 42

Run tests

Behat (with optional tags):

moodle-docker behat 42 --tags=@your_tag

PHPUnit (point to a test or directory):

moodle-docker phpunit 42 path/to/tests

Stop or destroy when done

Stop containers (preserves data): moodle-docker stop 42
Destroy containers and data for that version: moodle-docker destroy 42

Commands

moodle-docker help                      # Usage and examples
moodle-docker start   {version}         # Start (e.g., dev, 50, 45, 44, 43, 42, 41, 40, 311, 310, 39)
moodle-docker stop    {version}         # Stop containers (preserves data)
moodle-docker destroy {version}         # Stop and remove containers + data
moodle-docker init    {version}         # Re-init Behat + PHPUnit (after adding plugins)
moodle-docker behat   {version} [...]   # Run Behat in the container
moodle-docker phpunit {version} [...]   # Run PHPUnit in the container
moodle-docker xdebug  {version} [cmd]   # Manage Xdebug (install/enable/disable/status)
moodle-docker upgrade                   # Update this tool + upstream moodlehq/moodle-docker
moodle-docker grunt   {version} [watch] # Run grunt watch (JS/CSS builder)

Examples:

# Behat: run a tagged suite on 4.2
moodle-docker behat 42 --tags=@auth_manual

# PHPUnit: run a test on 4.2
moodle-docker phpunit 42 auth/manual/tests/manual_test.php

Behat Setup & Testing

First-time init: Behat is initialized automatically when you run moodle-docker start {version}
Re-initialize after adding/updating plugins:

moodle-docker init {version}     # e.g., moodle-docker init 42

Running Behat Tests

# Run all tests
moodle-docker behat 42

# Run specific tags
moodle-docker behat 42 --tags=@auth

# Run specific feature file
moodle-docker behat 42 /path/to/test.feature

# Interactive mode (pauses at breakpoints)
moodle-docker behat 42 --interactive --tags=@mytests

Watching Tests in Real-Time with VNC

Connect to the Selenium container to watch tests run visually:

Download a VNC viewer: RealVNC Viewer
Connect to the VNC server:
- Host: localhost
- Port: 590NN (e.g., 59042 for Moodle 4.2)
- Password: secret
Watch your tests execute in a real browser window

Interactive Testing

Interactive mode allows you to debug tests step-by-step and watch them run in real-time via VNC.

How to Run Interactive Tests

# Run tests interactively with the --interactive or -i flag
moodle-docker behat 42 --interactive --tags=@mytest

# Or use the short form
moodle-docker behat 42 -i --tags=@mytest

What Happens in Interactive Mode

VNC Connection Pause: The script pauses before starting tests, giving you time to connect your VNC viewer
Test Pausing: Tests pause at @pause tags in your scenarios
Failure Stops: Tests stop immediately on the first failure for debugging
Verbose Output: Detailed test execution information is displayed
Manual Control: Press Enter to continue when tests pause

Setting Up VNC to Watch Tests

When you run tests in interactive mode:

The script will pause and display:

⏸️  PAUSE: Open your VNC viewer now!
Connect VNC viewer to: localhost:59042 (port varies by version)
Password: secret

Open your VNC viewer and connect before pressing Enter
Once connected, press Enter to start the tests

Using @pause Tags for Breakpoints

Add @pause tags to your Behat scenarios to create breakpoints:

@mytest @pause
Scenario: Test with a breakpoint
    Given I am on homepage
    When I log in as "admin"
    Then I should see "Dashboard"  # Test pauses here
    And I click on "Site administration"  # Press Enter to continue to this step

When the test reaches a @pause tag:

The test execution pauses
You can inspect the browser state in VNC
Press Enter in the terminal to continue

Example Workflow

# 1. Start interactive test
moodle-docker behat 42 -i --tags=@auth_manual

# 2. Script pauses - connect VNC viewer to localhost:59042

# 3. Press Enter when VNC is connected

# 4. Tests run - they pause at any @pause tags

# 5. Press Enter to continue past each pause point

Useful URLs

Behat test status: http://localhost:80NN/admin/tool/behat/index.php
Failed test screenshots: http://localhost:80NN/_/faildumps/

Xdebug (PHP Debugging)

Enable step-by-step debugging for PHP development:

# Install and configure Xdebug for Moodle 4.2
moodle-docker xdebug 42 install

# Check Xdebug status
moodle-docker xdebug 42 status

# Temporarily disable Xdebug (improves performance when not debugging)
moodle-docker xdebug 42 disable

# Re-enable Xdebug
moodle-docker xdebug 42 enable

IDE Configuration

Configure your IDE to listen on port 9003
Set path mappings:
- Local: /path/to/moodle-docker-brew/moodle/42
- Remote: /var/www/html
For PHPStorm/VSCode, you may need to set an IDE key in the Xdebug config

Notes

Xdebug uses host.docker.internal on macOS
Performance is slower with Xdebug enabled - disable when not debugging

Grunt (JS/CSS Build)

Use grunt to rebuild AMD modules and theme assets during development.

# Start the watcher for Moodle 4.2
moodle-docker grunt 42 watch

What this does inside the container:

Installs NVM if missing, selects a Node version based on package.json engines (22, 20, 18, or 16; defaults to 20).
Installs grunt-cli globally and project dependencies (npm ci if lockfile exists, else npm install).
Runs grunt watch in /var/www/html.

Notes:

This is a long-running process; keep it open in a dedicated terminal tab.
Stop with Ctrl+C. You can restart anytime.
If dependencies change or you hit errors, run moodle-docker grunt {version} watch again to reinstall as needed.

Access & Ports

Web: http://localhost:80NN/ (e.g., 8042)
DB (MariaDB): host localhost, port 330NN, user moodle, pass m@0dl3ing
VNC (Selenium): host localhost, port 590NN, password secret
Behat faildumps: http://localhost:80NN/_/faildumps/
Mail catcher: http://localhost:80NN/_/mail/

VNC viewer example: download RealVNC Viewer, connect to localhost:59042 for Moodle 4.2.

PHP Versions

Default PHP Versions

Each Moodle version automatically uses the appropriate PHP version:

Moodle 3.9 → PHP 7.4
Moodle 3.10-3.11 → PHP 8.0
Moodle 4.0-4.3 → PHP 8.0
Moodle 4.4-4.5 → PHP 8.1
Moodle 5.0+ → PHP 8.2
Development (dev) → PHP 8.2

Manual PHP Version Override

You can override the default PHP version using the --php flag:

# Start Moodle 5.0 with PHP 8.3 instead of default 8.2
moodle-docker start 50 --php=8.3

# Start Moodle 4.4 with PHP 8.2 instead of default 8.1
moodle-docker start 44 --php=8.2

# Test your plugin with different PHP versions
moodle-docker start 45 --php=7.4  # Test backward compatibility
moodle-docker start 45 --php=8.3  # Test forward compatibility

Note: The specified PHP version must be available as a Docker image (moodlehq/moodle-php-apache:VERSION). Common versions include: 7.4, 8.0, 8.1, 8.2, 8.3

Upgrade

Upgrade the Homebrew formula and refresh the embedded moodlehq/moodle-docker checkout:

brew upgrade moodle-docker
moodle-docker upgrade

Tip: upgrade uses SSH. Ensure your GitHub SSH key is configured or the clone will fail.

Troubleshooting

OrbStack not installed: install with brew install orbstack and start OrbStack.
Ports in use: stop the other process or choose a different version number.
Missing unzip/git: install via Homebrew (brew install unzip git).
SSH access errors on upgrade: add your GitHub SSH key (ssh -T [email protected]).
Clean start: run moodle-docker destroy {version} and then moodle-docker start {version}.

Contributing

Contributions are welcome via pull request.

Keep changes small and focused; use 2‑space indent for shell scripts.
Share reusable logic under scripts/helper.sh.
Lint/format: shellcheck moodle-docker scripts/*.sh and shfmt -w ..
Verify end‑to‑end: start → behat/phpunit → stop.
Don’t commit secrets or local moodle/* contents.

Changelog

See CHANGELOG.md for a detailed version history.

Version Map

Supported Moodle versions and their download URLs are defined in moodle_versions.txt. Update this file when adding new versions.

To‑Do

Core Features

Use an environment variable for Workplace GIT location: [email protected]:moodle-source/moodle-workplace.git this should be added to .bashrc or .zshrc
Add developer/commander tools
Command to stop all running instances (moodle-docker stop-all)
Display all running Moodle versions (moodle-docker status)
Add moodle-docker restart <version> command
Add moodle-docker logs <version> [--follow] for viewing container logs
Add moodle-docker exec <version> <command> for running arbitrary commands
Support for custom PHP versions override globally (not just per command)

Database & Data Management

Upgrade to a higher Moodle version
Easy swithing to another PHP version

Development Tools

Add moodle-docker composer <version> for running composer commands
Add moodle-docker npm <version> for running npm commands
Add moodle-docker moosh <version> integration for Moosh commands
Add moodle-docker codechecker <version> [plugin_path] for Moodle code checker
Add moodle-docker profile <version> for XHProf profiling

User & Configuration Management

Language pack installation command , loads default configuration from tool_developer and also install this.

Monitoring & Debugging

Add moodle-docker debug <version> [on|off] to toggle debug mode
Integration with browser developer tools

Container Management

Auto-cleanup of unused containers/images
Allowing multiple containers for same Moodle version and give them a custom name.

Documentation & UX

Video: Fresh installation on macOS with orbstack, homebrew
Video: configure PhpStorm for plugin testing
Video: debugging with Xdebug and PHPStorm
Add moodle-docker doctor for system diagnostics

Integration Features

Integration with Moodle Mobile app development

Advanced Features

Redis/Memcached cache backends

Platform Support

Linux compatibility testing and documentation
Windows WSL2 support and documentation
ARM64 (Apple Silicon) optimization
Docker Desktop alternative support documentation

Authors

Luuk Verhoeven — Ldesign Media — [email protected]

Name		Name	Last commit message	Last commit date
moodle		moodle
screenshots		screenshots
scripts		scripts
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
moodle-docker		moodle-docker
moodle_versions.txt		moodle_versions.txt

Latest commit

History

Folders and files

Repository files navigation