Change Log

v9.0

Environment variables moved from .env to azure environment variables no longer sit in the crednetials/env.json file - this file is obsolete documentation ammended below for docker containers environment variables sit in docker/.env for deployment to azure variables sit in azure application settings

v8.2

Front-end Apps improvement

More componentization and fixed path for webpack. Development for CustomerWebApp sso for iframe and BC user personalization

v8.1

Swagger documentation is now more modular

Swagger documents can now be loaded from npm modules which is where they should belong.

This means that the api documentation (more important for headless apps), can shrink or grow depending on the modules imported.

All you need to do is get the json definition for swagger from the npm module, and load it at the same time as the routes are loaded.

The swagger setup has been migrated to its own script. the script only needs the express app object, and an array of json objects that will be loaded into the paths object in the swagger options.json at runtime.

v8

Several new features and changes have been rolled out in this release

1. Settings file has been moved to the credentials folder.
2. The module alias has been changed. Settings, Credentials and Env files can be required by @settings, @credentials and @env respectively.
3. Babaks Web App Portal code has been rolled into this project. The front end is selectable by running the npm run create command from the project root dir.
4. As part of the Portal integration, you now load routes in the app container by appending to the activeRoutes array in the settings.js file.
5. Webpack will only compile the frontend project selected.
6. Better error handling for when modules fail to load. Now there will be an error message instead of the containers crashing.
7. Startup scripts have more questions related to your selections. Question sets will be asked (or not asked) depending on your selections.
8. Startup scrips and loading methods are extensible in case more front end options are added.

v7.3

CWA rolled into the framework and pull requests mandatory on develop branch

v7.2

There is now a node based start up script in the root of the project. Creating the necessary files are no longer a requirement as long as you run the relevant docker commmand to create your project. Available npm commands are:

1. npm run create: This will run through the setup script and ask the required questions to generate the scripts you previously had to make manually
2. npm run start: This will spin up the Docker containers for the development environment.
3. npm run stop: This will stop the containers if they are running.
4. npm run destroy: This is the equivelant of docker-compose down -v run from the /Docker/Dev folder.
5. npm run build: This will rebuild the containers.

Prettier has also been added ontop of eslint as a way to further ensure code standards are being met. Please ensure you have the required extensions installed to enable Prettier and ESLint to do their job. Don't just turn off ES Lint because you don't like seeing red in VS Code. Handle the linting errors so they go away in a proper fashion

The database container has been dropped from the stack of possible containers. Reasons for its drop is it just isn't used. UKMS made us Azure Databases at the start of this frameworks development so the database container support has been neglected as a result.

v7.1

Version 7.1 undoes the changes in v7 that saw the introduction of an entrypoint script for the containers that was enabling node modules to be visible on the host machine. This in turn enabled intellisense.

This has been removed for performance issues. Nodemon took between 8-10 seconds to restart.

There is currently no method to enable intellisense on the host machine.

If you want this to work then you have two options:

1. Install the VS Code Remote Container extension and remote into the containers you are developing with.
2. Clone your project into WSL2 (enable WSL2 support for docker) and run the containers as normal from here. You can then do an npm install on the host, as there is no disparity between the OS in WSL and the container.

v7

Version 7 we have migrated the common library into a series of npm private modules.

1. @thenavpeople/common
2. @thenavpeople/database-module
3. @thenavpeople/authentication-module
4. @thenavpeople/base-app
5. @thenavpeople/base-api
6. @thenavpeople/component-library

For a complete overview of what is included in these modules please refer to the NPM Modules pdf file in the docs folder.

Note: In order to use these modules, you will need an NPM Token supplied to you. These should be distributed on a project basis so please either email someone with access to the npm repository to generate a new npm token for you.

Other small changes:

• The webpack config files are now in a seperate webpack folder which is a subdirectory of the client folder. This is to slim down the scripts in the containers root.
• pm2 scripts have been deleted as are not used
• container startup is handled through the entrypoint.sh scripts in the App and Api folder roots.
• package.json dependencies split into dev-dependencies where relevent.
• Docs updated. Base Library pdf removed as redundent and replaced with npm modules pdf. How to pdf updated.
• @thenavpeople npm modules fully integrated into scripts and examples.
• base directories from App and Api removed
• base assets docker volume removed

Express Base app framework

Dev Environment

For your dev environemnt, this framework will sit inside docker containers as part of a stack consisting of 3 containers. These containers are:

