jimsihk/alpine-moodle repository overview

⁠High Availability Moodle on Alpine Linux

Moodle setup with high availability (HA) capabilities for Docker, build on Alpine Linux⁠.

Repository: https://github.com/jimsihk/alpine-moodle⁠

• Based on official Moodle source https://github.com/moodle/moodle⁠
• Built on the lightweight image https://github.com/jimsihk/alpine-php-nginx⁠
• Smaller container image size (+/-150MB for full version, +/-90MB for slim version)
• Supports HA installation with multiple type of cache stores (memcached, Redis) and PostgresSQL poolers like PgBouncer
• Supports also Redis Sentinel as cache stores via plugin https://github.com/catalyst/moodle-cachestore_redissentinel⁠
• Pre-install Moodle plug-ins at build time with argument ARG_MOODLE_PLUGIN_LIST
• Always up-to-date Moodle version and Alpine packages with Renovate (see below)
• Supports read-only replica of database
• Multi-arch support: 386, amd64, arm/v7, arm64, ppc64le, s390x
• Optimized for 100 concurrent users
• Optimized to only use resources when there's traffic (by using PHP-FPM's ondemand PM)
• JIT enabled by default
• Use of runit instead of supervisord to reduce memory footprint
• Configured cron to run as non-privileged user https://github.com/gliderlabs/docker-alpine/issues/381#issuecomment-621946699⁠
• Configuration via ENV variables
• Auto update Moodle plugin and upgrade to newer Moodle versions (via ARG_MOODLE_GIT_URL and ARG_MOODLE_GIT_BRANCH at build time, MOODLE_GIT_URL and MOODLE_GIT_BRANCH at run time) when container start
• The servers NGINX, PHP-FPM run under a non-privileged user (nobody) to make it more secure
• The logs of all the services are redirected to the output of the Docker container (visible with docker logs -f <container name>)
• Follows the KISS principle (Keep It Simple, Stupid) to make it easy to understand and adjust the image to your needs

⁠Automated Release

Moodle version and package dependencies are monitored and automatically updated through pull requests by Renovate: https://github.com/renovatebot/renovate⁠

When Renovate updates the jimsihk/alpine-php-nginx base image in Dockerfile, GitHub Actions also refreshes the Alpine package pins in that same PR if the image moves to a new Alpine major/minor series.

A nightly build in GitHub Action scans for changes, then performs tagging and publishes a newer release on container registries.

The release tag will be in pattern: XXX.YYY.ZZ

• XXX = Moodle Branch
• YYY = Moodle Release Increments & Incremental Changes Number based on version.php of Moodle source
• ZZ = Git Repo Releases

e.g. for Moodle 4.1.1+ branch 401 version 2022112801.06, the release tag number will be starting from 401.106.0

⁠Multiple Container Registry

The images are available on multiple registries:

• DockerHub: https://hub.docker.com/r/jimsihk/alpine-moodle⁠
• Quay.io: https://quay.io/repository/jimsihk/alpine-moodle⁠

⁠Image Variants

⁠alpine-moodle:XXX.YYY.ZZZ

• Standard version with full features

⁠alpine-moodle:XXX.YYY.ZZZ-slim

• Even smaller container image size
• Git is not installed
• Removed in-place code upgrade functionality (i.e. ignored UPDATE_MOODLE_CODE)
• Controlled by build argument ARG_ENABLE_GIT_CLONE when build

⁠Usage

Start the Docker containers:

docker compose up

Start a Moodle cluster:

./generate_ssl_cert.sh
docker compose --file docker-compose.replica.yml up

Login on the system using the provided credentials (ENV vars)

⁠Sample docker-compose files

• docker-compose.yml⁠ - with PostgreSQL
• docker-compose.replica.yml⁠ - with PostgreSQL, Redis and multiple Moodle containers, using NGINX as load balancer with SSL termination
  • execute generate_ssl_cert.sh to generate a sample SSL certificate for localhost
  • refer to https://docs.moodle.org/en/Caching⁠ for setting up after login or set the SESSION_CACHE_* environment variables
  • please note this setup is NOT configured for production use, use it for demonstration only

⁠Configuration

Define the ENV variables in docker-compose.yml file

More settings on PHP and NGINX can refer to the base image https://github.com/jimsihk/alpine-php-nginx/blob/dev/README.md⁠

