A lightweight Moodle Docker image built on Alpine Linux — ~100 MB, PHP 8.3 FPM, Nginx, multi-arch, configured entirely through environment variables.

📚 Full documentation: https://erseco.github.io/alpine-moodle/

The documentation site covers quick start, docker-compose recipes, reverse proxy setups (Traefik, Nginx, NPM, Apache, Caddy), every supported environment variable, persistence and upgrade workflows, and a troubleshooting section built from the most frequent support questions.

docker run -d \
  -p 80:8080 \
  -e MOODLE_DATABASE_TYPE=sqlite3 \
  -e MOODLE_PASSWORD=ChangeMe123! \
  -v moodledata:/var/www/moodledata \
  erseco/alpine-moodle

Open http://localhost and log in with moodleuser / ChangeMe123!.

services:
  postgres:
    image: postgres:alpine
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: moodle
      POSTGRES_USER: moodle
      POSTGRES_DB: moodle
    volumes:
      - postgres:/var/lib/postgresql

  moodle:
    image: erseco/alpine-moodle
    restart: unless-stopped
    environment:
      MOODLE_USERNAME: admin
      MOODLE_PASSWORD: ChangeMe123!
    ports:
      - "80:8080"
    volumes:
      - moodledata:/var/www/moodledata
      - moodlehtml:/var/www/html
    depends_on:
      - postgres

volumes:
  postgres:
  moodledata:
  moodlehtml:

docker compose up -d

AUTO_UPDATE_MOODLE only runs the database upgrade (admin/cli/upgrade.php). The PHP code is handled separately:

# 1. Change the image tag (e.g. v5.0.1 → v5.0.2) in compose
# 2. Pull and recreate
docker compose pull
docker compose up -d
docker compose logs -f moodle
# Look for: Moodle code sync: 2025041401.00 → 2025041402.00

Preserve custom plugins that live only on the volume:

environment:
  SYNC_MOODLE_CODE: auto                    # default — set "never" to freeze the volume tree
  EXTRA_PLUGIN_PATHS: "mod/attendance theme/space local/mytool"
  # Or reinstall every boot (recommended when possible):
  # PLUGINS: "mod_attendance=https://…/attendance.zip"

Full details: Upgrading · Persistence · issue #103.

For production deployments (reverse proxy, TLS, Redis, tuning), see the documentation site.

In certain situations, you might need to run commands as root within your Moodle container, for example, to install additional packages. You can do this using the docker compose exec command with the --user root option:

docker compose exec --user root moodle sh

Example — install an extra Alpine package for debugging:

docker compose exec --user root moodle sh -c "apk update && apk add nano curl"

Define the ENV variables in docker-compose.yml. The full reference with notes, grouping and defaults lives at https://erseco.github.io/alpine-moodle/environment-variables/.

⚠️ Experimental. alpine-moodle can apply Moodle Playground-compatible blueprint.json files after Moodle has been installed or upgraded. This is an additional declarative provisioning layer for repeatable development, QA, CI and demo scenarios — it does not replace the environment-variable configuration. Only a documented subset of steps is implemented; unsupported steps fail clearly and unsafe steps are disabled by default.

The same blueprint.json can describe one Moodle scenario for two complementary sibling runtimes:

• moodle-playground — the browser/WASM runtime for ephemeral QA, demos, shareable reproductions and fast validation. No server required.
• alpine-moodle — this Docker runtime for local development, CI, plugin development, integration testing, persistence and real server-side behaviour (cron, mail, database, file system).

Author a blueprint once; run it in the browser for a quick look and in Docker when you need a real, persistent Moodle.

A new startup hook (rootfs/docker-entrypoint-init.d/03-apply-blueprint.sh) runs after 02-configure-moodle.sh and calls /usr/local/bin/moodle-blueprint apply when a blueprint variable is set.

If several sources are set, precedence is MOODLE_BLUEPRINT_BUNDLE > MOODLE_BLUEPRINT > MOODLE_BLUEPRINT_URL.

Compatibility matrix:

Minimal example:

