[docs] update/improve documentation to include dev-config-server

Author: pscanf

README.md

@@ -17,35 +17,15 @@ configure any static app.
 ### Install
 
 ```
-npm i --save-dev @staticdeploy/app-server
+yarn add -D @staticdeploy/app-server
 ```
 
-### Quickstart
+### Guides
 
-- add the following `<script>` to your `index.html`:
-  ```html
-  <script id="app-config">
-      window.APP_CONFIG={
-          MY_VAR: "default value for development"
-      };
-  </script>
-  ```
-  When serving the file, `app-server` will inject the runtime configuration into
-  the element.
+- [usage with create-react-app](docs/usage-with-cra.md)
+- [deploy create-react-app apps with Docker](docs/deploy-cra-apps-with-docker.md)
 
-- access the config variables in your code:
-  ```js
-  console.log(window.APP_CONFIG.MY_VAR);
-  ```
-
-- start the server setting configuration variables:
-  ```sh
-  env APP_CONFIG_MY_VAR=value app-server
-  ```
-
-### Documentation
+### Additional documentation
 
 - [how `window.APP_CONFIG` is generated](docs/config-generation.md)
-- [how the config script is injected into index.hmtl](docs/config-injection.md)
-- [how to dynamically set `window.APP_CONFIG` in development](docs/dynamic-config-in-dev.md)
-- [server configuration options](docs/server-configuration-options.md)
+- [app-server configuration options](docs/app-server-configuration-options.md)

docs/server-configuration-options.md renamed to docs/app-server-configuration-options.md

@@ -1,4 +1,4 @@
-## Server configuration options
+## `app-server` configuration options
 
 The `app-server` binary takes the following configuration options:
 

docs/config-injection.md

@@ -0,0 +1,29 @@
+## Deploy create-react-app apps with Docker
+
+Assuming you've set up your project as described in the
+[usage with create-react-app guide](usage-with-cra.md), then all you need to
+build a docker image for building and serving your app is using the following
+`Dockerfile`:
+
+```Dockerfile
+FROM staticdeploy/app-server:cra-builder
+FROM staticdeploy/app-server:cra-runtime
+```
+
+The first `FROM` instruction will run the `ONBUILD` instructions of the
+`:cra-builder` image, which will install dependencies with `yarn` and build the
+app with `yarn build`.
+
+The second `FROM` instruction will copy the built app into the (relatively)
+small `:cra-runtime` image where `app-server` is installed and configured to
+serve the app.
+
+You can then run your app image passing in configuration via environment
+variables:
+
+```sh
+docker run -e APP_CONFIG_MY_VAR=my_val my-app-image
+```
+
+> Note: the `Dockerfile`-s for the `staticdeploy/app-server:*` images can be
+> found in the [docker-app-server repository](https://github.com/staticdeploy/docker-app-server)

docs/deploy-cra-apps-with-docker.md

@@ -0,0 +1,68 @@
+## Usage with create-react-app
+
+### How-to
+
+First:
+
+- add the following `<script>` to your `public/index.html`:
+  ```html
+  <script id="app-config" src="http://localhost:3456/app-config.js"></script>
+  ```
+
+- modify the `start` npm script:
+  ```json
+  "start": "dev-config-server & react-scripts start"
+  ```
+  > Note: you can use `npm-run-all` or `concurrently` to better handle
+  > concurrently running processes in npm scripts
+
+- access the config variable in your code:
+  ```js
+  console.log(window.APP_CONFIG.MY_VAR);
+  ```
+
+Then:
+
+#### In development
+
+- define configuration in the `.env` file:
+  ```sh
+  APP_CONFIG_MY_VAR=my_val
+  ```
+
+- start the development server with `yarn start`
+
+#### In production
+
+- build your app with `yarn build`
+
+- run `app-server` defining configuration via environment variables:
+  ```sh
+  env APP_CONFIG_MY_VAR=my_val app-server
+  ```
+
+### How it works
+
+#### In development
+
+`dev-config-server` starts a server listening on port `3456`. Reading
+environment variables defined in the `.env` file, it generates a javascript file
+and serves it at `/app-config.js`. The file defines the `window.APP_CONFIG`
+global variable ([how it's generated](config-generation.md)).
+
+`react-scripts` starts the development server of the app.
+
+When the app is loaded in the browser, the `#app-config` script in `index.html`
+loads `/app-config.js` defining `window.APP_CONFIG`. The variable can then be
+accessed by the app code.
+
+#### In production
+
+`app-server` starts a server listening on port `3000`, serving files under the
+`build` directory. It also generates - from environment variables - the
+javascript file defining `window.APP_CONFIG`. Instead of serving it at
+`/app-config.js` though, the server injects it directly as content of the
+`#app-config` script in `index.html` (removing the script's `src` attribute).
+
+When the app is loaded in the browser, the `#app-config` script is evaluated,
+defining `window.APP_CONFIG` that can then be accessed by the app code.