docs: update documentation for v4

Author: pscanf

README.md

@@ -25,8 +25,7 @@ yarn add -D @staticdeploy/app-server
 - [deploy create-react-app apps with Docker](docs/deploy-cra-apps-with-docker.md)
 - [deploy generic static apps with Docker](docs/deploy-apps-with-docker.md)
 
-### Additional documentation
+### Reference documentation
 
+- [app-server config options](docs/app-server-config-options.md)
 - [how requests are routed](docs/requests-routing.md)
-- [how `window.APP_CONFIG` is generated](docs/config-generation.md)
-- [app-server configuration options](docs/app-server-configuration-options.md)

docs/app-server-config-options.md

@@ -0,0 +1,90 @@
+## app-server config options
+
+The **app-server** binary takes the following config options:
+
+- `--config`: path of the javascript file exporting the **app-server** config.
+  Defaults to `app-server.config.js`
+- `--root`: root directory to serve. Defaults to `build`
+- `--fallbackAssetPath`: absolute path (relative to the root directory) of the
+  asset to use as fallback when requests don't match any other asset. The asset
+  MUST exist. Defaults to `/index.html`
+- `--fallbackStatusCode`: status code to use when serving the fallback asset.
+  Defaults to `200`
+- `--headers`: (asset matcher, headers) map specifying which headers to assign
+  to which assets
+- `--configuration`: JSON configuration object for the static app, i.e. what
+  becomes `window.APP_CONFIG`
+- `--configurationKeyPrefix`: Prefix of the environment variables used to
+  generate the configuration for the static app. Defaults to `APP_CONFIG_`
+- `--basePath`: static app base path. Defaults to `/`
+- `--port`: port to listen on. Defaults to `3000`
+
+Options can also be passed via config file, a javascript file exporting an
+object defining one or more of the above config options. Example:
+
+```js
+module.exports = {
+  fallbackAssetPath: "/not-found.html",
+  fallbackStatusCode: 404
+};
+```
+
+Options can also be passed as upper-cased, snake-cased, environment variables
+prefixed by `APP_SERVER_`. Eg:
+
+```sh
+export APP_SERVER_FALLBACK_ASSET_PATH=...
+export APP_SERVER_FALLBACK_STATUS_CODE=...
+```
+
+Option sources have the following priority:
+
+1.  command line flags
+2.  environment variables
+3.  options defined in the config file
+
+Meaning for example that when an option is provided both as a command line flag
+and as an environment variable, the value provided with the command line flag is
+used.
+
+## App configuration generation
+
+The JSON configuration object that is injected by **app-server** into the served
+static app (as the global variable `window.APP_CONFIG`) is generated by merging:
+
+- the JSON object passed as the `--configuration` option
+- a JSON object generated from environment variables using the following
+  algorithm:
+  - filter variables whose name doesn't start with the prefix specified by the
+    `--configurationKeyPrefix` option
+  - strip the prefix from the name of the remaining variables
+  - create the object using those key-value pairs
+
+### Example
+
+Given the `--configuration` option:
+
+```json
+{
+  "KEY_0": "OPT_VALUE_0",
+  "KEY_1": "OPT_VALUE_1"
+}
+```
+
+And given the environment:
+
+```sh
+APP_CONFIG_KEY_1=ENV_VALUE_1
+APP_CONFIG_KEY_2=ENV_VALUE_2
+NON_PREFIXED_KEY=VALUE
+```
+
+the following `window.APP_CONFIG` is generated:
+
+```js
+window.APP_CONFIG = {
+  KEY_0: "OPT_VALUE_0",
+  KEY_1: "ENV_VALUE_1",
+  KEY_2: "ENV_VALUE_2"
+};
+```

docs/app-server-configuration-options.md

@@ -37,7 +37,7 @@ FROM node
 # RUN npm run build
 
 # Second docker stage: copy artifacts into the staticdeploy/app-server image
-FROM staticdeploy/app-server
+FROM staticdeploy/app-server:vX.Y.Z
 
 # Copy artifacts from the previous stage (assuming they were produced in the
 # /dist directory) into the /build directory of the image, the default directory

docs/config-generation.md

@@ -6,18 +6,18 @@ 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
+FROM staticdeploy/app-server:vX.Y.Z-cra-builder
+FROM staticdeploy/app-server:vX.Y.Z-cra-runtime
 ```
 
 The first `FROM` instruction will run the `ONBUILD` instructions of the
-`:cra-builder` image, which will install dependencies with **npm** (or **yarn**
-if your project has a `yarn.lock`) and build the app by running the `build` npm
-script.
+`:vX.Y.Z-cra-builder` image, which will install dependencies with **npm** (or
+**yarn** if your project has a `yarn.lock`) and build the app by running the
+`build` npm script.
 
 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.
+small `:vX.Y.Z-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:

docs/deploy-apps-with-docker.md

@@ -7,20 +7,14 @@
 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"