⁠Important Note about using AUTO_UPDATE_MOODLE and UPDATE_MOODLE_CODE

If set to true, Moodle will be set to CLI maintenance mode⁠ at container start while performing the update. No user will be able to use Moodle, not even admin.

If a cluster of Moodle containers are deployed for HA (e.g. on Kubernetes), it is suggested to set both to false to avoid unexpected interruption to users when auto scaling, such as adding extra containers to the cluster or container restart for auto healing.

⁠Custom builds

⁠Moodle plugins

⁠ARG_MOODLE_PLUGIN_LIST: define the list of plugins

• For installing plugins while building the main Dockerfile (slower), use ARG_MOODLE_PLUGIN_LIST:

docker buildx build . -t my_moodle_image:my_tag \
    --build-arg ARG_MOODLE_PLUGIN_LIST='mod_attendance mod_checklist mod_customcert block_checklist gradeexport_checklist'

• For building only to install additional moodle plugins (faster), create a Dockerfile like the following and then build.
• Example of Dockerfile.plugins:

# Dockerfile.plugins
FROM quay.io/jimsihk/alpine-moodle:latest

# Install additional plugins, a space/comma separated arg, (optional)
# Run install-plugin-list with argument "-f" to force install 
#   if the plugin is not compatible with current Moodle version
ARG ARG_MOODLE_PLUGIN_LIST=''
ENV MOODLE_PLUGIN_LIST=${ARG_MOODLE_PLUGIN_LIST}
RUN if [ -n "${MOODLE_PLUGIN_LIST}" ]; then /usr/libexec/moodle/install-plugin-list -p "${MOODLE_PLUGIN_LIST}"; fi && \
    rm -rf /tmp/moodle-plugins

• Since v4.2.1.02-2 (402.102.2), this could be further simplified into:

# Dockerfile.plugins
FROM quay.io/jimsihk/alpine-moodle:latest

# Install additional plugins, a space/comma separated arg, (optional)
ARG ARG_MOODLE_PLUGIN_LIST=''
ENV MOODLE_PLUGIN_LIST=${ARG_MOODLE_PLUGIN_LIST}
RUN /usr/libexec/moodle/download-moodle-plugin

• Example of build using Dockerfile.plugins:

# Build
docker buildx build . -t my_moodle_image:my_tag \
    -f Dockerfile.plugins \
    --build-arg ARG_MOODLE_PLUGIN_LIST='mod_attendance,mod_checklist,mod_customcert,block_checklist,gradeexport_checklist'

⁠ARG_ALLOW_INCOMPATIBLE_PLUGIN: allow installing incompatible plugins

• Since v4.2.1.02-2 (402.102.2), ARG_ALLOW_INCOMPATIBLE_PLUGIN is also available to easily control if continue the installation of latest available version despite lack of compatibility from maturity, default as false:

docker buildx build . -t my_moodle_image:my_tag \
    --build-arg ARG_MOODLE_PLUGIN_LIST='mod_attendance mod_checklist mod_customcert block_checklist gradeexport_checklist' \
    --build-arg ARG_ALLOW_INCOMPATIBLE_PLUGIN='true'

• Or using a custom Dockerfile.plugins:

# Dockerfile.plugins
FROM quay.io/jimsihk/alpine-moodle:latest

ARG ARG_MOODLE_PLUGIN_LIST='mod_attendance mod_checklist mod_customcert block_checklist gradeexport_checklist'
ARG ARG_ALLOW_INCOMPATIBLE_PLUGIN='true'
ENV MOODLE_PLUGIN_LIST=${ARG_MOODLE_PLUGIN_LIST}
ENV ALLOW_INCOMPATIBLE_PLUGIN=${ARG_ALLOW_INCOMPATIBLE_PLUGIN}
RUN /usr/libexec/moodle/download-moodle-plugin

⁠Known Issues

⁠Unable to Create/Update Moodle Roles with "Incorrect role short name" (https://github.com/erseco/alpine-moodle/issues/26⁠)

• Workaround: install Moosh⁠ and use the role-update-capability command, but beware that only version 0.39 of the plugin has this command
• FIXED since release v4.1.2.07-1 (401.207.1)

⁠Credits

• Plugin installation adopted from Krestomatio⁠