From 17a314be4b573c7ff030756aaa5b10ae7043b63a Mon Sep 17 00:00:00 2001 From: Rickard Falk Date: Tue, 5 Nov 2024 09:16:51 +0100 Subject: [PATCH] docs: update README --- README.md | 249 +++++++++------------------------------------------ package.json | 2 +- 2 files changed, 43 insertions(+), 208 deletions(-) diff --git a/README.md b/README.md index 5e6dc60a..ee3a5762 100644 --- a/README.md +++ b/README.md @@ -1,230 +1,65 @@ -# node-web +# Node Web -In an attempt to simplify the process of starting up new node.js based projects, there exists two template projects to use as a foundation. +## Description -The two projects are [node-web](https://github.com/KTH/node-web), a web server with express and react, and [node-api](https://github.com/KTH/node-api), a RESTful api. Both of them use OpenID Connect as a mechanism for authorisation and authentication. +Node Web is a frontend service used together with [node-api](https://github.com/KTH/node-api). It is also a template for Node Web applications developed at KTH. -**The projects can be found here:** -[https://github.com/KTH/node-web](https://github.com/KTH/node-web) -[https://github.com/KTH/node-api](https://github.com/KTH/node-api) +## Installation -It's important that we try to make changes that affect the template projects in the template projects themselves. +### Install Dependencies -> Are you looking for information about converting your app to use OpenID Connect? [Read more](./OIDC_Migration.md) - -## Quickrun - -1. Clone the repo - ```bash - $ git clone git@github.com:KTH/node-web.git - ``` -2. Install dependencies - ```bash - $ npm install - ``` -3. Create a `.env` file in the root of the project [Read more](#Configuration) -4. Add OIDC config in `.env` [Read more](#Where-do-you-keep-you-secrets) -5. Start your Redis [Read more](#Redis---Mandatory) -6. Start the server [Read more](#Starting-the-server) - ```bash - $ npm run start-dev - ``` - -And go to http://localhost:3000/node - -> Note: node-web is by default configured to connected to a api. If you don't have it running when starting node-web there will be errors in your log. No fear, node-web is still working. - -## Development - -### How do I use node-web template project for a project of my own? - -1. Create a new git repository on github.com/KTH (or somewhere else). - -2. Clone the node-web repository by using: - -```bash -git clone git@github.com:KTH/node-web.git NEW_REPOSITORY_NAME -``` - -3. Navigate to the cloned project directory - -4. Change remote repo - -```bash -git remote add origin https://github.com/KTH/.git -``` - -5. Time to code! - -### Configuration - -Configuration during local development are stored in a `.env`-file in the root of your project. **This file needs to be added by you.** - -The .env file should **never** be pushed and is therefore included in the .gitignore file - -When running the app in development mode it's configured to work out of the box except for the LDAP, OIDC (authentication) and SESSION_SECURE_COOKIE, [read more about this below](#Where-do-you-keep-you-secrets). - -Most of the apps configuration resides in `./config/serverSettings.js`. Here you will find what is configured and how to override it. - -Lets look at how to change the port the app is running on. Look for this line in `serverSettings.js` - -``` -port: getEnv('SERVER_PORT', devPort), -``` - -The getEnv function looks for an environment variable `SERVER_PORT`. This is the variable you can override in the .env file. - -Simply add a line in the .env file: - -``` -SERVER_PORT=8080 -``` - -If you want changes that should be used by everyone developing your project, change the default variables in the settings-files (see the `/config` folder). - -### Where do you keep you secrets? - -Secrets during local development are **ALWAYS** stored in the `.env`-file in the root of your project. This file is included in .gitignore so that it's never added to the repository. - -#### OIDC - Mandatory - -Node-web needs OpenID Connect configuration in order for authentication to work properly: - -```bash -OIDC_APPLICATION_ID= -OIDC_CLIENT_SECRET= -OIDC_TOKEN_SECRET= -``` - -In server.js you will find examples of using OIDC for securing your routes. - -### Redis - Mandatory - -We use [Redis](https://redis.io/) for storing sessions and data from Cortina (KTH.se CRM). You need to have a Redis running. - -A recommended way to run Redis (and [Mongodb](https://www.mongodb.com/)) during development is [kth-node-backend](https://gita.sys.kth.se/Infosys/kth-node-backend) - -Default configuration for connecting to redis is `redis://localhost:6379/`. - -If you would like to change this configuration you can add - -`REDIS_URI=` - -to you .env file - -### Path - -If your application is going to be proxied on www.kth.se/your-path make sure you make the following configuration - -#### SERVICE_PUBLISH - -Set a new value in your `.env`-file for SERVICE_PUBLISH e.g - -``` -SERVICE_PUBLISH=/your-path -``` - -#### SESSION_SECURE_COOKIE on localhost - -When you run the application locally during development on http you need to overrride SESSION_SECURE_COOKIE and set it to false. - -``` -SESSION_SECURE_COOKIE=false +```sh +$ npm install ``` -More info, see `config/commonSettings.js`#### Setup Parcel +### Environment Variables -Parcel needs a correct path when generating URLs. +Sensible defaults are set and the application can run locally with a minimal `.env` file. Only `OIDC_APPLICATION_ID` and `OIDC_CLIENT_SECRET` need to be set. They can be retrieved from a key vault in Azure. -Look at the build scripts in package.json +| Name | Description | Default Value | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| `SERVER_HOST_URL` | Address to application | `http://localhost:` + environment variable `SERVER_PORT` | +| `SERVER_PORT` | The HTTP server port | `3000` | +| `SERVICE_PUBLISH` | Root path for the application | `/node` | +| `NODE_API_KEY` | API key to connect to `node-api` | `1234` | +| `NODE_API_URI` | URI to connect to `node-api`, and additional connection parameters | `http://localhost:3001/api/node?defaultTimeout=10000` | +| `OIDC_CONFIGURATION_URL` | URL to OpenID Connect server, used by dependency `@kth/kth-node-passport-oidc` | `https://login.ref.ug.kth.se/adfs/.well-known/openid-configuration` | +| `OIDC_APPLICATION_ID` | Application clientID, used by dependency `@kth/kth-node-passport-oidc` | `null` | +| `OIDC_CLIENT_SECRET` | Application secret, used by dependency `@kth/kth-node-passport-oidc` | `null` | +| `OIDC_TOKEN_SECRET` | Application token secret, used for encrypting token for session storage, used by dependency `@kth/kth-node-passport-oidc` | `tokenSecretString` | +| `OIDC_CALLBACK_URL` | Application’s URL to callback function for standard login, used by dependency `@kth/kth-node-passport-oidc` | `http://localhost:3000${prefixPath}/auth/login/callback`, where `prefixPath` is environment variable `SERVER_PUBLISH` | +| `OIDC_CALLBACK_SILENT_URL` | Application’s URL to callback function for silent login, used by dependency `@kth/kth-node-passport-oidc` | `http://localhost:3000${prefixPath}/auth/silent/callback`, where `prefixPath` is environment variable `SERVER_PUBLISH` | +| `OIDC_CALLBACK_LOGOUT_URL` | Application’s URL to callback function for logout, used by dependency `@kth/kth-node-passport-oidc` | `http://localhost:3000${prefixPath}/auth/logout/callback`, where `prefixPath` is environment variable `SERVER_PUBLISH` | +| `CM_HOST_URL` | URL to CMS, used by dependency `@kth/cortina-block` | `https://www-r.referens.sys.kth.se/cm/` | +| `LOGGING_ACCESS_LOG` | Enables or disabled application access log, used by dependency `kth-node-access-log` | `true` | +| `LOGGING_LEVEL` | Application logging level, used by dependency `@kth/log` | `debug` | +| `SESSION_SECRET` | Application’s session secret, used by dependency `@kth/session` | `1234567890` | +| `SESSION_KEY` | Application’ session key, used by dependency `@kth/session` | `node-web.sid` | +| `REDIS_URI` | URL to [Redis](https://redis.io/), used to store data from CMS and sessions | `redis://localhost:6379/` | +| `SESSION_USE_REDIS` | Enables or disables saving sessions to Redis | `true` | +| `SESSION_SECURE_COOKIE` | Enables or disables using secure cookies for sessions, should be `true` unless in local development | `false` | +| `TOOLBAR_URL` | URL to KTH’s personal menu, KPM | `https://www-r.referens.sys.kth.se/social/toolbar/widget.js` | -You need to change **/node** on both these lines. This is the path for the application. +### Local Databases -``` - ... - "build": "bash ./build.sh prod /node", - "build-dev": "bash ./build.sh dev /node", - ... -``` +- It is recommended to use a local document database (and Redis) with [kth-node-backend](https://github.com/KTH/kth-node-backend) -Example after change: +## Usage -``` - ... - "build": "bash ./build.sh prod /your-path", - "build-dev": "bash ./build.sh dev /your-path", - ... -``` +Start the application in local development mode: -### Starting the server - -Always start by installing dependencies: - -```bash -$ npm install -``` - -Then you need to start the server: - -```bash +```sh $ npm run start-dev ``` -This will - -1. run `parcel build` once to build SASS-files, and prepare browser JavaScript files -2. start `nodemon` which triggers restart when server-side files have been updated -3. run `parcel watch` which triggers a rebuild of browser assets when files have been updated - -And go to http://localhost:3000/node - -### IDE Setup - -> Before you start coding it is important that you have both listed extensions installed in VS Code. +## Running Tests -- [Prettier](https://www.npmjs.com/package/prettier) -- [Eslint](https://www.npmjs.com/package/eslint) +Tests are setup with [Jest](https://jestjs.io/). Run them with: -```bash -$ npm install eslint prettier --save-dev ``` - -#### Linting - -> _From Wikipedia: lint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors, and suspicious constructs._ - -We use ESLint for our linting and our default config comes from the module [eslint-config-kth](https://github.com/KTH/eslint-config-kth) - -See .eslintrc file - -### Debugging - -#### Debugging in VS Code - -If you start Node.js from VS Code you can set breakpoints in your editor. The launch config will look like this: - -```json -{ - "type": "node", - "request": "launch", - "name": "Launch Program", - "program": "${workspaceRoot}/app.js", - "cwd": "${workspaceRoot}", - "env": { - "NODE_ENV": "development" - } -} +$ npm test ``` -Setting NODE_ENV is currently required. - -### Stack +## Contact -- Parcel (Alternative to webpack) -- Babel 7 -- Eslint -- Prettier -- Husky (Pre-commit) -- Sass -- React -- Mobx (State management) +Node Web is developed and maintained by [Team KTH Web](https://github.com/orgs/KTH/teams/web-team). diff --git a/package.json b/package.json index 459aeddb..3c23d610 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "node-web", "version": "2.0.0", - "description": "Template project for a node express web server", + "description": "Node Web is a frontend service used together with node-api. It is also a template for Node Web applications developed at KTH.", "private": true, "license": "MIT", "author": "KTH",