Merge pull request #815 from HumanBrainProject/staging

v2.3.0 release
FZJ-INM1-BDA · Dec 11, 2020 · ab0c6cf · ab0c6cf
2 parents b78de96 + 969499d
commit ab0c6cf
Show file tree

Hide file tree

Showing 383 changed files with 112,398 additions and 13,880 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -15,7 +15,7 @@ script: skip
 
 jobs:
   include:
-    - stage: Unit tests and Lint
+    - stage: Unit tests, Lint & test build
       if: |
         type = push AND \
         branch NOT IN (master, staging, dev)
@@ -25,6 +25,7 @@ jobs:
       script:
       - npm run lint
       - npm test
+      - npm run build-aot
       env:
       - NODE_ENV=test
 
@@ -64,6 +65,7 @@ env:
     - PPTR_VERSION=2.1.0
     - PROTRACTOR_SPECS=./src/navigating/*.e2e-spec.js
 
+
 # addons:
 #   browserstack:
 #     username: "xiao33"

diff --git a/Dockerfile b/Dockerfile
@@ -3,14 +3,8 @@ FROM node:12 as builder
 ARG BACKEND_URL
 ENV BACKEND_URL=${BACKEND_URL}
 
-ARG USE_LOGO
-ENV USE_LOGO=${USE_LOGO:-hbp}
-
 ARG DATASET_PREVIEW_URL
-ENV DATASET_PREVIEW_URL=${DATASET_PREVIEW_URL:-https://hbp-kg-dataset-previewer.apps.hbp.eu/datasetPreview}
-
-ARG USE_LOGO
-ENV USE_LOGO=${USE_LOGO:-hbp}
+ENV DATASET_PREVIEW_URL=${DATASET_PREVIEW_URL:-https://hbp-kg-dataset-previewer.apps.hbp.eu/v2}
 
 ARG STRICT_LOCAL
 ENV STRICT_LOCAL=${STRICT_LOCAL:-false}
@@ -28,7 +22,7 @@ RUN npm i
 RUN npm run build-aot
 
 # gzipping container
-FROM ubuntu:19.10 as compressor
+FROM ubuntu:20.10 as compressor
 RUN apt upgrade -y && apt update && apt install brotli
 
 RUN mkdir /iv

diff --git a/README.md b/README.md
@@ -7,103 +7,211 @@ Interactive Atlas Viewer is an frontend module wrapping around [nehuba](https://
 A live version of the Interactive Atlas Viewer is available at [https://interactive-viewer.apps.hbp.eu](https://interactive-viewer.apps.hbp.eu). This section is useful for developers who would like to develop this project.
 
 ### General information
-Interactive atlas viewer is built with [Angular (v6.0)](https://angular.io/), [Bootstrap (v4)](http://getbootstrap.com/), and [fontawesome icons](https://fontawesome.com/). Some other notable packages used are [ngrx/store](https://github.com/ngrx/platform) for state management. 
+Interactive atlas viewer is built with [Angular (v9.0)](https://angular.io/), [Bootstrap (v4)](http://getbootstrap.com/), and [fontawesome icons](https://fontawesome.com/). Some other notable packages used are [ngrx/store](https://github.com/ngrx/platform) for state management. 
 
 Releases newer than [v0.2.9](https://github.com/HumanBrainProject/interactive-viewer/tree/v0.2.9) also uses a nodejs backend, which uses [passportjs](http://www.passportjs.org/) for user authentication, [express](https://expressjs.com/) as a http framework.
 
-### Prerequisites
+### Develop viewer
+
+#### Prerequisites
 
 - node >= 12
 
-### Develop Interactive Viewer
+#### Buildtime environments
+
+It is recommended to manage your environments with `.env` file.
+
+As interactive atlas viewer uses [webpack define plugin](https://webpack.js.org/plugins/define-plugin/), where necessary, the environmental variables are `JSON.stringify`'ed and directly replaced in the code.
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `VERSION` | printed in console on viewer startup | `GIT_HASH` \|\| unspecificed hash | v2.2.2 |
+| `PRODUCTION` | if the build is for production, toggles optimisations such as minification | `undefined` | true |
+| `BACKEND_URL` | backend that the viewer calls to fetch available template spaces, parcellations, plugins, datasets | `null` | https://interactive-viewer.apps.hbp.eu/ |
+| `DATASET_PREVIEW_URL` | dataset preview url used by component <https://github.com/fzj-inm1-bda/kg-dataset-previewer>. Useful for diagnosing issues with dataset previews.| https://hbp-kg-dataset-previewer.apps.hbp.eu/datasetPreview | http://localhost:1234/datasetPreview |
+| `MATOMO_URL` | base url for matomo analytics | `null` | https://example.com/matomo/ |
+| `MATOMO_ID` | application id for matomo analytics | `null` | 6 |
+| `STRICT_LOCAL` | hides **Explore** and **Download** buttons. Useful for offline demo's | `false` | `true` |
+| `KIOSK_MODE` | after 5 minutes of inactivity, shows overlay inviting users to interact | `false` | `true` |
+| `BUILD_TEXT` | overlay text at bottom right of the viewer. set to `''` to hide. | |
+
+#### Deploy environments
+
+It is recommended to manage your environments with `.env` file.
+
+##### Application
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `PORT` | port to listen on | 3000 |
+| `HOST_PATHNAME` | pathname to listen on, restrictions: leading slash, no trailing slash | `''` | `/viewer` |
+| `SESSIONSECRET` | session secret for cookie session |
+| `NODE_ENV` | determines where the built viewer will be served from | | `production` |
+| `PRECOMPUTED_SERVER` | redirect data uri to another server. Useful for offline demos | | `http://localhost:8080/precomputed/` |
+| `LOCAL_CDN` | rewrite cdns to local server. useful for offlnie demo | | `http://localhost:7080/` |
+| `PLUGIN_URLS` | semi colon separated urls to be returned when user queries plugins | `''`
+| `STAGING_PLUGIN_URLS` | semi colon separated urls to be returned when user queries plugins | `''`
+| `USE_LOGO` | possible values are `hbp`, `ebrains`, `fzj` | `hbp` | `ebrains` |
+
+##### ebrains user authentication
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `HOSTNAME` | 
+| `HBP_CLIENTID` | `{HOSTNAME}{HOST_PATHNAME}/hbp-oidc/cb` |
+| `HBP_CLIENTSECRET` |
+| `HBP_CLIENTID_V2` | `{HOSTNAME}{HOST_PATHNAME}/hbp-oidc-v2/cb`
+| `HBP_CLIENTSECRET_V2` | 
+
+##### Querying ebrains knowledge graph
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `REFRESH_TOKEN` |
+| `ACCESS_TOKEN` | **nb** as access tokens are usually short lived, this should only be set for development purposes 
+| `CACHE_DATASET_FILENAME` | | `deploy/dataset/cachedKgDataset.json` |
+| `KG_ROOT` | | `https://kg.humanbrainproject.eu/query` |
+| `KG_SEARCH_VOCAB` | | `https://schema.hbp.eu/myQuery/` |
+| `KG_DATASET_SEARCH_QUERY_NAME` | | `interactiveViewerKgQuery-v0_3` |
+| `KG_DATASET_SEARCH_PATH` | | `/minds/core/dataset/v1.0.0` |
+| `KG_SEARCH_SIZE` | | `1000` |
+| `KG_SPATIAL_DATASET_SEARCH_QUERY_NAME` | | `iav-spatial-query-v2` |
+| `KG_SPATIAL_DATASET_SEARCH_PATH` | | `/neuroglancer/seeg/coordinate/v1.0.0` | 
+
+##### Logging
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `FLUENT_PROTOCOL` | protocol for fluent logging | `http` |
+| `FLUENT_HOST` | host for fluent logging | `localhost` |
+| `FLUENT_PORT` | port for fluent logging | 24224 |
+| `IAV_NAME` | application name to be logged | `IAV` | 
+| `IAV_STAGE` | deploy of the application | `unnamed-stage` |
+
+##### CSP
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `DISABLE_CSP` | disable csp | | `true` |
+| `CSP_REPORT_URI` | report uri for csp violations | `/report-violation` |
+| `NODE_ENV` | set to `production` to disable [`reportOnly`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only) | `null` |
+| `SCRIPT_SRC` | `JSON.stringify`'ed array of allowed scriptSrc | `[]` |
+| `CSP_CONNECT_SRC` | `JSON.stringify`'ed array of allowed dataSrc | `[]` |
+| `WHITE_LIST_SRC` | `JSON.stringify`'ed array of allowed src | `[]` |
+| `PROXY_HOSTNAME_WHITELIST` |
+
+##### Rate limiting
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `REDIS_PROTO` | fall back to `REDIS_RATE_LIMITING_DB_EPHEMERAL_PORT_6379_TCP_PROTO` |
+| `REDIS_ADDR` | fall back to `REDIS_RATE_LIMITING_DB_EPHEMERAL_PORT_6379_TCP_ADDR` |
+| `REDIS_PORT` | fall back to `REDIS_RATE_LIMITING_DB_EPHEMERAL_PORT_6379_TCP_PORT` |
+| `REDIS_USERNAME` |
+| `REDIS_PASSWORD` |
+| `DISABLE_LIMITER` | disable rate limiting (maybe required for automated tests) |
+
+##### SaneUrl
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `OBJ_STORAGE_AUTH_URL` |
+| `OBJ_STORAGE_IDP_NAME` |
+| `OBJ_STORAGE_IDP_PROTO` |
+| `OBJ_STORAGE_IDP_URL` |
+| `OBJ_STORAGE_USERNAME` |
+| `OBJ_STORAGE_PASSWORD` |
+| `OBJ_STORAGE_PROJECT_ID` |
+| `OBJ_STORAGE_ROOT_URL` |
+
+##### Test deploy denvironments
+
+| name | description | default | example |
+| --- | --- | --- | --- |
+| `SERVICE_ACCOUNT_CRED` | 
+| `SERVICE_ACCOUNT_CRED_PATH` | 
+| `WAXHOLM_RAT_GOOGLE_SHEET_ID` |
+| `SKIP_RETRY_TEST` | retry tests contains some timeouts, which may slow down tests | 
+
+##### e2e test environments
+
+| name | description | default | example | 
+| --- | --- | --- | --- |
+| PROTRACTOR_SPECS | specs relative to `./e2e/` | `./src/**/*.prod.e2e-spec.js` |  |
+| DISABLE_CHROME_HEADLESS | disable headless chrome, spawns chrome window | `unset` (falsy) | 1 |
+| ENABLE_GPU | uses GPU. nb, in headless mode, will show requirement not met | `unset` (falsy) | 1 |
+
+#### Start dev server
 
 To run a dev server, run:
 
-```
+```bash
 $ git clone https://github.com/HumanBrainProject/interactive-viewer
 $ cd interactive-viewer
 $ npm i
-$ npm run dev
+$ npm run dev-server
 ```
 
