Improve and document frontend resource build

Document the frontend build and reformat README.md to improve structure
and readability. Switch from plain npm to yarn.

README.md

@@ -7,11 +7,14 @@ in this repository provides the UI components that are required by Hydra.
 
 ## Setup
 
-- create certificates for the IDP, the application and Hydra. You can use the
+### Certificates
-  testca from the [CAcert developer setup](https://git.dittberner.info/jan/cacert-devsetup)
-  like this:
 
-  1. create signing requests
+You need a set of certificates for the IDP, the application and Hydra. You
+can use the Test CA created by the ``setup_test_ca.sh`` script from the
+[CAcert developer setup](https://git.dittberner.info/jan/cacert-devsetup)
+repository like this:
+
+1. create signing requests
 
    ```
    mkdir certs
@@ -34,7 +37,7 @@ in this repository provides the UI components that are required by Hydra.
    cp *.csr.pem $PATH_TO_DEVSETUP_TESTCA/
    ```
 
-  2. Use the CA to sign the certificates
+2. Use the CA to sign the certificates
 
    ```
    pushd $PATH_TO_DEVSETUP_TESTCA/
@@ -47,23 +50,34 @@ in this repository provides the UI components that are required by Hydra.
    cp $PATH_TO_DEVSETUP_TESTCA/{hydra,idp,app}.cacert.localhost.crt.pem .
    ```
 
-- install Hydra according to their documentation
+3. Copy CA certificate for client certificates
-
-- setup the Hydra database
   
    ```
-  sudo -i -u postgres psql
+   openssl x509 -in $PATH_TO_DEVSETUP_TESTCA/class3/ca.crt.pem \
-  > CREATE DATABASE hydra_local ENCODING utf-8;
+       -out client_ca.pem
-  > CREATE USER hydra_local WITH PASSWORD '${YOUR_POSTGRESQL_PASSWORD}';
-  > GRANT CONNECT, CREATE ON DATABASE hydra_local TO hydra_local;
-
-  hydra migrate sql "postgres://hydra_local:${YOUR_POSTGRESQL_PASSWORD}@localhost:5432/hydra_local"
    ```
 
-- create a configuration file for Hydra i.e. hydra.yaml:
+### Setup Hydra
 
-  ```
+We use the ORY Hydra OAuth2 / OpenID Connect implementation. Install Hydra
-  serve:
+according to their [documentation](https://www.ory.sh/hydra/docs/install).
+The setup has been tested with the Linux binary installation.
+
+Perform the Hydra database setup:
+
+```
+sudo -i -u postgres psql
+> CREATE DATABASE hydra_local ENCODING utf-8;
+> CREATE USER hydra_local WITH PASSWORD '${YOUR_POSTGRESQL_PASSWORD}';
+> GRANT CONNECT, CREATE ON DATABASE hydra_local TO hydra_local;
+
+hydra migrate sql "postgres://hydra_local:${YOUR_POSTGRESQL_PASSWORD}@localhost:5432/hydra_local"
+```
+
+Create a configuration file for Hydra i.e. ``hydra.yaml``:
+
+```
+serve:
   admin:
     host: hydra.cacert.localhost
   public:
@@ -75,7 +89,7 @@ in this repository provides the UI components that are required by Hydra.
       path: certs/hydra.cacert.localhost.key
   dsn: 'postgres://hydra_local:${YOUR_POSTGRESQL_PASSWORD}@localhost:5432/hydra_local'
 
-  webfinger:
+webfinger:
   oidc_discovery:
     supported_claims:
       - email
@@ -92,10 +106,10 @@ in this repository provides the UI components that are required by Hydra.
       - profile
       - email
 
-  oauth2:
+oauth2:
   expose_internal_errors: false
 
-  urls:
+urls:
   login: https://login.cacert.localhost:3000/login
   consent: https://login.cacert.localhost:3000/consent
   logout: https://login.cacert.localhost:3000/logout
@@ -105,69 +119,101 @@ in this repository provides the UI components that are required by Hydra.
     public: https://auth.cacert.localhost:4444/
     issuer: https://auth.cacert.localhost:4444/
 
-  secrets:
+secrets:
   system:
     - "${YOUR SECRET FOR HYDRA}"
-  ```
+```
 
-- add entries for auth.cacert.localhost and hydra.cacert.localhost to /etc/hosts
+The available configuration options are described in the
+[Hydra configuration documentation](https://www.ory.sh/hydra/docs/reference/configuration).
 
-  ```
+Hydra needs to be able to resolve its hostnames and does not work with the
-  ::1 auth.cacert.localhost hydra.cacert.localhost
+systemd-nss module. You therefore need to define Hydra's hostnames in your
-  ```
+``/etc/hosts`` file:
 
-  This is required to allow Hydra to start properly
+```
+::1 auth.cacert.localhost hydra.cacert.localhost
+```
 
-- create an OIDC client configuration for the demo application
+### Add OpenID Connect configuration for a client
 
-  ```
+Create an OpenID Connect (OIDC) client configuration for the demo application
-  hydra clients create --endpoint https://hydra.cacert.localhost:4445/ \
+
+```
+hydra clients create --endpoint https://hydra.cacert.localhost:4445/ \
     --callbacks https://app.cacert.localhost:4000/callback \
     --logo-uri https://register.cacert.localhost:3000/images/app.png \
     --name "Client App Demo" \
     --scope "openid offline_access profile email" \
     --post-logout-callbacks https://app.cacert.localhost:4000/after-logout \
     --client-uri https://register.cacert.localhost:3000/info/app
-  ```
+```
 
-  the command returns a client id and a client secret that you need to
+The command returns a client id and a client secret, that you need for the
-  configure for the demo application
+demo application configuration.
 
-- create a configuration for the IDP
+### Configure IDP
 
-  The IDP requires a strong random key for its CSRF cookie. You can generate
+The Identity Provider application (IDP) requires a strong random key for its
-  such a key using the following openssl command:
+CSRF cookie. You can generate such a key using the following openssl command:
 
-  ```
+```
-  openssl rand -base64 32
+openssl rand -base64 32
-  ```
+```
 
-  Use this value and create `idp.toml`:
+Use this value and the database credentials from your cacert-devsetup and
+create `idp.toml`:
 
-  ```
+```
-  [security]
+[security]
-  csrf.key = "<32 bytes of base64 encoded data>"
+csrf.key = "<32 bytes of base64 encoded data>"
-  ```
   
-- create a configuration for the Demo application
+[db]
+dsn = "$MYSQL_USER:$MYSQL_PASSWORD@tcp(localhost:13306)/cacert
+```
 
-  You will need a 32 byte and a 64 byte random secret for the session
+### Configure the Demo Application
-  authentication and encryption keys:
 
-  ```
+You will need a 32 byte and a 64 byte random secret for the session
-  openssl rand -base64 64
+authentication and encryption keys:
-  openssl rand -base64 32
-  ```
 
-  ```
+```
-  [oidc]
+openssl rand -base64 64
-  client-id = "<client id from hydra clients invocation>"
+openssl rand -base64 32
-  client-secret = "<client secret from hydra clients invocation>"
+```
 
-  [session]
+You also need the client id and the client secret, that have been generated
-  auth-key = "<64 bytes of base64 encoded data>"
+during the OIDC client setup described above.
-  enc-key = "<32 bytes of base64 encoded data>"
+
-  ```
+```
+[oidc]
+client-id = "<client id from hydra clients invocation>"
+client-secret = "<client secret from hydra clients invocation>"
+
+[session]
+auth-key = "<64 bytes of base64 encoded data>"
+enc-key = "<32 bytes of base64 encoded data>"
+```
+
+## Frontend resource build
+
+The frontend resources are built using [webpack 5](https://webpack.js.org/)
+and [yarn](https://classic.yarnpkg.com/lang/en/). You need recent nodejs
+and yarn versions. See the
+[Debian installation instructions](https://github.com/nodesource/distributions/blob/master/README.md#debinstall)
+of nodesource or look at the other options on the
+[nodejs Download page](https://nodejs.org/en/download/) if you cannot use
+Debian Bullseye or newer.
+
+When you are sure that you have nodejs >= 12 and yarn you can install the
+required dependencies and run webpack like this:
+
+```
+yarn
+yarn run build
+```
+
+## Start
 
 Now you can start Hydra, the IDP and the demo app in 3 terminal windows:
 

webpack.config.js

@@ -32,6 +32,7 @@ module.exports = {
         path: path.resolve(__dirname, 'static'),
         filename: 'js/[name].bundle.js',
     },
+    devtool: 'source-map',
     optimization: {
         minimize: true,
         minimizer: [new TerserPlugin()],
@@ -59,14 +60,14 @@ module.exports = {
                     loader: 'postcss-loader',
                     options: {
                         postcssOptions: {
-                            plugins: function () {
+                            plugins: [
-                                return [
+                                [
-                                    require('precss'),
+                                    'precss',
-                                    require('autoprefixer'),
+                                    'autoprefixer',
-                                ];
+                                ],
-                            }
+			    ],
-                        }
+                        },
-                    }
+                    },
                 }, {
                     loader: 'sass-loader',
                 }]