Materia

Setting up Server Variables

Using environment variables for configuration

Why Environment Variables?

Server variables are configured outside of the server application itself - why? Because direct modifications to configuration files in PHP would only persist for as long as that particular container is in service, unless you are using a private image with those changes baked in. That’s difficult to recommend, because it would likely require committing sensitive information to a git repository, which is never a good idea.

With environment variables, we can ensure server configurations are present and persistent on the host machine and written to the containers by way of docker compose. You have a number of available options for where to write these environment variables. We recommend a .env or .env.local file.

Note: It is crucial that you don’t expose phpinfo() pages to the web. It will display your secrets! In development mode, Materia exposes /dev/php-info! Make absolutely sure FUEL_ENV is set to production when building your production instance.

Where to Write Your Environment Variables

Configure Using .env

This is the most common and recommended approach. If you cloned Materia and used the nondev setup script, preconfigured environment variables will be present in docker/.env, and custom values written to .env.local. In a production environment, we recommend using a single .env file.

In the Materia repository, the root .env file can serve as a template for your own copy of .env.

Regardless of your .env file naming scheme, ensure your docker compose file imports them appropriately:

app:
  env_file:
    - .env

Multiple .env files can be referenced as well. Values in later imports take precedence:

app:
  env_file:
    - .env
	- .env.local

Note: Take extra care to make sure your .env file(s) are not accessible from the web.

Configure Using NGINX

You can set php environment variables in your NGINX config using the fastcgi_param option.

location ~ ^/index.php$ {
    fastcgi_pass  127.0.0.1:9000;
    #... clip ...

    # HERE!
    fastcgi_param FUEL_ENV development;

    # OR in this file
    include fastcgi_params;
}

Environment Variables Reference

The config key below shows all of the available environment variables.

Note: only BOOL_ options become boolean values. And ONLY true evaluates to true.

FUEL_ENV=production

String. Must be set. Sets the FuelPHP environment. Options are development or production. In any public-facing instance of Materia, this must be set to production.

MYSQL_USER=
MYSQL_PASSWORD=
MYSQL_DATABASE=materia
DATABASE_URL=mysql://${MYSQL_USER}:${MYSQL_PASSWORD}@mysql/${MYSQL_DATABASE}

String(s). DATABASE_URL must be set. DATABASE_URL is the most important value here: MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DATABASE are not explicitly referenced by the application but can be used to populate the value of DATABASE_URL using the syntax provided above. Alternatively, you can use DATABASE_URL exclusively with hard-coded username, password, and database values.

Note that in instances where a mysql container is in service, the MYSQL_USER, MYSQL_PASSWORD, and MYSQL_DATABASE values should be provided. We do not recommend using a mysql container in production instances.

BOOL_SEND_EMAILS=false

Boolean. Determines whether the system should send email notifications when users share, modify, or revoke widget access with other users.

SYSTEM_EMAIL=

String. Must be set. Sets the system email (where email notifications will be sent from).

FUEL_LOCAL=en_US.UTF-8

String. Sets PHP localization. Defaults to en_US.UTF-8 if not explicitly set here.

FUEL_ALWAYS_LOAD_PACKAGES="orm,auth,materiaauth,ltiauth"

String. Comma-delineated values. Tells FuelPHP what module packages to load. Defaults to orm,auth,materiaauth,ltiauth if unset. Two instances where you may be using additional module packages:

  1. You are using a custom authentication module.
  2. You are using a custom theme module.
FUEL_ALWAYS_LOAD_MODULES=""

String. Comma-delineated values. Tells FuelPHP what modules to load. You will likely be using the packages configuration instead; this value is not generally used.

GOOGLE_ANALYTICS_ID=

String. Hash. If you have a google analytics ID, you can enter it here.

FUEL_LOG_THRESHOLD=300

Integer. Sets the logging threshold for FuelPHP. Refer to FuelPHP’s Log Constants configuration documentation.

LOG_HANDLER=DEFAULT

String. Constant. Defines a custom log handler. This is an advanced FuelPHP configuration. Default is DEFAULT; this will write logs to fuel/app/logs/. STDOUT is preferable for development to ensure logs are captured in the compose log stream.

URLS_STATIC=
URLS_ENGINES=

String(s). Defines the values used to construct asset URL paths. For more information about how to configure these, visit domain name requirements.

BOOL_ADMIN_UPLOADER_ENABLE=true

Boolean. Determines whether the widget admin panel UI allows widget engine file uploads. The widget admin panel is only visible to users with the super_user role. We generally recommend using a single dedicated service user with super_user. Widget uploads will always be available through PHP oil commands in the shell. Defaults to true.

ASSET_STORAGE_DRIVER=file

String. Specifies the FuelPHP storage driver for assets. Options are file, s3, or db. Defaults to file.

Specifies the method of asset storage for your instance of Materia. The vast majority of users will want file, which stores user-uploaded media in the filesystem of the application container and, if properly configured, this media directory is volume-mounted from the host machine.

We provide s3 as an asset storage solution for users with the ability to leverage infrastructure on AWS. While our implementation is S3-specific, it should be feasible to create analogous storage driver solutions for other cloud hosting providers. Note that proper configuration of S3 storage requires a number of additional configuration values to be set, which are detailed below. When the S3 storage driver is in use, media urls will continue to utilize the static asset URLs as defined: the server application will perform the requests to AWS S3 directly, create the image file in memory, and serve it to the client.

