erseco/alpine-moodle

Moodle on Alpine Linux

!Docker Image Size !nginx 1.26 !php 8.3 !moodle !moosh 1.27 !License MIT !https://github.com/erseco/alpine-moodle/actions/workflows/build.yml/badge.svg

基于Alpine Linux构建的轻量级Moodle Docker镜像（约100MB）。

仓库地址：https://github.com/erseco/alpine-moodle

核心功能

• 基于轻量级基础镜像构建：https://github.com/erseco/alpine-php-webserver
• Docker镜像体积小巧（约100MB）
• 使用PHP 8.3 FPM提升性能，降低CPU使用率和内存占用
• 包含Composer依赖管理工具
• 支持Moodle <5.1和≥5.1版本（自动检测/public目录）
• 包含Redis会话处理器支持
• 集成https://github.com/tmuras/moosh Moodle管理工具
• 可通过环境变量配置（详见Dockerfile）
• 支持高可用（HA）部署：包含php-redis、php-ldap（支持自签名证书）
• 多架构支持：386、amd64、arm/v6、arm/v7、arm64、ppc64le、s390x
• 针对100个并发用户优化
• 采用PHP-FPM的ondemand进程管理器，仅在有流量时占用资源
• 使用runit替代supervisord，减少内存占用
• 通过runit每180秒运行一次Cron任务
• 提供带PostgreSQL和Redis的示例docker compose.yml
• 通过环境变量进行配置
• Nginx、PHP-FPM服务以非特权用户（nobody）运行，提升安全性
• 日志输出到容器STDOUT（可通过docker logs -f <容器名>查看）
• 可通过预/后配置钩子扩展功能
• 遵循KISS原则（保持简单），便于理解和调整镜像以满足需求

重要注意事项

• 修改默认凭据：务必将MOODLE_USERNAME和MOODLE_PASSWORD覆盖为安全值。
• Moodle ≥ 5.1：脚本会自动重新配置Nginx，从/public目录提供文件服务。
• Moodle < 5.1：会对publicpaths.php应用兼容性补丁，以支持容器内的端口映射。

从Moodle < 5.1升级到≥5.1

Moodle 5.1引入了新的/public目录用于所有Web可访问文件。如果从5.0或更早版本升级：

1. 备份关键数据：
   • config.php
   • moodledata/目录
   • 数据库备份
2. 清理旧文件：删除/var/www/html/下的所有剩余文件，避免陈旧或冲突代码。
3. 恢复配置：将config.php和自定义插件/主题复制到新代码库。
4. 运行依赖安装：当检测到/public目录时，容器会自动执行composer install。

使用方法

从Docker Hub获取：

bash
docker compose up

使用环境变量定义的凭据登录。

从GHCR获取：

yaml
services:
  moodle:
    image: ghcr.io/erseco/alpine-moodle
    # 其余配置...

以Root用户运行命令

在某些情况下，可能需要在Moodle容器内以root用户运行命令（例如安装额外包），可使用docker compose exec命令并指定--user root选项：

bash
docker compose exec --user root moodle sh

配置

在docker compose.yml文件中定义环境变量

反向代理配置

当使用反向代理（如Caddy、Traefik、nginx-proxy-manager）处理SSL终止时，可能会遇到CSS丢失或“重定向过多”错误。这是常见问题，可通过正确配置解决。

问题原因

1. CSS丢失：若SITE_URL设为内部Docker IP（如http://172.19.0.1:89），Moodle会生成带内部地址的URL。当浏览器通过https://moodle.example.com访问时，会因混合内容（尝试加载http内容到https页面）阻止这些资源。

2. ERR_TOO_MANY_REDIRECTS：若SITE_URL设为公共HTTPS地址（如https://moodle.example.com）但未正确配置代理设置，Moodle可能会混淆协议并进入重定向循环。

解决方案

关键是告知Moodle其位于SSL终止代理之后。可通过以下环境变量设置解决：

• SITE_URL：设为公共外部URL，带https协议（如https://moodle.example.com）。
• REVERSEPROXY：大多数反向代理设置保持false。仅当Moodle有意通过多个不同基础URL访问（如用户使用不同域名或协议）时设为true。在典型反向代理场景（所有用户通过单一公共URL访问）中保持false。详见Moodle反向代理文档。
• SSLPROXY：设为true。告知Moodle信任代理发送的X-Forwarded-Proto头，理解连接是安全的（即使与Docker容器的内部连接为HTTP）。

示例配置

以下是docker-compose.yml和Caddyfile的反向代理配置示例。

docker-compose.yml

yaml
services:
  moodle:
    image: erseco/alpine-moodle
    restart: unless-stopped
    environment:
      SITE_URL: https://moodle.example.com
      REVERSEPROXY: "false"
      SSLPROXY: "true"
      # ... 其他环境变量
    volumes:
      - moodledata:/var/www/moodledata
      - moodlehtml:/var/www/html
    depends_on:
      - postgres

  # ... 其他服务（postgres等）

volumes:
  moodledata:
  moodlehtml:

Caddyfile

caddy
moodle.example.com {
    reverse_proxy moodle:8080 {
        header_up Host {host}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-For {remote}
    }
}

