Allow specification of DocumentRoot with intelligent fallback

Author: andrewnicols

.github/workflows/test_buildx_and_publish.yml

@@ -25,7 +25,7 @@ jobs:
       - name: Run tests
         run: |
           docker run --name test0 -d -p 8000:80 \
-              -v $PWD/tests/fixtures:/var/www/html \
+              -v $PWD/tests/fixtures/entrypoint:/var/www/html \
               -v $PWD/tests/docker-entrypoint.d:/docker-entrypoint.d \
               -e PHP_INI-memory_limit=256M \
               -e PHP_INI-apc.enabled=0 \
@@ -40,14 +40,45 @@ jobs:
           curl --fail http://127.0.0.1:8000/test.php
           curl --fail http://127.0.0.1:8000/check-ini.php
 
+          # Test the default DocumentRoot when it contains a public directory.
+          docker run --name test1 -d -p 8002:80 \
+              -v $PWD/tests/fixtures/documentroot:/var/www/html \
+              moodle-php-apache
+          sleep 1 # Wait for the server to start
+          # Test the DocumentRoot when it contains a public directory.
+          curl --fail http://127.0.0.1:8002/test.php
+
+          # Test the DocumentRoot when it does not contain a public directory.
+          docker run --name test2 -d -p 8003:80 \
+              -v $PWD/tests/fixtures/documentroot/public:/var/www/html \
+              moodle-php-apache
+          sleep 1 # Wait for the server to start
+          curl --fail http://127.0.0.1:8003/test.php
+
+          # Test the DocumentRoot when it is has been overridden and contains a public directory.
+          docker run --name test3 -d -p 8004:80 \
+              -v $PWD/tests/fixtures/documentroot:/srv/moodle \
+              -e APACHE_DOCUMENT_ROOT=/srv/moodle \
+              moodle-php-apache
+          sleep 1 # Wait for the server to start
+          curl --fail http://127.0.0.1:8004/notpublic.php
+
+          # Test the DocumentRoot is not guessed when it has been overriden and does not contain a public directory.
+          docker run --name test4 -d -p 8005:80 \
+              -v $PWD/tests/fixtures/documentroot/public:/srv/moodle \
+              -e APACHE_DOCUMENT_ROOT=/srv/moodle \
+              moodle-php-apache
+          sleep 1 # Wait for the server to start
+          curl --fail http://127.0.0.1:8005/test.php
+
       - name: Display container logs on failure
         if: failure()
         run: |
           docker logs test0
-
-      - name: Cleanup docker images
-        run: |
-          docker rm -f test0
+          docker logs test1
+          docker logs test2
+          docker logs test3
+          docker logs test4
 
   Publish:
     # Completely avoid forks and pull requests to try this job.

Dockerfile

@@ -46,9 +46,19 @@ RUN mkdir /var/www/moodledata && chown www-data /var/www/moodledata && \
 
 ADD root/usr /usr
 ADD root/etc /etc
+ADD root/system-docker-entrypoint.d/wwwroot.sh /system-docker-entrypoint.d/10-wwwroot.sh
 
 # Fix the original permissions of /tmp, the PHP default upload tmp dir.
 RUN chmod 777 /tmp && chmod +t /tmp
 
