Materia

Materia is a platform and ecosystem for small, self-contained, customizable e-learning applications called widgets, designed to enhance digital course content. Widgets in the catalog can be customized by instructors to suit their instructional goals and objectives, then shared with students directly or embedded in an LMS through LTI.

Materia and its associated library of widgets is an open-source project of the University of Central Florida's Center for Distributed Learning.

View the Materia Docs for info on installing, using, and developing Materia and widgets.

Join UCF Open Slack Discussions

Using Materia at Your Institution

It's important to note that UCF maintains an instance of Materia for the UCF community, but it cannot grant access to users of other institutions. External institutions are welcome to host their own copy of Materia, and interested parties should contact their IT and distance learning department(s) about making Materia available to their students. We also welcome questions and inquiries on the UCF Open Slack discussion linked above.

Widgets & Associated Repositories

While casual references to Materia typically involve both the platform and its associated ecosystem of widgets, this repository only includes the Materia platform itself. Additional open-source repositories associated with Materia include:

• Most first-party widgets authored by UCF. These can be found by searching for "widget" under the UCFOpen GitHub organization or visiting the Materia Widget Gallery.
• The Materia Widget Developer Kit (MWDK). This is a required dependency of all widgets and includes a built-in express server and webpack configs for rapid in-situ development of widgets.
• Materia-Theme-UCF. This is a FuelPHP module that allows for overrides of certain views (login, help pages) with institution-specific variants.

Installation

Materia is configured to use docker containers in production environments, orchestrated through docker compose, though other orchestration frameworks could potentially be used instead. While it may be possible to deploy Materia without docker, we do not recommend doing so.

Docker Deployment

Refer to the Materia docker readme for a full breakdown of Materia's docker configuration and deployment in both development and production.

Configuration

Materia uses environment variables to facilitate application and webserver configuration. These are typically sourced from .env or .env.local files on the host machine that are volume mounted into their associated containers.

Visit docker README as well as the Server Variables page on our docs site for information about configuration through environment variables. The root env file serves as a configuration template for production instances of Materia.

Setup

Materia provides a pair of setup scripts for out-of-the-box deployment based on two different use cases:

1. run_first_for_dev.sh sets up and configures your local instance of Materia for development. This includes additional volume mounts for project files and makes use of additional containers for mysql, s3, and memcached.
2. run_first_for_nondev.sh is ideal for users who just want to explore Materia locally and potentially transition to a production instance. The script dynamically configures the override compose file based on selections you make in the script.

Note

yq is required for the nondev script. This may come preinstalled in some OS distributions but you should ensure the correct version is installed. Consult the yq installation guide for more info.

In either case, first-time setup involves the following:

git clone https://github.com/ucfopen/Materia.git
cd Materia/docker

Followed by either:

./run_first_for_dev.sh

For local development or

./run_first_for_nondev.sh

For creating a local instance where development is not desired.

The run_first scripts only have 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 volumes 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://localhost by default.

Note that Materia uses a self-signed certificate to facilitate https traffic locally. Your browser may require security exceptions for your application on ports 443 and 8008 (if setup for local development).

Note

If local development of static assets (JS and CSS) is desired, run yarn dev in a separate terminal window to enable the webpack dev server and live reloading. This requires node and yarn to be installed on the host machine.

Creating additional users

See the wiki page for Creating a local user.

Running Tests

Tests run in the docker environment to maintain consistency. View the run_tests_*.sh scripts in the docker directory for options.

Git Hooks

There is a pre-commit hook available to ensure your code follows our linting standards. Check out the comments contained inside the hook files (in the githooks directory) to install it, you may need a few dependencies installed to get linting working.

Contributing

Code contributors should review the CONTRIBUTING document before proceeding.

Authentication

Materia supports two forms of authentication:

• Direct authentication through direct logins. Note that Materia does not provide an out-of-the-box tool for user generation. If your goal is to connect to an external identity management platform or service, you will need to author an authentication module to support this. Review FuelPHP's Auth package and Login driver documentation, as well as the ltiauth and materiaauth packages located in fuel/packages to get started.
• Authentication over LTI. This is the more out-of-the-box solution for user management and authentication. In fact, you can disable direct authentication altogether through the BOOL_LTI_RESTRICT_LOGINS_TO_LAUNCHES environment variable, making LTI authentication the only way to access Materia. Visit our LTI Integration Overview page on the docs site for more information.

Asset Storage

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 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)

Note

Note that fakes3 asset storage is disabled when FUEL_ENV is set to production.

Widget Management

A default list of widgets will be installed as part of the first-time setup process, but the widget ecosystem has many more! Peruse the Materia Widget Gallery to view additional widgets to install.

Installing Widgets

Widgets can be installed in one of two ways:

1. A user with the super_user role can visit the Widget Admin panel by navigating to your.materia.url/admin/widget or by selecting the orange "Admin" button at the top. Select a .wigt file from the file upload dialog to install it.
2. Widgets can be installed from the cli on the application container once running:

$ docker exec -it <container name or id> sh
$ wget url/for/materia/widget.wigt
$ php oil r widget:install widget.wigt

The .wigt files do not need to be retained once a widget is installed.

Theming

Theme overrides are facilitated through FuelPHP packages, installed via composer. Materia ships with Materia-Theme-UCF by default.

Review the repository README for Materia-Theme-UCF for a breakdown of using theme overrides in Materia 10.x and later.

Transitioning to Production

More information about creating a production-capable Materia instance can be found in the Materia Docker Readme.