Addl (final?) refinements to docker compose, plus env cleanup and com…

…menting

.env

@@ -1,19 +1,25 @@
-# =========================
+# =================================
 # CONFIGURE MATERIA
-# 1. Copy `.env` to `.env.local` (make changes in .env.local)
-# 2. Set every `<MUST_SET>` value
-# 3. Comb through for any other settings you may wish to change
-# 4. Visit Materia in browser, check logs in fuel/app/logs for debugging
 #
-# DETAILED INSTRUCTIONS
-# !!! View the Materia README for options, descriptions & permitted values !!!
+# This .env file is not referenced by the default development & nondev docker stack! Use docker/.env.local instead.
+# It's recommended to use this .env file as a template for production.
+# Your docker compose file(s) will need to be updated to reference your final .env and its relative path in the env_file: directive of each service.
+#
+# DETAILED INSTRUCTIONS FOR PRODUCTION USE
+#
+# 1. If coming from a nondev instance, copy relevant values from docker/.env.local
+# 2. Set every `<MUST_SET>` value
+# 3. Review remaining optional settings
+# 4. Update your docker compose file(s) to point to the final .env file and location. Services should use the `env_file:` directive to include env vars as required
+# 5. Remove any dev `environment:` references in compose file(s) if they are present
+# 6. Start docker containers (or stop, rm, and restart if already running)
+# 7. Visit Materia in browser, check logs in fuel/app/logs for debugging
 #
-# Only `BOOL_` options become boolean values, and ONLY `true` evaluates to true
+# Refer to docker/README.md for more information about environment configs
 #
-# Docker/Dev notes:
-# docker/.env.local is used instead of .env.local
+# !! NOTE: Only `BOOL_` options become boolean values, and ONLY `true` evaluates to true
 
-# GENERAL ===================
+# GENERAL ==========================
 
 FUEL_ENV=production
 #DATABASE_URL=<MUST_SET>
@@ -24,43 +30,46 @@ BOOL_SEND_EMAILS=false
 #FUEL_ALWAYS_LOAD_MODULES=""
 #GOOGLE_ANALYTICS_ID=xxx
 
-# LOGGING ===================
+# LOGGING ==========================
 
 #FUEL_LOG_THRESHOLD=300
 #LOG_HANDLER=DEFAULT
 
-# ASSETS ===================
+# ASSETS ===========================
 
-#URLS_STATIC=
-#URLS_ENGINES=
+#URLS_STATIC= 								# Set if static files and assets come from a different domain. While used in dev, not required for prod
+#URLS_ENGINES= 								# same as above
 #BOOL_ADMIN_UPLOADER_ENABLE=true
-ASSET_STORAGE_DRIVER=file # file | s3 | db (db not recommended)
+ASSET_STORAGE_DRIVER=file					# file | s3 | db (db not recommended)
 
-# AWS S3 ===================
+# AWS S3 ===========================
+# Note: the <MUST_SET> options here are only required if S3 storage driver is enabled
 
-# ASSET_STORAGE_S3_REGION=us-east-1
-# ASSET_STORAGE_S3_BASEPATH=media
+# ASSET_STORAGE_S3_CREDENTIAL_PROVIDER=		# env | imds
 # 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
+# ASSET_STORAGE_S3_ENDPOINT=				# not required for S3 on AWS
+# ASSET_STORAGE_S3_KEY=<MUST_SET>
+# ASSET_STORAGE_S3_SECRET=<MUST_SET>
+# ASSET_STORAGE_S3_REGION=
+# ASSET_STORAGE_S3_BUCKET=
+# ASSET_STORAGE_S3_BASEPATH=
+# AWS_SESSION_TOKEN=<MUST_SET> 				# STS token for s3 development. Not required if using imds
 
-# SESSION & CACHE ===================
+# SESSION & CACHE ==================
 
 #MEMCACHED_HOST=localhost
 #MEMCACHED_PORT=11211
-#CACHE_DRIVER=file
-#SESSION_DRIVER=file
+#CACHE_DRIVER=file							# memcached | file
+#SESSION_DRIVER=file						# memcached | file | db
 SESSION_EXPIRATION=21600
 
-# THEME ===================
+# THEME ============================
 
 #THEME_ACTIVE=default
 # relative to /fuel/packages/
 #THEME_PACKAGE=materia-theme-ucf
 
-# AUTH ===================
+# AUTH ============================
 
 #AUTH_DRIVERS=Materiaauth
 #AUTH_SALT=<MUST_SET>
@@ -72,14 +81,14 @@ SESSION_EXPIRATION=21600
 #USER_INSTRUCTOR_PASSWORD
 #USER_STUDENT_PASSWORD
 
-# CRYPTO ===================
+# CRYPTO ==========================
 
 #CRYPTO_KEY=<MUST_SET>
 #CRYPTO_IV=<MUST_SET>
 #CRYPTO_HMAC=<MUST_SET>
 #CIPHER_KEY=<MUST_SET>
 
-# LTI ===================
+# LTI ============================
 
 #BOOL_LTI_RESTRICT_LOGINS_TO_LAUNCHES=false
 #LTI_GUID=
@@ -94,17 +103,18 @@ LTI_KEY="materia-production-lti-key"
 #BOOL_LTI_GRACEFUL_CONFIG_FALLBACK=true
 #BOOL_LTI_LOG_FOR_DEBUGGING=false
 
