Skip to content

Commit

Permalink
The readme updates never stop
Browse files Browse the repository at this point in the history
  • Loading branch information
@clpetersonucf
clpetersonucf committed Nov 26, 2024
1 parent 86e46f9 commit 116f577
Show file tree
Hide file tree
Showing 2 changed files with 36 additions and 29 deletions.
21 changes: 9 additions & 12 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -69,10 +69,11 @@ The `run_first` scripts only have to be run once for initial setup. Afterwards,

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.

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.

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.
## Transitioning to Production

More information about creating a production-capable Materia instance can be found in the [Materia Docker Readme](docker/README.md).
Expand All @@ -85,16 +86,6 @@ See the wiki page for [Creating a local user](https://github.com/ucfopen/Materia

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

#### Running A Single Test Group

Inspect the actual test command in `/.run_tests.sh` for guidance, but as of the time of writing this, you can run a subset of the tests in the docker environment to save time.

The following command will run just the **Oauth** tests rather quickly:

```
./run_tests.sh --group=Oauth
```

### 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.
Expand Down Expand Up @@ -155,4 +146,10 @@ $ 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](https://github.com/ucfopen/Materia-Theme-UCF) for `Materia-Theme-UCF` for a breakdown of using theme overrides in Materia 10.x and later.


44 changes: 27 additions & 17 deletions docker/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,8 @@ The default `docker-compose.yml` file contains some base-level configurations fo
- The `webserver` service definition and its associated image.
- The `frontend` and `backend` docker networks.

The `docker-compose.development.yml` file serves as a baseline template for the creation of a `docker-compose.override.yml` file via the first-run scripts and is not referenced directly by default. The `docker-compose.override.test.yml` is utilized for the test suite to separate test conditions from the running application.

The `docker-compose.override.yml` file is not tracked and generated by either the `run_first_for_dev.sh` or `run_first_for_nondev.sh` scripts. By default, `docker compose up` will initialize with both the `docker-compose.yml` and `docker-compose.override.yml` (if present) configurations. Docker compose can always be run with a different set of compose files via the `-f` flag:

```
Expand All @@ -28,22 +30,24 @@ docker compose -f docker-compose.yml -f docker-compose.my-override.yml up

### Volumes

Docker volumes are used to mount files from the host machine into one or more containers, and to share file contents between containers. Depending on whether you are pursuing a development or more prod-like instance, the individual volume definitions will be different.
Docker volumes are used to mount files from the host machine into one or more containers, and to share file contents between containers. Depending on whether you are pursuing a development or more prod-like instance, volume definitions in your compose file(s) will be different.

- **Development**: Your entire project directory is mounted to the `app` container. Static assets and widget assets are cross-mounted to the `webserver` container.
- **Production**: Static (compiled) assets are virtually mounted on the `app` container and cross-mounted on the `webserver` container. Widget engine files and user media files (if using the `file` asset storage driver) are volume mounted from the host machine.

In both situations, the `webserver` has additional volume-mounted files: the NGINX configuration and typically (though dependent on your production setup), the key and certificate pair for SSL.

### Data Persistence

Because docker containers are relatively ephemeral, it is recommended that certain resources and configurations are saved on the host machine or an external service and synced with the containers after they are running. This is especially important to facilitate future updates to the system. Let's review each:
Because docker containers are relatively ephemeral, certain resources and configurations should be sourced from the host machine or an external service and volume mounted to the containers through compose. This is especially important to facilitate future updates to the system. Let's review each:

#### The database

We highly recommend using an external database service like Amazon RDS, Azure Database for MySQL, or Cloud SQL. While the development instance of Materia uses a local MySQL database, this is not recommended for production. Regardless of where your database is located, you should perform regular backups.
We highly recommend using an external database service like Amazon RDS, Azure Database for MySQL, or Cloud SQL. Alternatively, the database file can be volume-mounted from the host to enable persistence. The default development environment persists the mysql database in a virtual volume, which is not recommended for production. Regardless of where your database is located, you should perform regular backups.

#### Configuration files, like env variables

These configuration files should be defined on the host machine or an external service like AWS Secrets Manager. The docker compose file can define individual environment variables or import a local `.env` or `.env.local` file. Materia ships with a `.env` file (and `.env.local`) for local development.
These configuration files should be defined on the host machine or an external service like AWS Secrets Manager. The docker compose file can define individual environment variables or import a local `.env` or `.env.local` file. The `.env` file in the root project directory serves as a template for production use; in `docker/`, the `.env`, `.env.local`, and `.env.local.mysql` files are used for the default development and nondevelopment instance.

#### Installed widget files

Expand All @@ -65,30 +69,33 @@ Use `./run_first_for_dev.sh` in the `docker/` directory to initialize the applic
4. Volume mounting the entire project directory into the application container, so that modifications of server files on the host machine are reflected in the running application.
5. Configuration of an additional port (`8008`) to simulate serving static assets from a second domain.

Since your entire project directory is volume mounted, local changes to compiled JS and CSS assets will be reflected on the running application. Use `yarn dev` to run the webpack dev server and facilitate live reloading of assets. This requires a local installation of `node` and `yarn`.

### Setup: Non-Development Environment

The non-dev configuration is ideal for those looking to play around with Materia locally without doing any local development. Additionally, it serves as a reasonal starting point for standing up a production instance of Materia.
The non-dev configuration is ideal for those looking to play around with Materia locally without doing any local development. Additionally, it serves as a reasonable starting point for standing up a production instance of Materia.

The nondev startup script walks you through a series of configuration decisions to dynamically write the `docker-compose.override.yml` file. These include:

1. The IP you use to access docker on your host machine (usually `localhost`).
2. The use of a local database in a dedicated `mysql` container.
2. The use of a local database in a dedicated `mysql` container or an external one.
3. The cache driver configuration (`memcached` or `file`).
4. The session driver configuration (`memcached`, `file`, or `db`).
5. The asset storage driver configuration (`file` or `db`).

Additionally, the script will explicitly ask whether or not you want to install the default set of widgets. While this is required for fresh instances, if using an existing database, this may not be desired.
Additionally, the script will explicitly ask whether or not you want to install the default set of widgets. While this is required for fresh instances, if using or migrating from an existing database, this may not be desired.

### Environment Configuration

The `docker/` directory contains two `env` files:
The `docker/` directory contains a default `.env` file, plus additional files based on the nondev script:

1. `.env` contains default dev-specific default values. This file is tracked, and changes to it are not generally recommended
1. `.env` contains default dev-specific default values. This file is tracked, and changes to it are generally not recommended.
2. `.env.local` is created by either of the `run_first` scripts. It contains environment configuration overrides and should be considered the authoritative source for environment variables.
3. `.env.local.mysql` is created by the `run_first_for_nondev.sh` script to contain credential values for the `mysql` service if configured.

If a different `env` file is desired, make sure to update your `docker-compose.override.yml` file with changes to the `env_file` parameter in the associated service definition (typically `app`, potentially `mysql`).
If a different `.env` file is desired, make sure to update your `docker-compose.override.yml` file with changes to the `env_file` parameter in the associated service definition (typically `app`, potentially `mysql`).

The Materia application will defer to environment variables to populate many configuration options. Storing these in environment variables that are loaded via docker compose ensure configurations will persist across container instances.
The Materia application will defer to environment variables to populate many configuration options. Storing these in environment variables that are loaded via docker compose ensures configurations will persist across container instances.

For a full breakdown of the environment variables available, refer to the [Server Variables](https://ucfopen.github.io/Materia-Docs/admin/server-variables.html) page in the documentation.

Expand All @@ -110,7 +117,7 @@ By default, the base `docker-compose.yml` file will contain the `image` definiti

### Database Migrations

Updating to a new version of Materia may require migrations to be performed on the database. These are handled by the built-in migration utility in FuelPHP. Database migration state is stored in the database in `migration` table.
Updating to a new version of Materia may require migrations be performed on the database. These are handled by the built-in migration utility in FuelPHP. Database migration state is stored in the database in the `migration` table.

> [!IMPORTANT]
> As with all database modifications, you should ensure a backup is performed prior to running a migration.
Expand All @@ -120,7 +127,7 @@ In `docker/`:
./run.sh php oil r migrate
```

Note that running oil commands in production may require shell access to the `app` container if the Materia repository (and `docker/` directory with its utility scripts) are not present.
Note that running oil commands in production may require shell access to the `app` container if the Materia repository (and `docker/` directory with its utility scripts) are not present (see _Upgrading Materia in Production_ below).

## Using Materia in Production

Expand All @@ -145,7 +152,7 @@ Based on the above, additional modifications to the docker compose file(s) shoul
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`).
4. Selecting the preferred versions of the `app` and `webserver` images. For production, we recommend version-specific tags (e.g., `app-v10.3.0` and `webserver-v10.3.0`) or the `app-stable` and `webserver-stable` tags.
5. Any additional configurations for the `webserver` service definition as far as port assignments or considerations for network traffic reaching the host machine.

> [!IMPORTANT]
Expand All @@ -154,6 +161,8 @@ Based on the above, additional modifications to the docker compose file(s) shoul
> * `LTI_KEY`, `LTI_SECRET`, `LTI_GUID`, and `LTI_TOOL_ID` must be set if you intend to use Materia with an LMS.
> * `AUTH_SALT`, `AUTH_SIMPLEAUTH_SALT, and `CIPHER_KEY`: _see the commands section below for generating a unique salt hash for these values._
> * `CRYPTO_IV`, `CRYPTO_HMAC`, and `CRYPTO_KEY` are legacy encryption keys. They are not required for new copies of Materia, but can be set using unique salt hashes in the same way as `CIPHER_KEY`.
>
> For easy reference, use the `.env` in the root project directory as a template for your production configurations.
Once configured, starting Materia on the host machine is as simple as:

Expand Down Expand Up @@ -191,8 +200,9 @@ services:
...additional webserver definitions...
```

4. Run `docker compose up` or `docker compose up -d` to run the containers in detached mode
5. If a database migration is required, perform the migration by first getting shell access to the `app` container and then running the migrate command:
4. Run `docker compose pull`.
5. Run `docker compose up` or `docker compose up -d` to run the containers in detached mode.
6. If a database migration is required, perform the migration by first getting shell access to the `app` container and then running the migrate command:

```
<host machine shell> $ docker exec -it <app container id> sh
Expand Down Expand Up @@ -264,4 +274,4 @@ Refer to the [Authentication section](https://github.com/ucfopen/Materia/blob/ma

### Default User Accounts

If you wish to log into Materia, there are [3 default accounts created for you based on the config](https://github.com/ucfopen/Materia/blob/master/fuel/app/config/materia.php#L56-L78). If you're on OSX or Linux, you'll also get a user based on the username you use on the host machine.
If you wish to log into Materia, there are [3 default accounts created for you based on the config](https://github.com/ucfopen/Materia/blob/master/fuel/app/config/materia.php#L56-L78). If you're on MacOS or Linux, you'll also get a user based on the username you use on the host machine.

0 comments on commit 116f577

Please sign in to comment.