services:
  moodle:
    image: erseco/alpine-moodle:latest
    ports:
      - "8080:8080"
    environment:
      MOODLE_DATABASE_TYPE: sqlite3
      MOODLE_USERNAME: admin
      MOODLE_PASSWORD: ChangeMe123!
      MOODLE_EMAIL: admin@example.com
      MOODLE_SITENAME: "Blueprint Demo"
      MOODLE_BLUEPRINT: /blueprints/demo.blueprint.json
    volumes:
      - moodledata:/var/www/moodledata
      - ./demo.blueprint.json:/blueprints/demo.blueprint.json:ro

volumes:
  moodledata:

{
  "$schema": "https://raw.githubusercontent.com/ateeducacion/moodle-playground/main/assets/blueprints/blueprint-schema.json",
  "preferredVersions": { "php": "8.3", "moodle": "5.0" },
  "landingPage": "/course/index.php",
  "steps": [
    { "step": "setConfig", "name": "debug", "value": 32767 },
    { "step": "createCategory", "name": "Blueprint demo", "idnumber": "blueprint-demo" },
    { "step": "createCourse", "fullname": "Blueprint demo course", "shortname": "BLUEPRINT101", "category": "blueprint-demo" },
    { "step": "createUser", "username": "student1", "password": "ChangeMe123!", "email": "student1@example.com", "firstname": "Student", "lastname": "One" },
    { "step": "enrolUser", "username": "student1", "course": "BLUEPRINT101", "role": "student" }
  ]
}

Bundles co-locate a blueprint.json with its resources (directory or ZIP, blueprint.json at the root or one directory deep, __MACOSX ignored):

my-moodle-blueprint/
├── blueprint.json
└── plugins/
    └── mod_example.zip

See the full guide, resource descriptors, security model and idempotency notes in docs/blueprints.md (published at https://erseco.github.io/alpine-moodle/blueprints/). A copy-pasteable example lives in docs/examples/demo.blueprint.json.

• Compact image (~100 MB) built on erseco/alpine-php-webserver
• PHP 8.3 FPM with ondemand process manager — idles near-zero CPU (opt-in PHP 8.4 images available for Moodle 5.x)
• PostgreSQL, MariaDB/MySQL or SQLite (single-container dev mode)
• Optional Redis session handler
• Supports Moodle 4.x, 5.0, 5.1+ (auto-detects /public layout) and main
• Multi-arch: amd64, arm64, arm/v7, arm/v6, 386, ppc64le, s390x
• Moosh CLI bundled for automation
• Pre/post configuration hooks (PRE_CONFIGURE_COMMANDS, POST_CONFIGURE_COMMANDS)
• Version-aware Moodle code sync (SYNC_MOODLE_CODE=auto) so a persistent moodlehtml volume upgrades when you change the image tag — no more docker volume rm for core updates (#103)
• Runs as the non-privileged nobody user
• Logs to stdout / stderr — just docker logs -f
• Internal cron via runit (configurable, or run it externally)

The default erseco/alpine-moodle tags currently remain on PHP 8.3 to preserve compatibility with existing Moodle 4.5 LTS installations and avoid breaking existing deployments.

PHP 8.4 images are available as opt-in tags for Moodle 5.x and later, identified by a -php84 suffix:

docker pull erseco/alpine-moodle:v5.2.1-php84
docker pull ghcr.io/erseco/alpine-moodle:v5.2.1-php84

Moodle 4.x is not available on PHP 8.4. Moodle 4.5 LTS does not support PHP 8.4, so no -php84 images are published for the 4.x line — keep using the default PHP 8.3 tags there.

These -php84 tags are built from the php84 branch and never overwrite the existing latest, main, or vX.Y.Z tags, which stay on PHP 8.3 for now.

The default official tags — including latest — will move to PHP 8.4 once Moodle 5.3 LTS (planned for 5 October 2026) is released and becomes the new LTS baseline.

• Docker Hub: erseco/alpine-moodle
• GitHub Container Registry: ghcr.io/erseco/alpine-moodle

The full, searchable documentation lives at https://erseco.github.io/alpine-moodle/:

• Quick Start
• Docker Compose examples
• Reverse proxy guides (Traefik, Nginx, NPM, Apache, Caddy)
• Environment variables reference
• Persistence & volumes
• Configuration & Moosh
• SQLite single-container mode
• Upgrading
• Troubleshooting
• FAQ

Issues and pull requests are welcome: https://github.com/erseco/alpine-moodle/issues.

Documentation sources live under docs/ and are built with Zensical via the docs.yml GitHub Actions workflow.

MIT