-# Question Generation ===
+# QUESTION GENERATION ===========
+# Note: <MUST_SET> options are only required if GENERATION_ENABLED is true
 
 #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
+#GENERATION_API_PROVIDER=<MUST_SET>			# openai | azure_openai
+#GENERATION_API_KEY=<MUST_SET>
+#GENERATION_API_ENDPOINT=					# required for azure
+#GENERATION_API_VERSION=					# required for azure
+#GENERATION_API_MODEL=						# required for openai
+#GENERATION_LOG_STATS=true					# optional. stats are logged to debug threshold.
 
-# webserver settings =======
+# WEBSERVER =====================
 
-#IS_SERVER_HTTPS=true
+#IS_SERVER_HTTPS=true						# defaults to true, only set to false if required

docker/.env

@@ -1,5 +1,14 @@
-## docker/.env contains environment variables used by Materia during local development
-## we do not recommend making edits directly to this file. Instead, make a .env.local in the same directory (docker/) and override the values below as desired.
+## This env file contains environment variable configurations for development and nondev (but NOT production!)
+## Instead of editing these values directly, use .env.local for overrides
+
+## In a production environment, a final .env file should not include any of the dev defaults for unique keys:
+## AUTH_SALT
+## AUTH_SIMPLEAUTH_SALT
+## CIPHER_KEY
+## LTI_KEY
+## LTI_SECRET
+
+## use the .env file in the root directory as a template for a production .env. Your compose file(s) will need to be updated accordingly.
 
 # fuel environment
 # the run_first_for_nondev script will automatically override this to production

docker/README.md

@@ -142,7 +142,7 @@ _At minimum_, the host machine will require the following:
 
 Based on the above, additional modifications to the docker compose file(s) should include:
 
-1. Importing the correct environment variables by ensuring the correct file is selected in a `env_file:` directive _or_ variables are individually imported via a `environment:` directive.
+1. Importing the correct environment variables by ensuring the correct file is selected in a `env_file:` directive _or_ variables are individually imported via a `environment:` directive. You can use the root `.env` as a template: just be sure to update the `env_file:` path for services accordingly.
 2. Ensuring the local paths for volume mounts for the `widget` and `media` directories are updated and correct.
 3. Ensuring the local paths for volume mounts for the NGINX configuration and key/cert pairs in the `webserver` service definition are updated and correct (if included).
 4. Selecting the preferred versions of the `app` and `webserver` images. For production, we recommend either the `app-stable` and `webserver-stable` tags, or version-specific tags (e.g., `app-v10.3.0` and `webserver-v10.3.0`).

docker/docker-compose.development.yml

@@ -19,6 +19,18 @@ services:
     env_file:
       - .env
       - .env.local
+    environment:
+      # In a production instance, these values should be unique and sourced from the .env file
+      - AUTH_SALT=${DEV_ONLY_AUTH_SALT}
+      - AUTH_SIMPLEAUTH_SALT=${DEV_ONLY_AUTH_SIMPLEAUTH_SALT}
+      - BOOL_LTI_LOG_FOR_DEBUGGING=true
+      - CIPHER_KEY=${DEV_ONLY_SECRET_CIPHER_KEY}
+      - CRYPTO_HMAC=${DEV_ONLY_SECRET_CIPHER_KEY}
+      - CRYPTO_IV=${DEV_ONLY_SECRET_CIPHER_KEY}
+      - CRYPTO_KEY=${DEV_ONLY_SECRET_CIPHER_KEY}
+      - USER_INSTRUCTOR_PASSWORD=${DEV_ONLY_USER_PASSWORD}
+      - USER_STUDENT_PASSWORD=${DEV_ONLY_USER_PASSWORD}
+      - USER_SYSTEM_PASSWORD=${DEV_ONLY_USER_PASSWORD}
     volumes:
       - ..:/var/www/html/
       - ../public/widget:/var/www/html/public/widget/:rw

docker/docker-compose.yml

@@ -17,18 +17,8 @@ services:
     build:
       context: ../
       dockerfile: materia-app.Dockerfile
-    environment:
-      # View Materia README for env settings
-      - AUTH_SALT=${DEV_ONLY_AUTH_SALT}
-      - AUTH_SIMPLEAUTH_SALT=${DEV_ONLY_AUTH_SIMPLEAUTH_SALT}
-      - BOOL_LTI_LOG_FOR_DEBUGGING=true
-      - CIPHER_KEY=${DEV_ONLY_SECRET_CIPHER_KEY}
-      - CRYPTO_HMAC=${DEV_ONLY_SECRET_CIPHER_KEY}
-      - CRYPTO_IV=${DEV_ONLY_SECRET_CIPHER_KEY}
-      - CRYPTO_KEY=${DEV_ONLY_SECRET_CIPHER_KEY}
-      - USER_INSTRUCTOR_PASSWORD=${DEV_ONLY_USER_PASSWORD}
-      - USER_STUDENT_PASSWORD=${DEV_ONLY_USER_PASSWORD}
-      - USER_SYSTEM_PASSWORD=${DEV_ONLY_USER_PASSWORD}
+    env_file:
+      .env
     networks:
       - frontend
       - backend