Add documentation about docker image builds

docs/app-rails/container-images.md

@@ -0,0 +1,67 @@
+# Container images
+
+This application employs the [Docker multi-stage build strategy](https://docs.docker.com/build/building/multi-stage/) to build separate docker images for different purposes:
+
+* `dev`: docker image designed to support local development on a developer machine and to run tests
+* `release`: docker image optimized for deployment to production, or other hosted, environments
+
+## Local development: `dev`
+
+You can run the application locally within a container or natively. When running the application in a container locally, use the `dev` image.
+
+Example in a `docker-compose.yml`:
+
+```yaml
+services:
+  local-development-app:
+    build:
+      target: dev
+```
+
+## Deployment to hosted environments: `release`
+
+When you deploy this application to hosted environments (e.g. AWS, Azure, GCP), use the `release` image.
+
+Example in a `docker-compose.yml`:
+
+```yaml
+services:
+  hosted-app:
+    build:
+      target: release
+```
+
+## Testing `release` locally
+
+It is useful to be able to test the `release` image locally without needing to execute a deployment to a hosted environment, such as for testing the production asset compilation pipeline.
+
+In addition to the default Rails environments (i.e. `test`, `development`, `production`), this application implements a `mock-production` Rails environment, which uses "production-like" configuration. Specifically, SSL is disabled in [`mock-production.rb`](/app-rails/config/environments/mock-production.rb):
+
+```ruby
+config.assume_ssl = false
+config.force_ssl = false
+```
+
+### Instructions
+
+Follow these steps to run the `release` image locally. This process uses configuration in [`docker-compose.mock-production.yml`](/docker-compose.mock-production.yml) to build the image and run the composition.
+
+#### 1. Change to the application directory
+
+```bash
+cd app-rails
+```
+
+#### 2. Initialize the container
+
+```bash
+make init-container DOCKER_COMPOSE_ARGS="-f ../docker-compose.mock-production.yml"
+```
+
+### 3. Start the container
+
+```bash
+make start-container DOCKER_COMPOSE_ARGS="-f ../docker-compose.mock-production.yml"
+```
+
+To stop the container, type `Ctrl-C`.