Feature/forms 779 devcontainer (bcgov#1226)

* Add devcontainer Signed-off-by: Jason Sherman <[email protected]> * update readme with more detail and startup info Signed-off-by: Jason Sherman <[email protected]> * provide sample config files. update readme to include configuration steps for keycloak SSO Signed-off-by: Jason Sherman <[email protected]> * make sure we ignore editable config files. update readme explain some config, provide login info for KC Signed-off-by: Jason Sherman <[email protected]> * add component tasks, update readmes Signed-off-by: Jason Sherman <[email protected]> --------- Signed-off-by: Jason Sherman <[email protected]> Co-authored-by: Walter Moar <[email protected]>
usingtechnology · Jan 18, 2024 · 9515042 · 9515042
1 parent 50cd70a
commit 9515042
Show file tree

Hide file tree

Showing 13 changed files with 3,847 additions and 5 deletions.
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -0,0 +1,5 @@
+ARG VARIANT="18.18.2-bullseye"
+FROM node:${VARIANT}
+
+# not much in here, could acheive this another way for sure...
+# but this allows us a prepared place to add other things to the container OS.
diff --git a/.devcontainer/README.md b/.devcontainer/README.md
@@ -0,0 +1,74 @@
+# CHEFS Development with Dev Container
+The following guide will get you up and running and developing/debugging CHEFS as quickly as possible. 
+We provide a [`devcontainer`](https://containers.dev) and will use [`VS Code`](https://code.visualstudio.com) to illustrate.
+
+By no means is CHEFS development limited to these tools; they are merely examples.  
+
+## Caveats
+
+The primary use case for this `devcontainer` is for developing, debugging and unit testing CHEFS source code.
+
+There are limitations running this devcontainer, such as all networking is within this container. This container has [docker-in-docker](https://github.com/microsoft/vscode-dev-containers/blob/main/script-library/docs/docker-in-docker.md) which allows running demos, building docker images, running `docker compose` all within this container.
+
+## Files
+The `.devcontainer` folder contains the `devcontainer.json` file which defines this container. We are using a `Dockerfile` and `post-install.sh` to build and configure the container run image. The `Dockerfile` is simple but in place for simplifying image enhancements. The `post-install.sh` will install the required node libraries for CHEFS including the frontend and formio components.
+
+In order to run CHEFS you require Keycloak (configured), Postgresql (seeded) and the CHEFS backend/API and frontend/UX. Previously, this was a series of downloads and configuration updates and numerous commands to run. See `.devcontainer/chefs_local` files.
+
+Also included are convenient launch tasks to run and debug CHEFS.
+
+## Open CHEFS in the devcontainer
+
+To open CHEFS in a devcontainer, we open the *root* of this repository. We can open in 2 ways:
+
+1. Open Visual Studio Code, and use the Command Palette and use `Dev Containers: Open Folder in Container...`
+2. Open Visual Studio Code and `File|Open Folder...`, you should be prompted to `Reopen in Container`.
+
+
+## Running CHEFS locally
+Keycloak and Postgresql will be launched using docker compose. These will run inside of the devcontainer (docker-in-docker) but the ports are forwarded to the host machine and are accessible on the local host.
+
+CHEFS API and Frontend are running as node applications on the devcontainer - again, ports are forwarded to the host.
+
+### Configuring CHEFS locally
+When the devcontainer is built, it copies `.devcontainer/chefs_local/local.json.sample` and `.devcontainer/chefs_local/realm-export.json.sample` to `.devcontainer/chefs_local/local.json` and `.devcontainer/chefs_local/realm-export.json` respectively. These copies are not checked in and allow the developer to make changes and tweaks without impacting other developers or accidentially committing passwords. 
+
+### Authorization Prerequisites
+1.  An IDIR account is required to access CHEFS. 
+2.  Request an SSO Integration from the Common Hosted Single Sign-on (CSS) page in order to obtain a resource and secret that will be used for authentication when building CHEFS. View the [detailed documentation](https://bcdevex.atlassian.net/wiki/spaces/CCP/pages/961675282) about requesting the Pathfinder SSO integration. 
+3.  Open realm-export.json  located at chefs_build/docker/imports/keycloak and search for `XXXXXXXXXXXX`. This value must match the `clientSecret` value in `local.json`  so that the CHEFS API can connect to your Keycloak instance. By default, these are set to be equal and don’t need to be altered.
+4.  Navigate to the CSS page, login with your IDIR, and download the ‘Development’ Installation JSON from your SSO Integration. 
+5.  Back in the `realm-export.json` file, search for all instances of `YYYYYYYYYYYY` and replace it with the `resource` you obtained from the downloaded JSON file. Search for all instances of `ZZZZZZZZZZZZ` and replace it with the `secret`. 
+
+### Run/Debug
+1. start Keycloak and Postgresql. Many ways to start... 
+    - right click on `.devcontainer/chefs_local/docker-compose.yml` and select `Compose up`
+    - or use command palette `Docker: Compose Up` then select `.devcontainer/chefs_local/docker-compose.yml`
+    - or `Terminal | Run Task...|chefs_local up`
+2. start CHEFS
+    - Run and Debug, select 'CHEFS' which will start both the API and the frontend.
+3. debug Frontend with Chrome
+    - Run and Debug, select 'CHEFS Frontend - chrome' which will start a Chrome browser against the frontend, will allow breakpoints in `/app/frontend/src`
+4. stop Keycloak and Postgresql. Many ways to stop... 
+    - right click on `.devcontainer/chefs_local/docker-compose.yml` and select `Compose down`
+    - or use command palette `Docker: Compose Down` then select `.devcontainer/chefs_local/docker-compose.yml`
+    - or `Terminal | Run Task...|chefs_local down`
+
+*Notes*
+- `CHEFS Frontend` launch configuration is using the `chefs-frontend-local` client in Keycloak, not `chefs-frontend` client as we do in production.
+- `CHEFS API` will use the configuration found at `.devcontainer/chefs_local/local.json`
+- `Postgres DB`: localhost:5432
+- `Keycloak Admin console`: http://localhost:8082 - username/password = admin/admin
+- `CHEFS Frontend`: http://localhost:5173/app
+- `CHEFS API`: http://localhost:5173/app/api/v1
+
+## Formio Components
+If you are developing the formio components, you should build and redeploy them before running your local debug instances of CHEFS. Use tasks `Components build` and `Components Deploy`.
+
+## Troubleshooting
+All development machines are unique and here we will document problems that have been encountered and how to fix them.
+
+### Failure during load of devcontainer when running webpack (Segmentation Fault)
+Encountered on Mac Ventura 13.6, with Mac Docker Desktop 4.26.1 when running `npm run build:formio` on load, we hit a `Segmentation Fault`. The issue was resolved when turning off the virtualization settings in Docker Desktop.
+
+Under Settings, select `gRPC Fuse` instead of `VirtioFS` then unselect `Use Virtualization framework`. Restart Docker and VS Code.
diff --git a/.devcontainer/chefs_local/docker-compose.yml b/.devcontainer/chefs_local/docker-compose.yml
@@ -0,0 +1,42 @@
+version: "3.9"
+volumes:
+  postgres_kc_data:
+    driver: local
+services:
+  postgres:
+    image: postgres:14.2
+    volumes:
+      - postgres_kc_data:/var/lib/postgresql/data
+    restart: unless-stopped
+    ports:
+      - 5432:5432
+    environment:
+      - POSTGRES_USER=app
+      - POSTGRES_PASSWORD=admin
+      - POSTGRES_DB=chefs
+  chefs-keycloak:
+    image: quay.io/keycloak/keycloak:17.0.1
+    volumes:
+      - type: bind
+        source: ./realm-export.json
+        target: /tmp/realm-export.json
+        read_only: true
+    ports:
+      - 8082:8082
+    environment:
+      - DB_VENDOR=POSTGRES
+      - DB_ADDR=postgres
+      - DB_USER=admin
+      - DB_PASSWORD=admin
+      - KEYCLOAK_ADMIN=admin
+      - KEYCLOAK_ADMIN_PASSWORD=admin
+    depends_on:
+      - postgres
+    restart: unless-stopped
+    command:
+      - "start-dev"
+      - "--http-port=8082"
+      - "-Dkeycloak.migration.action=import"
+      - "-Dkeycloak.migration.provider=singleFile"
+      - "-Dkeycloak.migration.file=/tmp/realm-export.json"
+      - "-Dkeycloak.migration.strategy=OVERWRITE_EXISTING"
diff --git a/.devcontainer/chefs_local/local.json.sample b/.devcontainer/chefs_local/local.json.sample
@@ -0,0 +1,90 @@
+{
+    "db": {
+      "database": "chefs",
+      "host": "localhost",
+      "port": "5432",
+      "username": "app",
+      "password": "admin"
+    },
+    "files": {
+      "uploads": {
+        "enabled": "true",
+        "fileCount": "1",
+        "fileKey": "files",
+        "fileMaxSize": "25MB",
+        "fileMinSize": "0KB",
+        "path": "files"
+      },
+      "permanent": "localStorage",
+      "localStorage" : {
+        "path": "myfiles"
+      },
+      "objectStorage": {
+        "accessKeyId": "bcgov-citz-ccft",
+        "bucket": "chefs",
+        "endpoint": "https://commonservices.objectstore.gov.bc.ca",
+        "key": "chefs/dev/",
+        "secretAccessKey": "anything"
+      }
+    },
+    "frontend": {
+      "apiPath": "api/v1",
+      "basePath" : "/app",
+      "keycloak": {
+        "clientId": "chefs-frontend-local",
+        "realm": "chefs",
+        "serverUrl": "http://localhost:8082"
+      }
+    },
+    "server": {
+      "apiPath": "/api/v1",
+      "basePath" : "/app",
+      "bodyLimit": "30mb",
+      "keycloak": {
+        "clientId": "chefs",
+        "realm": "chefs",
+        "serverUrl": "http://localhost:8082",
+        "clientSecret": "XXXXXXXXXXXX"
+      },
+      "logLevel": "http",
+      "port": "8080",
+      "rateLimit" : {
+        "public": {
+          "windowMs": "900000",
+          "max": "100"
+        }
+      }
+    },
+    "serviceClient": {
+      "commonServices": {
+        "ches": {
+          "endpoint": "https://ches-dev.api.gov.bc.ca/api",
+          "tokenEndpoint": "https://dev.loginproxy.gov.bc.ca/auth/realms/comsvcauth/protocol/openid-connect/token",
+          "clientId": "CHES_CLIENT_ID",
+          "clientSecret": "CHES_CLIENT_SECRET"
+        },
+        "cdogs": {
+          "endpoint": "https://cdogs-dev.api.gov.bc.ca/api",
+          "tokenEndpoint": "https://dev.loginproxy.gov.bc.ca/auth/realms/comsvcauth/protocol/openid-connect/token",
+          "clientId": "CDOGS_CLIENT_ID",
+          "clientSecret": "CDOGS_CLIENT_SECRET"
+        }
+      }
+    },
+    "customBcAddressFormioComponent":{
+      "apikey":"xxxxxxxxxxxxxxx",
+      "bcAddressURL":"https://geocoder.api.gov.bc.ca/addresses.json",
+      "queryParameters":{
+        "echo": false,
+        "brief": true,
+        "minScore": 55,
+        "onlyCivic": true,
+        "maxResults": 15,
+        "autocomplete": true,
+        "matchAccuracy": 100,
+        "matchPrecision": "occupant, unit, site, civic_number, intersection, block, street, locality, province",
+        "precisionPoints": 100
+      }
+    }
+  }
+