Merge branch 'dev/10.3.0' into issue/1607-retire-cookie-class

.env

@@ -11,7 +11,7 @@
 # Only `BOOL_` options become boolean values, and ONLY `true` evaluates to true
 #
 # Docker/Dev notes:
-# docker/config/materia-docker.env.local is loaded instead of .env.local
+# docker/.env.local is used instead of .env.local
 
 # GENERAL ===================
 
@@ -34,12 +34,17 @@ BOOL_SEND_EMAILS=false
 #URLS_STATIC=
 #URLS_ENGINES=
 #BOOL_ADMIN_UPLOADER_ENABLE=true
-#ASSET_STORAGE_DRIVER=file
-#ASSET_STORAGE_S3_REGION=us-east-1
-#ASSET_STORAGE_S3_BUCKET=
-#ASSET_STORAGE_S3_BASEPATH=
-#ASSET_STORAGE_S3_KEY=
-#ASSET_STORAGE_S3_SECRET=
+ASSET_STORAGE_DRIVER=file # file | s3 | db (db not recommended)
+
+# AWS S3 ===================
+
+# ASSET_STORAGE_S3_REGION=us-east-1
+# ASSET_STORAGE_S3_BASEPATH=media
+# ASSET_STORAGE_S3_BUCKET=<MUST_SET>
+# ASSET_STORAGE_S3_ENDPOINT= # endpoint not required for S3 on AWS
+# AWS_ACCESS_KEY_ID=<MUST_SET>
+# AWS_SECRET_ACCESS_KEY=<MUST_SET>
+# AWS_SESSION_TOKEN=<MUST_SET> # STS token for s3 development
 
 # SESSION & CACHE ===================
 
@@ -88,3 +93,14 @@ LTI_KEY="materia-production-lti-key"
 #BOOL_LTI_USE_LAUNCH_ROLES=true
 #BOOL_LTI_GRACEFUL_CONFIG_FALLBACK=true
 #BOOL_LTI_LOG_FOR_DEBUGGING=false
+
+# Question Generation ===
+
+#GENERATION_ENABLED=true
+#GENERATION_ALLOW_IMAGES=false
+#GENERATION_API_PROVIDER=<MUST_SET>
+#GENERATION_API_ENDPOINT=
+#GENERATION_API_KEY=
+#GENERATION_API_VERSION=
+#GENERATION_API_MODEL=
+#GENERATION_LOG_STATS=true

.github/workflows/test_and_build.yml

@@ -29,10 +29,17 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v2
 
+      - name: Create .env.local to satisfy build requirements
+        run: |
+          cd docker
+          if [ ! -f .env.local ]; then
+            touch .env.local
+          fi
+
       - name: Build App Image
         run: |
           cd docker
-          docker-compose build --no-cache webserver app
+          docker compose build --no-cache webserver app
 
       - name: Push App Images
         run: |

.gitignore