The db asset storage driver instead stores asset binaries within the database’s asset_data table. This storage driver solution is primarily meant for use with low-cost cloud hosting solutions with minimal disk space allotments. It is not intended for use at scale.

We strongly advise against using the db storage driver solution. It will be completely removed in the next major version of Materia!

ASSET_STORAGE_S3_CREDENTIAL_PROVIDER=
ASSET_STORAGE_S3_BUCKET=
ASSET_STORAGE_S3_ENDPOINT=
ASSET_STORAGE_S3_KEY=
ASSET_STORAGE_S3_SECRET=
ASSET_STORAGE_S3_REGION=
ASSET_STORAGE_S3_BASEPATH=
AWS_SESSION_TOKEN=

Strings. These values are only required if your ASSET_STORAGE_DRIVER configuration is set to s3. Let’s run through each.

CACHE_DRIVER=file

String. Sets the server cache driver. Options are file or memcached. Defaults to file if not set. If using memcached, additional configuration values are required, as detailed below.

MEMCACHED_HOST=localhost
MEMCACHED_PORT=11211

Used when CACHE_DRIVER is memcached:

Note that our recommended implementation of memcached uses a dedicated docker container alongside the app and webserver containers. Additions to your docker compose file are required.

SESSION_DRIVER=file

String. Sets the session driver for the Materia server application. Acceptable values are memcached, file, or db. Defaults to file if not set. Using memcached requires additions to your docker compose file.

SESSION_EXPIRATION=21600

Integer. Sets the expiration of server sessions. Defaults to 21600 if not set.

THEME_ACTIVE=default
THEME_PACKAGE=materia-theme-ucf

Strings. Sets the FuelPHP theme. Themes allow for deep customization of pages in FuelPHP.

Theming in FuelPHP became considerably more complex after Materia v10, as page content is entirely rendered on the client. We acknowledge that theming is not ideal currently, and will be working to make it easier to extend and customize in the future.

AUTH_DRIVERS=Materiaauth

String. Sets the auth driver for the application. Defaults to Materiaauth if not set. The built-in Materia auth is sufficient for the creation and management of service user accounts; it is insufficient for user management at scale. Users may extend the capability of Materiaauth by prepending authentication through an external service such as SAML. In such cases, successful authentications can then provide various attributes from a SAML payload which are then used to create or update records in the database. Bear in mind we do not provide this sort of authentication solution out of the box.

AUTH_SALT=
AUTH_SIMPLEAUTH_SALT=

Strings. Hashes. Must be set. These are the salt values used for password authentication. These values must be properly generated and unique.

You can use the following php shell command to generate valid salt hashes locally. This can be performed within the app container shell environment:

php -r "echo(sodium_bin2hex(random_bytes(SODIUM_CRYPTO_STREAM_KEYBYTES)));"

USER_SYSTEM_PASSWORD=
USER_INSTRUCTOR_PASSWORD=
USER_STUDENT_PASSWORD=

Strings. Configure the password for the default system users (~materia_system_only, ~author, ~student). These are only used if the create_default_users FuelPHP oil task is run, which is intended for development. These accounts will not be generated in a production environment unless the oil task is run manually. Generally speaking, we do not advise you run this task in production. Create your own service user accounts manually instead.

CIPHER_KEY=
CRYPTO_KEY=
CRYPTO_IV=
CRYPTO_HMAC=

Strings. Hashes. Sets the cryptographic keys used for authentication. CIPHER_KEY is used for contemporary cryptography with Sodium; the CRYPTO_ values are used for legacy cryptography with PHPSecLib. Consult the FuelPHP Crypt class config documentation for more info.

LTI_KEY=
LTI_SECRET=
LTI_GUID=
LTI_TOOL_ID=
LTI_REMOTE_USERNAME=
LTI_REMOTE_IDENTIFIER=

Various. LTI configuration settings which are used in conjunction with your LMS. Only LTI_KEY and LTI_SECRET are required. You will provide these values in the LMS when adding a new external application. More information is available in our Canvas LTI Setup page.

BOOL_LTI_RESTRICT_LOGINS_TO_LAUNCHES=false
BOOL_LTI_COURSE_NAV_DEFAULT=false
BOOL_LTI_CREATE_USERS=true
BOOL_LTI_USE_LAUNCH_ROLES=true
BOOL_LTI_GRACEFUL_CONFIG_FALLBACK=true
BOOL_LTI_LOG_FOR_DEBUGGING=false

Booleans. These are additional configuration toggles to manage various aspects of LTI integration:

GENERATION_ENABLED=false
GENERATION_ALLOW_IMAGES=false
GENERATION_API_PROVIDER=
GENERATION_API_KEY=
GENERATION_API_ENDPOINT=
GENERATION_API_VERSION=
GENERATION_API_MODEL=
GENERATION_LOG_STATS=true

Various. With version 10.3, Materia added support for the use of generative AI in limited and controlled situations associated with widget instance content authoring. We use the OpenAI PHP client to facilitate these queries. The client has support for two implementations: the OpenAI platform API, and Azure OpenAI. Be mindful that there are additional costs incurred with use of this feature. Not all configuration options are required for both implementations. Let’s review each:

IS_SERVER_HTTPS=true

Boolean. Tells FuelPHP whether to manage cookies securely. There are very few reasons why you’d want to set this to false, but it’s available as an option if desired. Defaults to true.