erseco/alpine-moodle repository overview

⁠Alpine Moodle

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

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.

⁠Quick start

⁠Single container (SQLite — dev/demo only)

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!.

⁠With PostgreSQL (recommended)

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

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

⁠Running Commands as Root

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"

⁠Configuration

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/⁠.

⁠Moodle Playground Blueprints

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: [email protected]
      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": "[email protected]", "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⁠.

⁠Key features

• 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)
• Runs as the non-privileged nobody user
• Logs to stdout / stderr — just docker logs -f
• Internal cron via runit (configurable, or run it externally)

⁠PHP 8.4 opt-in images

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

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.

⁠Registries

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

⁠Documentation

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⁠

⁠Contributing

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.

⁠License

MIT⁠