• client
• backend
• frontend

There is a startup script included in the framework that make configuring the container stack as straightforward as answering a few questions. To run this startup script, you will need to have npm installed (installed alongside Node js). The startup script should be designed to use only standard Node functionality so you should not have to perform an npm install as a part of setting up your development environment.

To begin the startup script you should run npm run create from a command line terminal (command promp, powershell etc). This will run you through the basic startup questions and create your environment based on your answers. If the files it needs to create already exists, it should use that as a template and update them with your new values.

To effectively work with this repository please have Docker installed and Linux contaners switched on...

Prerequisites

The web app framework has some features to aid in development. There are a few VS Code extensions that you should install to enable full functionality.

Docker

• Docker - so you can manage Docker inside VS Code
• Remote Containers - so you can attach a VS Code instance to a Docker Container

Debugging

• Debugger for Chrome - to enable react debugging

Linting

• ESLint - to show any linting errors
• Prettier - Code formatter - for formatting javascript code for a consistent layout.

Other

• A VS Code pdf viewer so you can view the documentation in a VS Code Window.

To set up your dev environment, please read through this document then follow the steps below

1. Clone this repository
2. Unless, you are intending to further develop these Base Web App Components, copy the files into your own repository (or delete the .git file and replace it with one of your own)
3. From the root of the project, run npm run create. Follow the prompts and answer the questions.
4. Once the containers are spun up, go to localhost:{{devport}} in your browser and start developing.

Manual Setup

If for any reason you seem unable to follow the startup script, here are the steps involved for a manual setup of the development environment. Please complete steps 1. and 2. from the previous section and follow on from there:

1. Create a new file in ./docker/dev/ called .env. Contents for this file are listed below. (This file is typically generated when you run npm run create and should be in the gitignore as it is specific to your local environment)
2. Create file called credentials.js in both /frontend/credentials and /backend/credentials folders. The contents of these files you can get from /scripts/templates/* or by looking at the relevant documentation.
3. If you are using a database, modify the credentials.js files to fit.
4. Run npm run start from the root of your project.
5. Press F1 > Tasks: Run Task > Logs to open the container logs.
6. Open your browser to localhost:{{devport}} and begin development.

For a full breakdown of the contents of the various credentials, env and settings files please refer to the documentation in /scripts/templates and in the main framework pdf document.

• Docker .env
• Frontend credentials.json
• Frontend env.json **(DEPRICATED)
• Frontend settings.json
• Backend credentials.json
• Backend env.json **(DEPRICATED)
• Backend settings.json
• Client settings.json
• Client local.settings.json
• Client proxies.json

Useful Docker Commands

To spin up your container stack: docker-compose up

To remove the containers: docker-compose down

To remove the containers and destroy the volumes: docker-compose down -v

To rebuild all the containers: docker-compose build

To rebuild a single container: docker-compose build <service_name> e.g. docker-compose build app

IMPORTANT: You shouldn't ever push to this repository unless you are making actual changes to the base scripts. If you are then please take extra care not to rename the folders as this may break the startup script.

If you are cloning this repository to start a new project, you should always push it to its own project specific repository.

Overview

Frontend

This is the server the client will authenticate against and make any requests to. Requests that require data from either the database or ERP should be retreived from the backend server. The client should not make requests to the backend directly.

A more detailed overview of the frontend component of this stack can be found here.

Backend

This server is designed to handle any back end logic for the application. All database or ERP operations or should be handled here.

The connection between the frontend and backend apis is protected by oAuth as standard using a client credentials flow. During local development the oAuth process is bypassed and you will have full access with all available roles.

For deployment to azure, you would need to create two App Registrations. One which exposes the backend api with all the available roles, and another which consumes the first and has a secret that can be used to connect with. This will generate a token with the required roles that is sent to the backend server. The full process is documented in the main pdf documentation.

Any additional (third party) integrations, for example NAV/BC requests to the backend, will need their own app registration with roles assigned for their intended purposes.

A more detailed overview of the backend component of this stack can be found here.

Client

The client is served from an Azure Static Web App. In development this is emulated using the Azure SWA CLI and Azure Function Core Tools for the proxy. The proxy should only ever point to the frontend api for any requests that need to be made and you would need to maintain the proxy.json file to make requests, or use Azure Functions.

The client code is written in react and uses redux for state management. Requests to the frontend api should be done in a redux thunk function.

A more detailed overview of the client component of this stack can be found here.