+  <script id="app-config">
+    window.APP_CONFIG = {
+      /* Your development configuration here */
+      MY_VAR: "my_val"
+    };
+  </script>
   ```
-
-  > 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);
@@ -30,18 +24,12 @@ Then:
 
 #### In development
 
-- define configuration in the `.env` file:
-
-  ```sh
-  APP_CONFIG_MY_VAR=my_val
-  ```
-
+- define your development configuration in the `app-config` script as seen above
 - 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
@@ -51,26 +39,18 @@ Then:
 
 #### In development
 
-**dev-config-server** - a CLI tool provided by
-[staticdeploy/app-config](https://github.com/staticdeploy/app-config/),
-dependency of app-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.
+defines `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).
+**app-server** starts a static server for files under the `build` directory. It
+also generates - from environment variables, command line options, or a
+configuration file - the javascript snippet defining `window.APP_CONFIG`, and
+injects it as content of the `#app-config` script in `index.html`, replacing the
+development configuration.
 
 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.

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

@@ -1,2 +1,2 @@
-FROM staticdeploy/app-server:v4.0.0-cra-builder
-FROM staticdeploy/app-server:v4.0.0-cra-runtime
+FROM staticdeploy/app-server:master-cra-builder
+FROM staticdeploy/app-server:master-cra-runtime

docs/usage-with-cra.md

@@ -13,29 +13,19 @@ yarn install
 yarn start
 ```
 
-Open the app at http://localhost:3000 and see the `Hello world!` greeting. Then
-stop the process, change the value of the variable defined in `.env` and restart
-the development server. Re-open the app and see that the greeting target has
-changed.
+Open the app at http://localhost:3000 and see the `Hello world!` greeting.
+Change the value of the variable defined in `public/index.html` and see that the
+greeting target has changed.
 
 ### What happens in the example
 
-`yarn start` starts - in parallel - **create-react-app**'s development server
-and [**app-config**](https://github.com/staticdeploy/app-config)'s
-**dev-config-server**.
-
-When started, **dev-config-server**:
-
-1.  generates from the `.env` file a javascript script defining the global
-    variable `window.APP_CONFIG`
-2.  serves the script at `http://localhost:3456/app-config.js`
+`yarn start` simply starts **create-react-app**'s development server.
 
 When the app is loaded:
 
-1.  the `#app-config` script in the app's `index.html` loads and evaluates
-    `/app-config.js`
-2.  `app-config.js` defines the variable `window.APP_CONFIG`
-3.  the appropriate greeting is rendered
+1.  the `#app-config` script in the app's `index.html` defines the variable
+    `window.APP_CONFIG`
+2.  the appropriate greeting is rendered
 
 ## Run the example in production mode with Docker
 
@@ -45,20 +35,22 @@ cd app-server/examples/create-react-app
 # Build the app Docker image
 docker build -t app-server-example .
 # Run the image passing in the necessary configuration
-docker run -p 3000:80 -e APP_CONFIG_TARGET=world app-server-example
+docker run --rm --init -p 3000:80 -e APP_CONFIG_TARGET=world app-server-example
 ```
 
-Open the app at http://localhost:3000 and see the `Hello world!` greeting. Then
-stop the container and restart it passing in a different value for the
+Open the app at http://localhost:3000 and see the `Hello world!` greeting. Stop
+the container and restart it passing in a different value for the
 `APP_CONFIG_TARGET` variable. Re-open the app and see that the greeting target
 has changed.
 
 ### What happens in the example
 
 The `docker build ...` command builds the app docker image, using the
 `staticdeploy/app-server:cra-builder` and `staticdeploy/app-server:cra-runtime`
-base images which respectively build the app into a static bundle and setup
-**app-server** to serve the built app.
+base images which respectively:
+
+- build the app into a static bundle
+- setup**app-server** to serve the bundle
 
 When the image is run with `docker run ...`, `app-server`:
 

examples/create-react-app/.env

@@ -2,9 +2,7 @@
   "name": "create-react-app",
   "version": "0.0.0",
   "scripts": {
-    "start:config-server": "dev-config-server",
-    "start:dev-server": "react-scripts start",
-    "start": "npm-run-all -p start:*",
+    "start": "react-scripts start",
     "build": "react-scripts build",
     "test": "react-scripts test --env=jsdom"
   },
@@ -13,7 +11,6 @@
     "react-dom": "^16.9.0"
   },
   "devDependencies": {
-    "@staticdeploy/app-config": "^2.0.2",
     "npm-run-all": "^4.1.5",
     "react-scripts": "3.1.1"
   },

examples/create-react-app/Dockerfile

@@ -1,13 +1,15 @@
-<!doctype html>
+<!DOCTYPE html>
 <html>
+    <head>
+        <title>create-react-app app</title>
+        <script id="app-config">
+            window.APP_CONFIG = {
+                TARGET: "world"
+            };
+        </script>
+    </head>
 
-<head>
-  <title>create-react-app app</title>
-  <script id="app-config" src="http://localhost:3456/app-config.js"></script>
-</head>
-
-<body>
-  <div id="root"></div>
-</body>
-
+    <body>
+        <div id="root"></div>
+    </body>
 </html>