@@ -85,6 +85,7 @@ public/js/materia.storage.table.js
 public/js/student.js
 public/js/vendor/*
 
+public/openai_usage.txt
 
 # Installed Widgets
 public/widget

README.md

@@ -48,11 +48,11 @@ cd Materia/docker
 ./run_first.sh
 ```
 
-The `run_first.sh` script only has to be run once for initial setup. Afterwards, your local copy will persist in a docker volume unless you explicitly use `docker-compose down` or delete the volume manually.
+The `run_first.sh` script only has to be run once for initial setup. Afterwards, your local copy will persist in a docker volume unless you explicitly use `docker compose down` or delete the volume manually.
 
-Use `docker-compose up` to run your local instance. The compose process must persist to keep the application alive. Materia is configured to run at `https://127.0.0.1` by default.
+Use `docker compose up` to run your local instance. The compose process must persist to keep the application alive. Materia is configured to run at `https://127.0.0.1` by default.
 
-In a separate terminal window, run `yarn dev` to enable the webpack dev server and live reloading while making changes to JS and CSS assets. 
+In a separate terminal window, run `yarn dev` to enable the webpack dev server and live reloading while making changes to JS and CSS assets.
 
 Note that Materia uses a self-signed certificate to facilitate https traffic locally. Your browser may require security exceptions for both `127.0.0.1:443` and `127.0.0.1:8008`.
 
@@ -89,4 +89,23 @@ Materia supports two forms of authentication:
 
 ## Asset Storage
 
-Materia enables users to upload media assets for their widgets, including images and audio. There are two asset storage drivers available out of the box: `file` and `db`. `file` is the default asset storage driver, which can be explicitly set via the `ASSET_STORAGE_DRIVER` environment variable.
+Users can upload media assets (images and audio) for use in their widgets, facilitated through a media importer that is provided by Materia itself. Asset storage drivers include:
+
+- `file`: Assets are stored on the local filesystem of the application. It is recommended that assets are backed up and synced with an external storage solution (such as S3) to ensure the files persist across application instances.
+- `s3`: Files are uploaded to and requested directly from AWS S3. This is the most straightforward and recommended storage driver option. Be sure to consult the [Materia Docker Readme](docker/README.md) for additional environment variables associated with using S3.
+- `db`: This storage driver stores asset binaries directly in the database. This option allows Materia to run on cloud hosting options with very limited storage volumes. The `db` storage driver option is not recommended for general use.
+
+> [!WARNING]
+> The `db` asset storage driver option is deprecated and will be removed in the next major version of Materia.
+
+The storage driver is configured via the `ASSET_STORAGE_DRIVER` environment variable.
+
+### Local Asset Storage With S3
+
+A `fakes3` container is instantiated as part of the default development stack and the `ASSET_STORAGE_DRIVER` environment variable is set to `s3` by default in the development `.env` file located in `docker/.env`. When using `fakes3`, this is all that is required to simulate S3 usage locally.
+
+To use an actual S3 bucket for local dev:
+
+1. Set `DEV_ONLY_FAKES3_DISABLED` environment variable in `docker/.env` to `true`
+2. Set `ASSET_STORAGE_S3_BUCKET` to your bucket name
+3. Set `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` in `.env.local`. (Tip: You can run `aws configure export-credentials --profile YOUR_PROFILE_NAME --format env-no-export` to get these)

composer.json

@@ -50,9 +50,10 @@
         "phpseclib/phpseclib": "~3.0",
 		"phpseclib/phpseclib2_compat":"~1.0",
         "eher/oauth": "1.0.7",
-        "aws/aws-sdk-php": "3.288.1",
+        "aws/aws-sdk-php": "^3.314",
         "symfony/dotenv": "^5.1",
-        "ucfopen/materia-theme-ucf": "2.0.3"
+        "ucfopen/materia-theme-ucf": "2.0.4",
+        "openai-php/client": "^0.8.5"
     },
     "suggest": {
         "ext-memcached": "*"
@@ -99,9 +100,9 @@
             "package": {
                 "name": "ucfopen/materia-theme-ucf",
                 "type": "fuel-package",
-                "version": "2.0.3",
+                "version": "2.0.4",
                 "dist": {
-                    "url": "https://github.com/ucfopen/Materia-Theme-UCF/archive/refs/tags/v2.0.3.zip",
+                    "url": "https://github.com/ucfopen/Materia-Theme-UCF/archive/refs/tags/v2.0.4.zip",
                     "type": "zip"
                 },
                 "source": {
@@ -114,5 +115,14 @@
         }
     ],
     "minimum-stability": "dev",
-    "prefer-stable": true
+    "prefer-stable": true,
+    "autoload": {
+        "psr-0": {
+            "": "*"
+        },
+        "psr-4": {
+            "S3\\": "../s3/",
+            "AwsUtilities\\": "../aws_utilities/"
+        }
+    }
 }