From 505c0acb92e2632f2dec941298c75e969bd11939 Mon Sep 17 00:00:00 2001 From: John Date: Mon, 16 Dec 2024 20:37:36 +0000 Subject: [PATCH] Update based on PR feedback - Better documentation - Better naming conventions --- .env | 2 +- .env.development | 1 + .env.production | 2 +- Makefile | 5 +- craco.config.js | 4 + docker/{bc.env.js => config.bc.js} | 2 +- docker/{ynwt.env.js => config.ynwt.js} | 2 +- docker/docker-compose.yaml | 2 +- docker/entrypoint.sh | 5 +- docs/developer/configuration.md | 242 +++++++++++-------------- docs/developer/dependencies.md | 5 +- docs/developer/development.md | 16 +- public/{env.js => config.js} | 2 +- public/index.html | 6 +- 14 files changed, 142 insertions(+), 154 deletions(-) create mode 100755 .env.development rename docker/{bc.env.js => config.bc.js} (95%) rename docker/{ynwt.env.js => config.ynwt.js} (95%) rename public/{env.js => config.js} (98%) diff --git a/.env b/.env index 7253a3f4..616a4492 100644 --- a/.env +++ b/.env @@ -1 +1 @@ -PUBLIC_URL=%REPLACE_URL% +PUBLIC_URL=%REPLACE_PUBLIC_URL% diff --git a/.env.development b/.env.development new file mode 100755 index 00000000..3d591c1a --- /dev/null +++ b/.env.development @@ -0,0 +1 @@ +PUBLIC_URL=http://localhost:30503 diff --git a/.env.production b/.env.production index 7253a3f4..616a4492 100644 --- a/.env.production +++ b/.env.production @@ -1 +1 @@ -PUBLIC_URL=%REPLACE_URL% +PUBLIC_URL=%REPLACE_PUBLIC_URL% diff --git a/Makefile b/Makefile index 80b5c45c..f773db70 100644 --- a/Makefile +++ b/Makefile @@ -1,13 +1,14 @@ # These variables are set to make it convenient to run the docker image locally. tag = $(shell git rev-parse --abbrev-ref HEAD) -port = 30502 +port = 30503 public_url = http://localhost:${port} image: + @npm run build @SDP_TAG=$(tag) SDP_PORT=$(port) docker compose -f docker/docker-compose.yaml build --build-arg REACT_APP_APP_VERSION='$(shell ./generate-commitish.sh)' up: - @SDP_TAG=$(tag) SDP_PORT=$(port) docker compose -f docker/docker-compose.yaml up -d --force-recreate + @SDP_TAG=$(tag) SDP_PORT=$(port) docker compose -f docker/docker-compose.yaml up --force-recreate @echo "Station Data Portal running on $(port)" @docker logs -f station-data-portal-frontend diff --git a/craco.config.js b/craco.config.js index 54d13469..944da6cc 100644 --- a/craco.config.js +++ b/craco.config.js @@ -10,6 +10,10 @@ module.exports = { options: {}, }, ], + // Works around a warning that plotly.js doesn't have a source map + // As warnings are treated as errors in the build, this is necessary + // node_modules are generally external code so it is hard to fix the warning + // and we can safely ignore sourcemap errors. webpack: { configure: { ignoreWarnings: [ diff --git a/docker/bc.env.js b/docker/config.bc.js similarity index 95% rename from docker/bc.env.js rename to docker/config.bc.js index c532f4ad..d271cc91 100644 --- a/docker/bc.env.js +++ b/docker/config.bc.js @@ -1,5 +1,5 @@ window.env = { - PUBLIC_URL: "http://localhost:30502", + PUBLIC_URL: "http://localhost:30503", REACT_APP_BC_BASE_MAP_TILES_URL: "https://services.pacificclimate.org/tiles/bc-albers-lite/{z}/{x}/{y}.png", appTitle: "BC Station Data - PCDS", diff --git a/docker/ynwt.env.js b/docker/config.ynwt.js similarity index 95% rename from docker/ynwt.env.js rename to docker/config.ynwt.js index 77b067e4..0859b129 100644 --- a/docker/ynwt.env.js +++ b/docker/config.ynwt.js @@ -1,7 +1,7 @@ // Example environment config for a YNWT based deployment window.env = { - PUBLIC_URL: "http://localhost:30502", + PUBLIC_URL: "http://localhost:30503", REACT_APP_YNWT_BASE_MAP_TILES_URL: "https://services.pacificclimate.org/tiles/yukon-albers-lite/{z}/{x}/{y}.png", appTitle: "YNWT Station Data", diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml index cd8692d6..9da51cb5 100644 --- a/docker/docker-compose.yaml +++ b/docker/docker-compose.yaml @@ -19,6 +19,6 @@ services: #image: pcic/station-data-portal-frontend:${SDP_TAG} container_name: station-data-portal-frontend volumes: - - ./ynwt.env.js:/app/env.js + - ./config.bc.js:/app/config.js ports: - "${SDP_PORT}:8080" diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh index 719874e2..63857b7d 100755 --- a/docker/entrypoint.sh +++ b/docker/entrypoint.sh @@ -1,10 +1,9 @@ #!/bin/bash - # Note: this pulls the public url by a combination of grep and cut and relies on # PUBLIC_URL to be on its own line with the value and in the format of PUBLIC_URL="http://localhost:8080" # Fragile to additional quotes due to us looking for index 2 -PUBLIC_URL=$(grep PUBLIC_URL env.js | cut -d'"' -f 2) +PUBLIC_URL=$(grep PUBLIC_URL config.js | cut -d'"' -f 2) # update static files with the public url rpl -iR \ @@ -12,7 +11,7 @@ rpl -iR \ -x **/*.html \ -x **/*.css \ -x **/*.json \ - "%REPLACE_URL%" $PUBLIC_URL . + "%REPLACE_PUBLIC_URL%" $PUBLIC_URL . # It is possible that the above could be replaced by a node.js based # script which may prove more resillient long term diff --git a/docs/developer/configuration.md b/docs/developer/configuration.md index bd1fa2c4..cc699777 100644 --- a/docs/developer/configuration.md +++ b/docs/developer/configuration.md @@ -1,16 +1,16 @@ # Configuration Most configuration of the Station Data Portal frontend is done via a YAML -file, `public/config.yaml`. For details, see below. +file, `public/config.js`. For details, see below. For technical reasons, a few configuration parameters must be supplied via environment variables. -## Configuration via `public/config.yaml` +## Configuration via `public/config.js` This file must be a key-value map. It overrides the default configuration values, which are given below. Certain keys do not have default values and -_must_ be specified in `public/config.yaml`. The others are optional. +_must_ be specified in `public/config.js`. The others are optional. ### Configuration options @@ -19,7 +19,7 @@ For default values see [Default configuration](#default-configuration). #### Absolutely required values These values do not have defaults and must be specified -in `public/config.yaml`. They are critical to the functioning of the app. +in `public/config.js`. They are critical to the functioning of the app. `appTitle` @@ -208,35 +208,40 @@ of the correct type. ### Default configuration ```yaml -adjustableColumnWidthsDefault: [7, 5] -defaultTab: Filters -defaultNetworkColor: "#000000" -zoomToMarkerRadiusSpec: [[7, 2], [99, 4]] -userDocs: - showLink: false - url: "https://data.pacificclimate.org/portal/docs/" - text: "User Docs" -lethargy: - enabled: true - stability: 7 - sensitivity: 50 - tolerance: 0.05 -disclaimer: - enabled: false - title: "Disclaimer Title" - body: "Disclaimer body ..." - buttonLabel: "Acknowledge" -mapSpinner: - spinner: "Bars" - x: "40%" - y: "40%" - width: "80" - stroke: "darkgray" - fill: "lightgray" -stationDebugFetchOptions: false -stationDebugFetchLimits: [100, 500, 1000, 2000, 4000, 8000] -showReloadStationsButton: false -timingEnabled: false +{ + "adjustableColumnWidthsDefault": [7, 5], + "defaultTab": "Filters", + "defaultNetworkColor": "#000000", + "zoomToMarkerRadiusSpec": [[7, 2], [99, 4]], + "userDocs": + { + "showLink": false, + "url": "https://data.pacificclimate.org/portal/docs/", + "text": "User Docs", + }, + "lethargy": + { "enabled": true, "stability": 7, "sensitivity": 50, "tolerance": 0.05 }, + "disclaimer": + { + "enabled": false, + "title": "Disclaimer Title", + "body": "Disclaimer body ...", + "buttonLabel": "Acknowledge", + }, + "mapSpinner": + { + "spinner": "Bars", + "x": "40%", + "y": "40%", + "width": "80", + "stroke": "darkgray", + "fill": "lightgray", + }, + "stationDebugFetchOptions": false, + "stationDebugFetchLimits": [100, 500, 1000, 2000, 4000, 8000], + "showReloadStationsButton": false, + "timingEnabled": false, +} ``` ### Example custom configuration files @@ -245,94 +250,72 @@ timingEnabled: false Currently targets CRMP database. -```yaml -appTitle: BC Station Data - PCDS -baseMap: BC - -# sdsUrl values will be replaced by dev or prod URLs when they become ready. -# For now, we have demo instances inside the firewall. -# Uses monsoon database -sdsUrl: http://docker-dev02.pcic.uvic.ca:30512 -# Uses new database -#sdsUrl: http://docker-dev02.pcic.uvic.ca:30562 -# Local instance -#sdsUrl: http://localhost:5000 - -# Currently deployed metadata backends do not respond to provinces QP. -# When they do, we can use stationsQpProvinces and lose stationFilters -#stationsQpProvinces: BC -stationFilters: histories[0].province = "BC" - -# Always necessary for CRMP database -networkFilters: name != "PCIC Climate Variables" - -# pdpDataUrl values will be replaced by dev or prod URLs when they become ready. -# For now, we have a demo instance inside the firewall, below. -# Uses monsoon database -pdpDataUrl: http://docker-dev02.pcic.uvic.ca:30514 -# Uses new database -#pdpDataUrl: http://docker-dev02.pcic.uvic.ca:??? - -# Debug params -#stationFilters: histories[0].province = "BC" -#stationDebugFetchOptions: false -#stationDebugFetchLimits: [100, 500, 1000, 2000, 4000, 8000] -#stationOffset: undefined -#stationLimit: undefined -#stationStride: undefined -#showReloadStationsButton: false -#timingEnabled: false +```js +window.env = { + appTitle: "BC Station Data - PCDS", + baseMap: "BC", + // Uses development database + sdsUrl: + "https://beehive.pacificclimate.org/station-data-portal/pcds/metadata", + //sdsUrl: http://localhost:5000, + // Currently deployed metadata backends do not respond to provinces QP. + // When they do, we can use stationsQpProvinces and lose stationFilters + //stationsQpProvinces: "BC", + stationFilters: 'histories[0].province = "BC"', + // Always necessary for CRMP database + networkFilters: 'name != "PCIC Climate Variables"', + // pdpDataUrl values will be replaced by dev or prod URLs when they become ready. + // For now, we have a demo instance inside the firewall, below. + // Uses development database + pdpDataUrl: + "https://beehive.pacificclimate.org/station-data-portal/pcds/data", + // optional Debug params + //stationFilters: histories[0].province = "BC" + //stationDebugFetchOptions: false + //stationDebugFetchLimits: [100, 500, 1000, 2000, 4000, 8000] + //stationOffset: undefined + //stationLimit: undefined + //stationStride: undefined + //showReloadStationsButton: false + //timingEnabled: false +}; ``` #### PCDS data portal -```yaml -appTitle: BC Station Data - PCDS -baseMap: BC - -# sdsUrl values will be replaced by dev or prod URLs when they become ready. -# For now, we have demo instances inside the firewall. -# Uses monsoon database -sdsUrl: http://docker-dev02.pcic.uvic.ca:30512 -# Uses new database -#sdsUrl: http://docker-dev02.pcic.uvic.ca:30562 - -# Currently deployed metadata backends do not respond to provinces QP. -# When they do, we can invert the commenting out below. -#stationsQpProvinces: BC -stationFilters: histories[0].province = "BC" - -# Always necessary for CRMP database -networkFilters: name != "PCIC Climate Variables" - -# pdpDataUrl values will be replaced by dev or prod URLs when they become ready. -# For now, we have a demo instance inside the firewall, below. -# Uses monsoon database -pdpDataUrl: http://docker-dev02.pcic.uvic.ca:30514 -# Uses new database -#pdpDataUrl: http://docker-dev02.pcic.uvic.ca:??? +```js +window.env = { + appTitle: "BC Station Data - PCDS", + baseMap: "BC", + // uses development database + sdsUrl: + "https://beehive.pacificclimate.org/station-data-portal/pcds/metadata", + // Currently deployed metadata backends do not respond to provinces QP. + // When they do, we can invert the commenting out below. + //stationsQpProvinces: "BC", + stationFilters: 'histories[0].province = "BC"', + // Always necessary for CRMP database + networkFilters: 'name != "PCIC Climate Variables"', + pdpDataUrl: + "https://beehive.pacificclimate.org/station-data-portal/pcds/data", +}; ``` #### YNWT data portal -```yaml -appTitle: YNWT Station Data -baseMap: YNWT - -# sdsUrl values will be replaced by prod URLs when they become ready. -# For now, we have a dev instance. -# Uses monsoon database -sdsUrl: https://services.pacificclimate.org/dev/ynwt/meta - -# We do not at present need to filter based on province (verify!) -#stationsQpProvinces: YK,NT -# We do not at present need to filter networks (verify!) -#networkFilters: ??? - -# pdpDataUrl values will be replaced by prod URLs when they become ready. -# For now, we have a dev instance. -# Uses monsoon database -pdpDataUrl: https://services.pacificclimate.org/dev/ynwt/data +```js +window.env = { + appTitle: "YNWT Station Data", + baseMap: "YNWT", + // We do not at present need to filter based on province (verify!) + //stationsQpProvinces: YK,NT + // We do not at present need to filter networks (verify!) + //networkFilters: ??? + sdsUrl: + "https://beehive.pacificclimate.org/station-data-portal/ynwt/metadata", + pdpDataUrl: + "https://beehive.pacificclimate.org/station-data-portal/ynwt/metadata", +}; ``` ### Custom configuration and Docker deployment @@ -344,17 +327,15 @@ For example, in your docker-compose.yaml, include the following mount: ```yaml volumes: - type: bind - source: /path/to/custom/config.yaml - target: /app/public/config.yaml + source: /path/to/custom/config.js + target: /app/config.js read_only: true ``` -Note: We mount to target `/app/public/config.yml` because the app is built -in the Docker _container_, and this file is picked up in the build and -copied to the appropriate build artifact. -If we move to a system in which the app is built in advance in the -Docker _image_, then the target will change, likely to -`/app/build/static/config.yaml`. +Note: We mount to target `/app/config.js` because the app is built and loaded into +this directory. When executed the docker container's entrypoint will substitute any +`%PUBLIC_URL%` references in code (`%REPLACE_PUBLIC_URL%` in the container) with +the values of PUBLIC_URL in the config.js. ## Environment variables @@ -370,16 +351,13 @@ For development runs of the app launched with `npm start`, the files For more details, see the [CRA documentation](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables). -For production runs, environment variables are provided by -`docker-compose.yaml`. - -### Deployment +### Build time variables `PUBLIC_URL` - Base URL for Station Data Portal frontend. - For local development this should match the expected local url (generally http://localhost:3000/) -- For production this will be set to %REPLACE_URL% and needs to be injected at start time. This happens in the docker container's entrypoint.sh and allows us to configure the sites expected path at run time. +- For production this will be set to %REPLACE_PUBLIC_URL% and needs to be injected at start time. This happens in the docker container's entrypoint.sh and allows us to configure the sites expected path at run time. `REACT_APP_APP_VERSION` @@ -389,18 +367,6 @@ For production runs, environment variables are provided by - It is not recommended to manually override the automatically generated value when the image is run. - Note doubled `APP_` in name. -`REACT_APP_BC_BASE_MAP_TILES_URL` - -- URL template (includes x, y, z) for BC base map tiles. -- Type: string. -- Required if YAML config.baseMap === "BC" - -`REACT_APP_YNWT_BASE_MAP_TILES_URL` - -- URL template (includes x, y, z) for YNWT base map tiles. -- Type: string. -- Required if YAML config.baseMap === "YNWT" - ## Filtering metadata The app can filter metadata to include only a desired subset of items. diff --git a/docs/developer/dependencies.md b/docs/developer/dependencies.md index 73c64668..5a3385f2 100644 --- a/docs/developer/dependencies.md +++ b/docs/developer/dependencies.md @@ -2,7 +2,7 @@ ## Execution environment -Node.js >= 9.2.0 (**important**) +Node.js >= 16 (**important**) All other package requirements are specified in `package.json`. @@ -10,6 +10,9 @@ We **strongly** recommend using [`nvm`](https://github.com/creationix/nvm) to ma In particular, you will have trouble finding later versions of Node.js in standard Linux installs; `nvm` however is up to date with all recent releases. +Alternatively the .devcontainer setup will contain everything needed to set up this environment to the last verified version +of node used for the project. + Note: Avoid `snap` packages. Experience to date suggests it does not result in stable, reliable installations. ## Backend services diff --git a/docs/developer/development.md b/docs/developer/development.md index bcfd51dc..1f187885 100644 --- a/docs/developer/development.md +++ b/docs/developer/development.md @@ -6,8 +6,9 @@ npm start ``` -This starts the app with environment variables taken from local `.env` -files. Brief summary: +This starts the app with environment variables taken from local `.env` files. Generally env variables should be avoided +In favour of values being placed in the `public/config.js` file as these values are pulled when the code +is built. Brief summary: - `.env`: Global default settings - `.env.development`: Development-specific settings (`npm start`) @@ -15,9 +16,20 @@ files. Brief summary: For more details, see the [CRA documentation](https://facebook.github.io/create-react-app/docs/adding-custom-environment-variables). +Take special note of the `.env.*` file priorities when attempting to override for different build types. For building and running a production app, see below. +## the PUBLIC_URL variable + +In line with create react app this variable still needs to be set for correct working of application routers. +In development this will be set to the value in `.env.development` which should be set to the expected url while +executing `npm start`. Generally this will be `http://localhost:3000` by default. + +For production (running `npm run build`) this will be set to `%REPLACE_PUBLIC_URL%` and allow the built +docker container to be able to set this at true run time. See `docker/entrypoint.sh` for the specifics +of this replace implementation. + ## Upgrading `pcic-react-leaflet-components` To get a successful upgrade in your local environment, you must do the diff --git a/public/env.js b/public/config.js similarity index 98% rename from public/env.js rename to public/config.js index b99e46cb..a3d991cd 100644 --- a/public/env.js +++ b/public/config.js @@ -1,5 +1,5 @@ window.env = { - PUBLIC_URL: "http://localhost:3000", + PUBLIC_URL: "http://localhost:30503", REACT_APP_BC_BASE_MAP_TILES_URL: "https://swarm.pacificclimate.org/tiles/bc-albers-lite/{z}/{x}/{y}.png", REACT_APP_YNWT_BASE_MAP_TILES_URL: diff --git a/public/index.html b/public/index.html index e0e9b5f0..a7bda29b 100644 --- a/public/index.html +++ b/public/index.html @@ -20,10 +20,12 @@ Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will work correctly both with client-side routing and a non-root public URL. - Learn how to configure a non-root public URL by running `npm run build`. + + See [Development Docs](docs/developer/development.md) for more information about configuring + public URLs for development and build time. --> Met Data Portal - +