-### Develop Plugins
-
-For releases newer than [v0.2.9](https://github.com/HumanBrainProject/interactive-viewer/tree/v0.2.9), Interactive Atlas Viewer attempts to fetch `GET {BACKEND_URL}/plugins` to retrieve a list of URLs. The interactive atlas viewer will then perform a `GET` request for each of the listed URLs, parsing them as [manifests](src/plugin_examples/README.md#Manifest%20JSON).
+Start backend (in a separate terminal):
 
-The backend reads the environment variable `PLUGIN_URLS` and separate the string with `;` as a delimiter. In order to return a response akin to the following:
-
-```JSON
-["http://localhost:3001/manifest.json","http://localhost:9001/manifest.json"]
+```bash
+$ cd deploy
+$ node server.js
 ```
 
-Plugin developers may choose to do any of the following:
-
-_shell_
-
-set env var every time
+#### Build
 
 ```bash
-$ PLUGIN_URLS=http://localhost:3001/manifest.json;http://localhost:9001/manifest.json npm run dev
+$ npm run build-aot
 ```
 
-_dotenv_
+### Develop plugins
 
-set a `.env` file in `./deploy/` once
+Below demonstrates an example workflow for developing plugins:
 
 ```bash
-$ echo `PLUGIN_URLS=http://localhost:3001/manifest.json;http://localhost:9001/manifest.json` > ./deploy/.env
-```
-
-then, simple start the dev process with
 
-```bash
-$ npm run dev
+$ # build aot version of the atlas viewer
+$ npm run build-aot
+$ cd deploy
+$ # run server with PLUGIN_URLS
+$ PLUGIN_URLS=http://localhost:3333/manifest.json;http://localhost:3334/manifest.json node server.js
 ```
 
-Plugin developers can start their own webserver, use [interactive-viewer-plugin-template](https://github.com/HumanBrainProject/interactive-viewer-plugin-template), or (coming soon) provide link to a github repository.
-
-
-[plugin readme](src/plugin_examples/README.md)
-
-[plugin api](src/plugin_examples/plugin_api.md)
-
-[plugin migration guide](src/plugin_examples/migrationGuide.md)
+Interactive Atlas Viewer attempts to fetch list of manifests:
 
+```
+GET {BACKEND_URL}/plugins
+```
 
-## Compilation
+The response from this endpoint will be:
 
-`package.json` provide with two ways of building the interactive atlas viewer, `JIT` or `AOT` compilation. In general, `AOT` compilation produces a smaller package and has better performance. 
+```json
+[
+  "http://localhost:3333/manifest.json",
+  "http://localhost:3334/manifest.json"
+]
+```
 
-### AOT compilation
+When user launches the viewer, the atlas viewer will attempt to fetch the metadata of the plugins:
 
 ```
-npm run build-aot
+GET http://localhost:3333/manifest.json
+GET http://localhost:3334/manifest.json
 ```
 
-### JIT Compilation
-```
-npm run build
-
-/* OR */
+The response from these endpoints are expected to adhere to [manifests](src/plugin_examples/README.md#Manifest%20JSON).
 
-npm run build-min
-```
+When the user launches the plugin, the viewer will fetch `templateUrl` and `scriptUrl`, if necessary.
 
-### Docker
+Plugin developers can start their own webserver, use [interactive-viewer-plugin-template](https://github.com/HumanBrainProject/interactive-viewer-plugin-template), or (coming soon) provide link to a github repository.
 
-The repository also provides a `Dockerfile`. Here are the environment variables used:
 
-_build time_
-- __BACKEND_URL__ : same as `HOSTNAME` during run time. Needed as root URL when fetching templates / datasets etc. If left empty, will fetch without hostname.
+[plugin readme](src/plugin_examples/README.md)
 
-_run time_
+[plugin api](src/plugin_examples/plugin_api.md)
 
-- __SESSION_SECRET__ : needed for session
-- __HOSTNAME__ : needed for OIDC redirect
-- __HBP_CLIENTID__ : neded for OIDC authentication
-- __HBP_CLIENTSECRET__ : needed for OIDC authentication
-- __PLUGIN_URLS__ : optional. Allows plugins to be populated
-- __REFRESH_TOKEN__ : needed for access of public data
+[plugin migration guide](src/plugin_examples/migrationGuide.md)
 
 ## Contributing
 
@@ -115,4 +223,4 @@ Commit history prior to v0.2.0 is available in the [legacy-v0.2.0](https://githu
 
 ## License
 
-TO BE DECIDED
+Apache-2.0