+# Allow configuration of the Apache DocumentRoot via environment variable.
+# Note: Do not specify a default value here, as it will be set in the
+#       `wwwroot.sh` script, which will be run before the Apache server starts.
+#       This allows the user to override the default value by setting the
+#       `APACHE_DOCUMENT_ROOT` environment variable when running the container.
+
+RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/sites-available/*.conf
+RUN sed -ri -e 's!/var/www/!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf
+
 CMD ["apache2-foreground"]
 ENTRYPOINT ["moodle-docker-php-entrypoint"]

README.md

@@ -11,22 +11,62 @@ A Moodle PHP environment configured for Moodle development based on [Official PH
 For a complete list of supported versions, look to the [master README](https://github.com/moodlehq/moodle-php-apache/tree/master).
 
 ## Example usage
+
 The following command will expose the current working directory on port 8080:
 ```bash
 $ docker run --name web0 -p 8080:80  -v $PWD:/var/www/html moodlehq/moodle-php-apache:7.1
 ```
 
 ## Features
+
 * Preconfigured with all php extensions required for Moodle development and all database drivers
-* Serves wwroot configured at /var/www/html/
+* Serves content from `/var/www/html` or `/var/www/html/public` (for Moodle 5.1 onwards) by default.
+* Document root can be overridden
 * For PHP 7.3 and up, both `linux/amd64` and `linux/arm64` images are being built. Note that `linux/arm64` doesn't support the sqlsrv and oci extensions yet. Other than that, both architectures work exactly the same.
 * Verified by [automated tests](https://travis-ci.com/moodlehq/moodle-php-apache).
 * Autobuilt from GHA, on push.
 * Support for entrypoint scripts and PHP Configuration
 * Many common extensions available
 * Note that PHP 8.4 images do not include oci extensions as these are no longer supported by Moodle 5.0 onwards.
 
+## Configuration
+
+### Apache Configuration
+
+This image makes use of the Apache HTTPD server to serve all content. It requires minimal manual configuration.
+
+The Apache `DocumentRoot` directive can be configured using the `APACHE_DOCUMENT_ROOT` environment variable, for example:
+
+```bash
+docker run \
+    --name web0 \
+    -p 8080:80 \
+    -v $PWD/moodle:/srv/moodle
+    -e APACHE_DOCUMENT_ROOT=/srv/moodle \
+    moodle-php-apache:latest
+```
+
+Note: Specifying a `DocumentRoot` will override the default root, and will prevent the ability for the image to automatically configure any Moodle-specific configuration.
+
+### PHP Configuration
+
+As a lightweight alternative to a full PHP configuration file, you can specify a set of prefixed environment variables when starting your container with these variables turned into ini-format configuration.
+
+Any environment variable whose name is prefixed with `PHP_INI-` will have the prefix removed, and will be added to a new ini file before the main command starts.
+
+```bash
+docker run \
+    --name web0 \
+    -p 8080:80 \
+    -v $PWD/moodle:/var/www/html
+    -e PHP_INI-upload_max_filesize=200M \
+    -e PHP_INI-post_max_size=210M \
+    moodle-php-apache:latest
+```
+
+
 ## Directories
+
 To facilitate testing and easy setup the following directories are created and owned by www-data by default:
 
 * `/var/www/moodledata`
@@ -36,9 +76,19 @@ To facilitate testing and easy setup the following directories are created and o
 
 ## Initialisation scripts
 
-If you would like to do additional initialization, you can add one or more `*.sh`, or `*.ini`  scripts under `/docker-entrypoint.d` (creating the directory if necessary). When the entrypoint script is called, it will run any executable `*.sh` script, source any non-executable `*.sh` scripts found in that directory, and will copy any `*.ini` scripts into the PHP Configuration directory (`/usr/local/etc/php/conf.d`).
+This image supports custom initialisation scripts using the the `docker-entrypoint.d` directory. These may be in the following formats:
+
+* a non-executable `.sh` script, which will be _sourced_ and alter the current context;
+* an executable `.sh` script, which will be _executed_ in the current context;
+* a `.ini` file. which will be copied into the PHP Configuration directory (`/usr/local/etc/php/conf.d`.)
 
-For example, to configure PHP to support a higher `upload_max_filesize` option you might add the following to a `config/10-uploads.ini` file:
+The following scripts are included as standard:
+
+* `10-wwwroot.sh` - a non-executable script used to guess the `APACHE_DOCUMENT_ROOT` if one is not provided.
+
+These scripts cannot be removed, but may be disabled by creating a file with a matching file name in your own `docker-entrypoint.d` location.
+
+Other scripts may also be provided, for example, to configure PHP to support a higher `upload_max_filesize` option you might add the following to a `config/10-uploads.ini` file:
 
 ```
 ; Specify a max filesize of 200M for uploads.
@@ -59,22 +109,6 @@ docker run \
 
 These initialization files will be executed in sorted name order as defined by the current locale, which defaults to en_US.utf8.
 
-## PHP Configuration
-
-As a lightweight alternative to a full PHP configuration file, you can specify a set of prefixed environment variables when starting your container with these variables turned into ini-format configuration.
-
-Any environment variable whose name is prefixed with `PHP_INI-` will have the prefix removed, and will be added to a new ini file before the main command starts.
-
-```
-docker run \
-    --name web0 \
-    -p 8080:80 \
-    -v $PWD/moodle:/var/www/html
-    -e PHP_INI-upload_max_filesize=200M \
-    -e PHP_INI-post_max_size=210M \
-    moodle-php-apache:latest
-```
-
 ## Extensions
 
 The following extensions are included as standard:

root/system-docker-entrypoint.d/wwwroot.sh

@@ -0,0 +1,27 @@
+echo
+echo "#######################################"
+echo "# moodle-php-apache wwwroot setup"
+echo "#######################################"
+echo "#"
+echo "# Setting up Apache DocumentRoot"
+
+if [ -z "$APACHE_DOCUMENT_ROOT" ]; then
+    echo "# No value set for \$APACHE_DOCUMENT_ROOT. Creating default value."
+    export APACHE_DOCUMENT_ROOT=/var/www/html
+
+    if [ -d "$APACHE_DOCUMENT_ROOT/public" ]; then
+        echo "# Detected /public directory."
+        echo "# Using /var/www/html/public"
+        export APACHE_DOCUMENT_ROOT="$APACHE_DOCUMENT_ROOT/public"
+    else
+        echo "# Using default Apache DocumentRoot: /var/www/html"
+    fi
+
+else
+    echo "# A value was provided as an environment variable"
+fi
+
+echo "# \$APACHE_DOCUMENT_ROOT: $APACHE_DOCUMENT_ROOT"
+echo "#"
+echo "#######################################"
+echo

root/usr/local/bin/moodle-docker-php-entrypoint

@@ -19,6 +19,11 @@ docker_process_init_files() {
           . "$f"
         fi
         ;;
+      *.conf)
+        echo "$0: copying $f into /etc/apache2/conf-enabled/"
+        cp "$f" /etc/apache2/conf-enabled/
+        a2enconf "$(basename "$f")"
+        ;;
       *.ini)
         echo "$0: copying $f into /usr/local/etc/php/conf.d/"
         cp "$f" /usr/local/etc/php/conf.d/
@@ -31,8 +36,16 @@ echo "Running PHP Configuration fetcher"
 /usr/local/bin/moodle-docker-php-ini
 echo
 
-echo "Running entrypoint files from /docker-entrypoint.d/*"
-docker_process_init_files /docker-entrypoint.d/*
+mkdir -p /system-docker-entrypoint.d  /docker-entrypoint.d /final-docker-entrypoint.d
+echo "Building Entrypoint files from /system-docker-entrypoint.d/* and /docker-entrypoint.d/*"
+
+echo "Copying /system-docker-entrypoint.d/* to /final-docker-entrypoint.d/"
+cp -rf /system-docker-entrypoint.d/* /final-docker-entrypoint.d/ || true
+echo "Copying /docker-entrypoint.d/* to /final-docker-entrypoint.d/"
+cp -rf /docker-entrypoint.d/* /final-docker-entrypoint.d/ || true
+
+echo "Running entrypoint files from /final-docker-entrypoint.d/*"
+docker_process_init_files /final-docker-entrypoint.d/*
 echo
 
 echo "Starting docker-php-entrypoint with $@"

tests/fixtures/documentroot/notpublic.php

@@ -0,0 +1,3 @@
+<?php
+
+header('HTTP/1.1 200 - OK');

tests/fixtures/documentroot/public/test.php

@@ -0,0 +1,3 @@
+<?php
+
+header('HTTP/1.1 200 - OK');