Significant rework to base README and docker README

README.md

@@ -26,37 +26,53 @@ Materia is configured to use Docker containers in production environments, orche
 
 ### Docker Deployment
 
-We publish production ready docker and nginx containers in the [Materia Docker repository](https://github.com/orgs/ucfopen/packages/container/package/materia).  For more info on using Docker in Production, read the [Materia Docker Readme](docker/README.md)
+We publish production-ready application and webserver images in the [Materia Docker repository](https://github.com/orgs/ucfopen/packages/container/package/materia), which can be used with docker compose as part of a production application instance.
+
+The default compose file includes some minimum requirements for a local application. A production instance may require changes to the base compose file or composite additions via a `docker-compose.override.yml` file based on various needs. Note that the startup scripts mentioned below will create an override compose file for you.
 
 ### Configuration
 
+> [!NOTE]
+> Due to the ephemeral nature of docker containers, it is recommended you manage application configurations via a `.env` file on the host machine. Docker compose can import these environment variables into the application container.
+
 Visit the [Server Variables](https://ucfopen.github.io/Materia-Docs/admin/server-variables.html) page on our docs site for information about configuration through environment variables.
 
-## Development
+## Setup
 
-Code contributors should review the [CONTRIBUTING](CONTRIBUTING.md) document before proceeding.
+Materia provides a pair of setup scripts for out-of-the-box deployment based on two different use cases:
 
-### Local Dev with Docker
+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.
 
-Get started with a local dev server:
+In either case, first-time setup involves the following:
 
 ```
 git clone https://github.com/ucfopen/Materia.git
-
 cd Materia/docker
+```
 
-./run_first.sh
+Followed by either:
+```
+./run_first_for_dev.sh
 ```
+For local development or 
 
-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.
+```
+./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.
 
-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. This requires node and yarn to be installed on the host machine.
 
-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 your application on ports `443` and `8008` (if setup for local development).
 
-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`.
+## Transitioning to Production
 
-More info about Materia Docker can be found in the [Materia Docker Readme](docker/README.md)
+More information about creating a production-capable Materia instance can be found in the [Materia Docker Readme](docker/README.md).
 
 ### Creating additional users
 
@@ -80,6 +96,10 @@ The following command will run just the **Oauth** tests rather quickly:
 
 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](CONTRIBUTING.md) document before proceeding.
+
 ## Authentication
 
 Materia supports two forms of authentication:
@@ -109,3 +129,27 @@ 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](https://ucfopen.github.io/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.
+
+