Commit 3c22bc9c authored by Revant Nandgaonkar's avatar Revant Nandgaonkar

docs: Update Documentation

Fixes and reorganize documentation
One page development how to
Relative image imports

update documentation
parent fb62d721
......@@ -3,5 +3,12 @@
These are set of apps to build an OAuth 2.0 Infrastructure to host Users and Client Apps.
It allows dynamic client registration and client registration for third party apps.
<img src="https://gitlab.com/castlecraft/building-blocks/raw/develop/docs/assets/building-blocks.png">
![cluster](assets/building-blocks.png)
### Development
Start development environment. Refer [section](/development/README.md)
DO NOT setup local development servers to develop apps based on this authorization server and related service.
Host a common setup under a kubernetes namespace for developers.
# Authorization Server Development
Complete the [development setup](/development/README.md)
### Setup Environment
`.env` file for initializing following variables needs to be setup in project root to configure environment. This file is ignored by git.
......@@ -21,64 +19,4 @@ BULL_QUEUE_REDIS_PORT=6379
BULL_QUEUE_REDIS_PASSWORD=admin
```
Note: It is important to change the secrets and password. DO NOT USE example passwords or secrets.
### Setup hosts file
add `127.0.0.1 *.localhost` in `/etc/hosts` file or hosts file of your operating system.
### Setup server with POST request
`authorization-server` needs to have first client (app), i.e `infrastructure-console` for administration dashboard for all apps, users, roles, scopes and general settings.
- Run the script
```
./scripts/setupwiz.py setup-as http://accounts.localhost:3000 Administrator your@email.com Secret@9000 +919876543210 http://admin.localhost:5000
```
Above script would store the `clientId` and `clientSecret` from response to setup Authorization Server.
- Expected response
```
<Response [201]>
```
-Note
```
The password must be at least 10 characters long
The password must contain at least one uppercase letter,
least one number and least one special character.
phone must be MobileE164. (ie. +911234567890)
If you see any response other response such as 400 try the manual way,
making post request on /setup rest endpoint from something like postman or rester add your request parameters to your body,
appURL : http://accounts.example.com,
email : your@email.com,
infrastructureConsoleUrl : http://admin.example.com,
adminPassword : Admin@123,
phone : +911234567890,
issuerUrl : http://accounts.example.com,
fullName : Your_full_name
Response should be something like
{
"redirectUris": [
"http://admin.example.com/index.html",
"http://admin.example.com/silent-refresh.html"
],
"allowedScopes": [],
"uuid": "67cda72c-d214-4b87-a8a2-fcd2acc9c978",
"clientId": "68c373e0-cf3f-46d6-88b4-d56192eb392c",
"clientSecret": "b71915d04dccbda33f99c8d15e677c6da30ebb657910f9cfd0d0b971e7af07c1",
"name": "Infrastructure Console",
"isTrusted": 1,
"userDeleteEndpoint": "http://admin.example.com/connect/v1/user_delete",
"tokenDeleteEndpoint": "http://admin.example.com/connect/v1/token_delete"
}
take clientId, clientSecret from above response and setup infrastructure-console similarly.
```
This sets up Authorization Server as well as Infrastructure Console
Note: It is important to change the secrets and password. DO NOT USE development passwords or secrets.
# Authorization Server Development
Complete the [development setup](/development/README.md)
# Communication Server Development
### Setup Environment
......@@ -13,24 +11,6 @@ DB_USER=communication-server
DB_PASSWORD=admin
```
Note: It is important to change the secrets and password. DO NOT USE example passwords or secrets.
### Setup hosts file
add `127.0.0.1 connect.localhost` in `/etc/hosts` file or hosts file of your operating system.
### Setup server with POST request
- Run the script
```
./scripts/setupwiz.py add-client your@email.com Secret@2019 http://admin.localhost:3000 "Communication Server" http://myaccount.localhost:4100
```
- Expected response
```
<Response [201]>
```
Note: It is important to change the secrets and password. DO NOT USE development passwords or secrets in production.
Use Communication Server to setup personal and system email accounts, cloud storage accounts.
# Development Installation
- Install Docker and Docker compose
- Clone Building Blocks Repository and Start the backing services
### Setup hosts file
add `127.0.0.1 *.localhost` in `/etc/hosts` file or hosts file of your operating system.
### Install Prerequisites
- Docker (to run backing services containers for redis and mongo)
- Docker compose (easy bootstrap of development setup)
- NodeJS
- Python and Python Requests (to setup backend apps on first run)
- VS Code (Editor and NodeJS/TypeScript IDE)
### Install NodeJS global commands
```
# use nvm for better control and secure node environments for users.
# DO NOT USE sudo or root privileges
npm i lerna @angular/cli @nestjs/cli -g
```
### Clone Repository and set working directory
```sh
git clone https://gitlab.com/castlecraft/building-blocks
cd building-blocks/docker
nano .env # setup required environment variables mentioned below
docker-compose --project-name bb -f docker-compose.yml up -d
cd building-blocks
```
### Bootstrap NodeJS package dependencies
```
npm i
lerna bootstrap
```
### Setup Environment Variables
```
code .env # setup required environment variables mentioned below
```
Required environment variables in `.env` file:
......@@ -20,39 +50,93 @@ MONGODB_ROOT_PASSWORD=admin
REDIS_PASSWORD=admin
```
Install NodeJS global commands
Setup Development environment. place appropriate `.env` files under each app's package root
```
npm i lerna @angular/cli @nestjs/cli -g
code apps/authorization-server/.env
```
Bootstrap dependencies
refer [Authorization Server](/authorization-server/README.md) `.env` file
```
cd building-blocks # change directory to repo root
npm i
lerna bootstrap
code apps/communication-server/.env
```
refer [Communication Server](/communication-server/README.md) `.env` file
```
code apps/identity-provider/.env
```
refer [Identity Provider](/identity-provider/README.md) `.env` file
```
code apps/infrastructure-console/.env
```
refer [Infrastructure Console](/infrastructure-console/README.md) `.env` file
### Start Backing Services
```
docker-compose --project-name bb -f docker/docker-compose.yml up -d
```
### Start apps and frontends
Setup Development
Start Development backend and frontend using following commands
```
# for packages in apps/ directory,
# execute following command from the app package root
npm run start:debug
# for packages in frontends/ directory,
# execute following command from the frontend package root
npm start
```
or use VS Code Setup, refer [example](/development/vscode.md)
### Run development setup script
Execute to initialize administrator user and core trusted clients
Note:
- The password must be at least 10 characters long
- The password must contain at least one uppercase letter
- The password must contain at least one number
- The password must contain at least one special character
- phone must be MobileE164. (ie. +911234567890)
- email must be valid email address
```
# export required environment variables
ADMIN_FULL_NAME="Mr Administrator"
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=Secret@9000
ADMIN_PHONE=+919876543210
# Start development backends and frontends and then Run script
export ADMIN_FULL_NAME="Mr Administrator"
export ADMIN_EMAIL=admin@example.com
export ADMIN_PASSWORD=Secret@9000
export ADMIN_PHONE=+919876543210
# Run script
./scripts/setup-dev.sh
# Output
Setting Up Authorization Server and Infrastructure Console
<Response [201]>
Setting Up Identity Provider
<Response [201]>
Setting Up Communication Server
<Response [201]>
```
All apps dependencies and services are up and downloaded. Refer App's development documentation for further development.
All apps dependencies and services are up for debug and development.
# Commands for testing
### Commands for testing
```
# NestJS unit tests
npm run test:server
lerna run test:server
# Drop databases for auth-server e2e
mongo admin -u root -p admin --authenticationDatabase admin
......@@ -60,17 +144,34 @@ mongo admin -u root -p admin --authenticationDatabase admin
> db.dropDatabase()
> exit
# Or use command to drop test database
echo -e "use test_authorization-server;\n db.dropDatabase()" | mongo -u root -p admin --authenticationDatabase admin
# NestJS e2e/integration
npm run test:e2e
lerna run test:e2e
# Angular unit tests
npm run test --watch=false --browsers ChromeHeadless
export NODE_ENV=test
lerna run test
# Angular e2e
npm run e2e
lerna --concurrency 1 run e2e
# Check format
lerna run format:check
# Check Linting
lerna run lint
```
### Commands to format code and lint fixes
```
# To execute from project root
lerna run format && lerna run lint -- --fix
# Format Code and lint
npm run format && npm run lint --fix
# OR execute from app or frontend package root
npm run format && npm run lint -- --fix
```
# TypeScript API Documentation
......
# Authorization Server Development
# Identity Provider Development
Complete the [development setup](/development/README.md)
......@@ -13,26 +13,6 @@ DB_USER=identity-provider
DB_PASSWORD=admin
```
Note: It is important to change the secrets and password. DO NOT USE example passwords or secrets.
### Setup hosts file
add `127.0.0.1 myaccount.localhost` in `/etc/hosts` file or hosts file of your operating system.
### Setup server with POST request
- Run the script
```
./scripts/setupwiz.py add-client your@email.com Secret@2019 http://admin.localhost:3000 "Identity Provider" http://myaccount.localhost:3200
```
Above script would store the `clientId` and `clientSecret` from response to setup app.
- Expected response
```
<Response [201]>
```
Note: It is important to change the secrets and password. DO NOT USE development passwords or secrets in production.
Login to Identity Provider to manage the user profile.
# Authorization Server Development
# Infrastructure Console Development
Complete the [development setup](/development/README.md)
......@@ -13,8 +13,6 @@ DB_USER=infrastructure-console
DB_PASSWORD=admin
```
Note: It is important to change the secrets and password. DO NOT USE example passwords or secrets.
Note: It is important to change the secrets and password. DO NOT USE development passwords or secrets in production.
### Setup
Refer Authorization Server's setup. This service is setup along with authorization-server
Use Infrastructure console to as an adminstration panel for all clients, users and services.
......@@ -7,3 +7,5 @@ This section is set of how-tos and documentation related to kubernetes
helm-charts for all apps are kept in directory `helm-charts`.
Each chart has a README file for details about installation.
Helm Charts : [Github Repo](https://github.com/castlecraft/helm-charts)
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment