[O2B-830] Add to global docs

README.md

@@ -1,10 +1,29 @@
 # Bookkeeping
-This repository contains the software for ALICE Bookkeeping.
-
-## Wiki
-- Go to chapter: [Configuration](./docs/CONFIGURATION.md)
-- Go to chapter: [Contributing](./docs/CONTRIBUTING.md)
-- Go to chapter: [Development](./docs/DEVELOPMENT.md)
-- Go to chapter: [Docker](./docs/DOCKER.md)
-- Go to chapter: [gRPC](/docs/grpc.md)
-- ~~Go to chapter: OpenAPI~~ OpenAPI has been removed in version 0.48.0 and is not supported anymore
+This repository contains the software for ALICE Bookkeeping whose main purpose is to keep track of the experiment and provide a history state of the system
+
+Bookkeeping allows users to manually insert system updates which then can be filtered and retrieved to quickly access the information they are looking for. Moreover, it provides the means to other systems to enable them to automatically store and retrieve data. Based on the input, it builds global and individual statistics about  the system performances which in turn helps improving the overall  efficiency of the experiment.
+
+## Installation instructions
+
+What is your use case?
+
+### A. :arrow_right: I want to use Bookkeeping and other O<sup>2</sup> Components.
+
+In order to deploy a fully operational O<sup>2</sup> FLP Suite, please use these [instructions](https://alice-flp.docs.cern.ch/system-configuration/utils/o2-flp-setup/). 
+
+For support, please contact [email protected]
+
+### B. :telescope: I want to use Bookkeeping and connect it to other systems already deployed
+
+You can deploy Bookkeeping on your own setup by following our [SETUP](/docs/setup.md) guide.
+
+### C. :hammer_and_wrench: I want to contribute to Bookkeeping software
+
+You are more than welcomed to contribute to Bookkeeping. Please fellow our [CONTRIBUTING](./docs/CONTRIBUTING.md) guide where you can find out more about how to set up a dev environment and how to follow our coding standards.
+
+## Bookkeeping Requests
+
+If you would like to see a new feature in Bookkeeping, please raise a JIRA ticket and explain the use-case you envisage and why the feature is needed. [JIRA Board](https://alice.its.cern.ch/jira/secure/RapidBoard.jspa?projectKey=O2B)
+
+## Bookkeeping Status
+GitHub Actions: ![Status](https://github.com/AliceO2Group/Bookkeeping/actions/workflows/bookkeeping.yml/badge.svg)

docs/CONTRIBUTING.md

@@ -1,9 +1,16 @@
-# Contributing to AliceO2 Bookkeeping
+# C. 🛠️ I want to contribute to Bookkeeping software
 We would love for you to contribute to *AliceO2 Bookkeeping* and help make it even better than it is today! As a contributor, here are the guidelines we would like you to follow:
-- [Coding conventions](#coding-conventions)
-- [Endpoint conventions](#endpoint-conventions)
-- [Commit Message Guidelines](#commit-message-guidelines)
-- [Trunk based development guidelines](#trunk-based-development)
+
+- [C. 🛠️ I want to contribute to Bookkeeping software](#c-️-i-want-to-contribute-to-bookkeeping-software)
+  - [Coding conventions](#coding-conventions)
+  - [Endpoint conventions](#endpoint-conventions)
+    - [Example](#example)
+  - [Commit Message Guidelines](#commit-message-guidelines)
+    - [Format](#format)
+    - [Examples](#examples)
+  - [Local Development setup](#local-development-setup)
+  - [gRPC](#grpc)
+  - [Trunk based development](#trunk-based-development)
 
 ## Coding conventions
 To ensure consistency throughout the source code, keep these rules in mind as you are working:
@@ -12,19 +19,19 @@ To ensure consistency throughout the source code, keep these rules in mind as yo
 - All code must be formatted. An automated formatter is available (`npm run lint:fix`).
 
 ## Endpoint conventions
-A **resource can be a singleton or a collection**. For example, "`customers`" is a collection resource and "`customer`" is a singleton resource (in a banking domain). We can identify "`customers`" collection resource using the URI "`customers`". We can identify a single "`customer`" resource using the URI "`/customers/{customerId}`".
+A **resource can be a singleton or a collection**. For example, "`logs`" is a collection resource and "`log`" is a singleton resource. We can identify "`logs`" collection resource using the URI "`logs`". We can identify a single "`log`" resource using the URI "`/logs/{logId}`".
 
-A **resource may contain sub-collection resources** also. For example, sub-collection resource "`accounts`" of a particular "`customer`" can be identified using the URI "`/customers/{customerId}/accounts`" (in a banking domain). Similarly, a singleton resource "`account`" inside the sub-collection resource "`accounts"` can be identified as follows: "`/customers/{customerId}/accounts/{accountId}`".
+A **resource may contain sub-collection resources** also. For example, sub-collection resource "`attachments`" of a particular "`log`" can be identified using the URI "`/logs/{logId}/attachments`". Similarly, a singleton resource "`attachment`" inside the sub-collection resource "`logs"` can be identified as follows: "`/logs/{logId}/attachments/{attachmentId}`".
 
 ### Example
 ```
-GET   /orders          <---> orders
-POST  /orders          <---> orders.push(data)
-GET   /orders/1        <---> orders[1]
-PUT   /orders/1        <---> orders[1] = data
-PATCH /orders/1        <---> orders[1] = { ...orders[1], ...data }
-GET   /orders/1/lines  <---> orders[1].lines
-POST  /orders/1/lines  <---> orders[1].lines.push(data)
+GET   /logs          <---> logs
+POST  /logs          <---> logs.push(data)
+GET   /logs/1        <---> logs[1]
+PUT   /logs/1        <---> logs[1] = data
+PATCH /logs/1        <---> logs[1] = { ...logs[1], ...data }
+GET   /logs/1/attachments  <---> logs[1].attachments
+POST  /logs/1/attachments  <---> logs[1].attachments.push(data)
 ```
 
 ## Commit Message Guidelines
@@ -40,14 +47,18 @@ Each commit message consists of a **header** and a **body**. The header has a sp
 
 ### Examples
 ```
-docs(changelog): update changelog to beta.5
+[O2B-111] Update changelog to beta.5
 ```
 ```
-fix(release): need to depend on latest rxjs and zone.js
+[O2B-123] Adds new environment details page
 
-The version in our package.json gets copied to the one we publish, and users need the latest of these.
 ```
 
+## Local Development setup
+In order to setup Bookkeeping for local development, please follow our guide in which we have step by step instructions: [DEVELOPMENT](/docs/DEVELOPMENT.md)
+
+## [gRPC](/docs/grpc.md)
+
 ## Trunk based development
 
 For this project we generally use [trunk based development](https://cloud.google.com/solutions/devops/devops-tech-trunk-based-development).

docs/DEVELOPMENT.md

@@ -1,61 +1,49 @@
 # Development
 
-## Getting started
-### Configuration
-The following `.env` configuration is the bare minimum required for development. It must be placed in the top dir. 
-```ini
-; Database
-MYSQL_ROOT_PASSWORD=cern
-OPENID_ID=
-OPENID_SECRET=
-OPENID_REDIRECT=
+## Prerequisite
 
-JWT_SECRET=
+Local development requires the following programs to run:
+- docker ([documentation](https://docs.docker.com/engine/install/)) and [Docker](./docs/DOCKER.md)
+- npm, which is bundled with nodejs ([download](https://nodejs.org/en/download/))
 
-ATTACHMENT_PATH=/var/storage
+For recent versions of docker, `docker-compose` utility is now part of docker (in `docker compose`). 
+For compatibility reasons, create an alias or a script that aliases `docker-compose` to `docker compose`.
 
-NOTIFICATION_BROKER=
-```
+## Installation
+
+Clone the Bookkeeping project
 
-On mac, the file database/configuration/my.cnf must be modified to set this variable to 1 : 
+```sh
+git clone [email protected]:AliceO2Group/Bookkeeping.git
+cd Bookkeeping
 ```
-lower_case_table_names=1
+
+## Run the docker stack
+
+Use the npm script (the `docker-compose` command must be available to npm)
+
+```sh
+npm run docker-run
 ```
 
-### Running
+You will then see in this tabs the server's log
 
-Execute `npm run docker-run` to launch the application. Once it is running, go to [localhost:4000](localhost:4000).
+### Run seeders [optional]
 
-## Sequlize (CLI)
+For the first time, database can be feed with fake data. To do so:
 
-In order to run those commands locally, you can either install `sequelize-cli` globally or simply run `npm i`.
+Wait until you see the log
 
-### Usage
-```sh
-$ npx sequelize-cli [command]
 ```
-
-### Show help
-```sh
-$ npx sequelize-cli --help
+[DATABASE] info: Executed pending migrations
 ```
 
-### Generates a new migration file
-```sh
-$ npx sequelize-cli migration:generate --name <MIGRATION_FILE_NAME>
-```
+Then you can run seeders in a different terminal window to populate your database
 
-### Run pending migrations
 ```sh
-$ npx sequelize-cli db:migrate
+docker-compose exec application npm run sequelize -- db:seed:all
 ```
 
-### Generates a new seed file
-```sh
-$ npx sequelize-cli seed:generate --name <SEEDER_FILE_NAME>
-```
+### You are ready
 
-### Run every seeder
-```sh
-$ npx sequelize-cli db:seed:all
-```
+You can now open the app at [http://localhost:4000](http://localhost:4000)

docs/setup.md

@@ -0,0 +1,65 @@
+# B. :telescope: I want to use Bookkeeping and connect it to other systems already deployed
+## Getting started
+
+Below instructions, are provided for those who would like to deploy and setup Bookkeeping on its own. For this, you will need:
+- npm, which is bundled with nodejs ([download](https://nodejs.org/en/download/))
+- mariaDB ([download](https://mariadb.org/download/))
+### Configuration
+
+The following `.env` configuration is the bare minimum required for setup. It must be placed in the top dir. 
+```ini
+; Database
+MYSQL_ROOT_PASSWORD=cern
+OPENID_ID=
+OPENID_SECRET=
+OPENID_REDIRECT=
+
+JWT_SECRET=
+
+ATTACHMENT_PATH=/var/storage
+
+NOTIFICATION_BROKER=
+```
+
+On mac, the file `database/configuration/my.cnf` must be modified to set this variable to `1`: 
+```
+lower_case_table_names=1
+```
+
+### Running
+
+Execute `npm run start:prod` to launch the application. Once it is running, go to [localhost:4000](localhost:4000).
+
+## Sequlize (CLI)
+Bookkeeping uses **sequalize** to migrate schemas from one version of Bookkeeping to another. It is also used for seed data into the existing database setup.
+In order to run below commands locally, you can either install `sequelize-cli` globally or simply run `npm ci`.
+
+### Usage
+```sh
+$ npx sequelize-cli [command]
+```
+
+### Show help
+```sh
+$ npx sequelize-cli --help
+```
+
+### Generates a new migration file
+```sh
+$ npx sequelize-cli migration:generate --name <MIGRATION_FILE_NAME>
+```
+
+### Run pending migrations
+```sh
+$ npx sequelize-cli db:migrate
+```
+
+### Generates a new seed file
+```sh
+$ npx sequelize-cli seed:generate --name <SEEDER_FILE_NAME>
+```
+
+### Run every seeder
+```sh
+$ npx sequelize-cli db:seed:all
+```