通过此配置可避免Moodle在反向代理后的常见问题。详见issue https://github.com/erseco/alpine-moodle/issues/101%E3%80%82

最小化docker-compose.yml示例

yaml
---
services:
  postgres:
    image: postgres:alpine
    restart: unless-stopped
    environment:
      - POSTGRES_PASSWORD=moodle
      - POSTGRES_USER=moodle
      - POSTGRES_DB=moodle
    volumes:
      - postgres:/var/lib/postgresql/data
  moodle:
    image: erseco/alpine-moodle
    restart: unless-stopped
    environment:
      MOODLE_USERNAME: moodleuser
      MOODLE_PASSWORD: PLEASE_CHANGEME
    ports:
      - 80:8080
    volumes:
      - moodledata:/var/www/moodledata
      - moodlehtml:/var/www/html
    depends_on:
      - postgres
volumes:
  postgres: null
  moodledata: null
  moodlehtml: null

高级功能

1. 使用Moosh CLI

此镜像包含https://github.com/tmuras/moosh%E2%80%94%E2%80%94%E5%BC%BA%E5%A4%A7%E7%9A%84Moodle%E7%AE%A1%E7%90%86%E5%91%BD%E4%BB%A4%E8%A1%8C%E5%B7%A5%E5%85%B7%E3%80%82%E5%8F%AF%E9%80%9A%E8%BF%87%E4%BB%A5%E4%B8%8B%E5%91%BD%E4%BB%A4%E8%B0%83%E7%94%A8%E4%BB%BB%E4%BD%95Moosh%E5%91%BD%E4%BB%A4%EF%BC%9A

bash
docker compose exec moodle moosh <命令>

示例：

升级插件列表（安装前需执行）

bash
docker compose exec moodle moosh plugin-list

按名称安装插件

bash
docker compose exec moodle moosh plugin-install mod_attendance

可使用--force选项强制安装不支持的插件。

注意：https://github.com/tmuras/moosh/issues/520%EF%BC%8C%E5%BB%BA%E8%AE%AE%E4%BD%BF%E7%94%A8%60--delete%60%E6%A0%87%E5%BF%97%E9%87%8D%E6%96%B0%E8%B0%83%E7%94%A8%E5%AE%89%E8%A3%85%E5%87%BD%E6%95%B0%E6%88%96%E4%BD%BF%E7%94%A8%60module-reinstall%60%E9%80%89%E9%A1%B9%EF%BC%8C%E4%BE%8B%E5%A6%82%EF%BC%9A%60docker compose exec moodle moosh plugin-install --delete theme_almondb或docker compose exec moodle moosh module-reinstall theme_almondb`

备份课程

按ID备份课程。默认排除日志和成绩历史。

示例：备份ID=3的课程到容器内/opt/moosh/目录的默认.mbz文件：

bash
docker compose exec moodle moosh course-backup 3

创建用户

创建新Moodle用户。提供一个或多个参数可创建多个用户。

示例：创建用户“testuser”并设置所有可选值

bash
docker compose exec moodle moosh user-create --password pass --email me@example.com --digest 2 --city Valverde --country ES --institution "IES Garoé" --department "Technology" --firstname "first name" --lastname name testuser

删除用户

从Moodle删除用户。提供一个或多个用户名为参数。

示例：删除用户testuser

bash
docker compose exec moodle moosh user-delete testuser

这些示例可直接包含在POST_CONFIGURE_COMMANDS中，以自动化插件安装、备份或任何Moosh支持的功能。

使用Moosh可遵循DRY原则（避免重复），并利用强大的Moodle管理工具集。

完整命令列表见：[***]

2. 预/后配置钩子

可通过PRE_CONFIGURE_COMMANDS和POST_CONFIGURE_COMMANDS环境变量定义在Moodle配置前后执行的命令。适用于安装额外包或运行脚本等任务。

yaml
environment:
  PRE_CONFIGURE_COMMANDS: "cat config-dist.php"
  POST_CONFIGURE_COMMANDS: |
    moosh plugin-list
    moosh plugin-install --delete theme_almondb
    moosh plugin-install --delete theme_almondb

3. 指定Moodle版本

调用docker compose build会使用Moodle主分支的最新版本。如需使用特定版本，可通过MOODLE_VERSION构建参数指定。

要使用特定版本，编辑docker compose.yml中moodle服务的build部分：

yaml
moodle:
  image: erseco/alpine-moodle
  build:
    context: .
    args:
      MOODLE_VERSION: v4.5.3  # 替换为所需版本

可用版本标签列表见：https://github.com/moodle/moodle/tags

4. 启用测试场景生成器

Moodle在管理员 > 开发 > 创建测试场景下提供测试场景生成工具。要启用它，运行以下命令或添加到POST_CONFIGURE_COMMANDS：

bash
php admin/tool/generator/cli/runtestscenario.php

此工具允许使用.feature文件语法生成手动测试所需的所有元素。

维护提示

安装额外Alpine包（以root用户）：

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

手动数据库升级：

bash
docker compose exec moodle php admin/cli/upgrade.php

访问日志：

bash
docker compose logs -f moodle