docs: update readme and onboarding (#1724)

Author: MarceloRobert

README.md

@@ -8,7 +8,7 @@ to static checks, build logs, boot logs and test results related for the Linux k
 CI/test ecosystem. All that data will be provided by [KCIDB](https://docs.kernelci.org/kcidb/)
 system from the [KernelCI Foundation](https://kernelci.org/).
 
-# Repository
+## Repository
 What we have as a repository is a monorepo containing the *dashboard* (the web application) and a *backend*.
 
 ### Dashboard
@@ -18,13 +18,40 @@ A web app built with [React](https://react.dev/) + [Typescript](https://www.type
 A Python http server built with [Django](https://www.djangoproject.com/) + [DRF](https://www.django-rest-framework.org/), to see more information check the backend [README](/backend/README.md).
 
 
-# Build
+## Build
 
-Create a .env file in /dashboard (Do not forget to check and set the variables and their values)
+### Frontend
+
+Create a .env file in /dashboard, check and set the variables and their values
 ```sh
  cp ./dashboard/.env.example ./dashboard/.env
 ```
 
+With docker, you can start just the frontend with `docker compose up --build proxy`. It is also possible to run the dashboard outside of it for development purposes.
+
+We use `pnpm` to help with the package management. Install the dependencies with
+```sh
+pnpm install
+```
+
+Then start the dev server with
+```sh
+pnpm dev
+```
+
+If you want to test the production state of the dashboard, use
+```sh
+pnpm build
+pnpm preview
+```
+
+### Backend
+
+Create a .env file in the base directory,
+```sh
+ cp .env.backend.example .env.bakckend
+```
+
 Create a secret key for Django:
 ```sh
 export DJANGO_SECRET_KEY=$(openssl rand -base64 22)
@@ -59,22 +86,17 @@ If you are going to use a database user other than `kernelci`, set it to `DB_DEF
 export DB_DEFAULT_USER=<user>
 ```
 
-If you are setting up instance different than production KernelCI dashboard, you need to define CORS_ALLOWED_ORIGINS.
-
-docker-compose example:
-```yaml
-services:
-  backend:
-    environment:
-      CORS_ALLOWED_ORIGINS: ["https://d.kernelci.org","https://dashboard.kernelci.org"]
-```
-or .env file example:
+If you are setting up instance different than production KernelCI dashboard, you need to define CORS_ALLOWED_ORIGINS. On .env.backend:
 ```
 CORS_ALLOWED_ORIGINS=["https://d.kernelci.org","https://dashboard.kernelci.org"]
 ```
 
+It is also possible to run the backend outside of docker for development purposes. Simply run the ssh tunnel with the instructions sent to you by the database manager, then export the variables seen in [.env.backend.example](/.env.backend.example).
+
 > For other optional envs, check the [backend README](backend/README.md).
 
+### Common
+
 Startup the services:
  ```sh
  docker compose up --build -d
@@ -90,7 +112,7 @@ sudo -E docker compose up --build -d
 ```
 Or you can also run the env exports and docker compose within the root user by running `sudo su`.
 
-> Tip: you can create a quick script to set all the necessary envs and start the services. This will also allow docker to see the environment variables correclty.
+> Tip: you can create a quick script to set all the necessary envs and start the services. This will also allow docker to see the environment variables correclty. Example:
 
 ```sh
 export DB_DEFAULT_USER=email@email.com
@@ -101,9 +123,9 @@ export DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."
 docker compose up --build
 ```
 
-> [Note] If you are going to run using only a dump of the database, the DB_DEFAULT_NAME should be `dashboard` and the `DB_DEFAULT_USER` and `DB_DEFAULT_PASSWORD` should be `admin` (for now).
+> [Note] If you are going to run using only the local database, the DB_DEFAULT_NAME should be `dashboard` and the `DB_DEFAULT_USER` and `DB_DEFAULT_PASSWORD` should be `admin` (for now).
 > After you define those values, also set the env var `USE_DASHBOARD_DB` to True, setting the local database as the default one.
-> You can also skip the cloud-proxy on such case.
+> You could also set the DB_DEFAULT variables to point to the local database and leave `USE_DASHBOARD_DB` as False.
 
 
 ## Deploying to production
@@ -117,5 +139,5 @@ See details about our new [notifications](docs/notifications.md) system.
 
 ## Contributing 
 
-There is an [onboarding guide](docs/Onboarding.md) to help get acquainted with the project.
+Check out our [CONTRIBUTING.md](/CONTRIBUTING.md), and there is an [onboarding guide](docs/Onboarding.md) to help get acquainted with the project. Contributions are welcome!
 

docs/Onboarding.md

@@ -57,19 +57,20 @@ Definition of Done: The Redis server is running and you do not encounter Redis-r
 
 ### Task 2: Run the Backend locally
 1. Clone the KernelCI Dashboard repository from the following link: https://github.com/kernelci/dashboard
-2. Read the main README.md file to understand the project structure and how to run the project. Don't forget to communicate if there is something that you don't understand and feel free to send a PR with improvements.
-3. Go to the `backend` directory, see the README.md from the backend and run the project locally (read at least up to "Running the server").
+2. Go to the `backend` directory, see the [README.md](../backend/README.md) from the backend and run the project locally (read at least up to "Running the server").
+3. At this point you should have already read the [main README](../README.md) file for a general context of the project and how to run it too. If there are any mistakes feel free to send a PR with corrections and changes.
 
 Definition of Done: You have the KernelCI Dashboard backend running locally.
 
+
 ### Task 3: Get acquainted with the backend
 > Note:
 > Although the example requests use httpie, you can use any other request tool (such as curl, Postman, or Insomnia) to interact with the API.
 
 1. Install [httpie](https://github.com/httpie)
 2. Check the folder `backend/requests` and see that there are multiple bash scripts file, those are httpie requests, try to run some of those. (If one of those requests is not working, it is a good opportunity to created a ticket or fix in a PR).
-3. Try to see in the [KernelCI Dashboard](https://dashboard.kernelci.org/) to see if you can view where those calls are being made.
-4. Try to see how the endpoints you can see where the URLs lead to in the `backend/kernelCI_app/urls.py` file.
+3. Try to look in the [KernelCI Dashboard](https://dashboard.kernelci.org/) to see if you can view where those calls are being made.
+4. Check the URL to endpoint relationship in the [backend/kernelCI_app/urls.py](../backend/kernelCI_app/urls.py) file.
 
 Definition of Done: You have run some requests to the KernelCI Dashboard API and try to have a high level understanding of at least one endpoint from the dashboard to the database.
 
@@ -78,18 +79,20 @@ Definition of Done: You have run some requests to the KernelCI Dashboard API and
 1. Install a Database management software like [DBeaver](https://dbeaver.io/) or [pgAdmin](https://www.pgadmin.org/) 
 2. Connect to the KernelCI Database and try to see the tables and the data that is stored there.
 3. Read this docs to understand the database: [Database Knowledge](../backend/docs/database-logic.md)
-4. Try to make some SQL queries to see what you can do, feel free to look at the Backend code.
+4. Make some direct SQL queries to see what you can do, feel free to look at the Backend code.
 5. Move some data from kcidb to the dashboard_db by running the `update_db` command with `poetry run python3 manage.py update_db`. You don't need a lot of data, specially considering that the database is heavy. For now, just a couple of hours should suffice.
 
-Definition of Done: Run a SQL query that gets all the tests from a specific Tree. (Feel free to choose any), you can post the query Result in the Github Issue.
+Definition of Done: Run a SQL query that gets all the tests from a specific Tree. (Feel free to choose any), post the query Result in the Github Issue.
+
 
 ### Task 5: Run the Frontend locally
-1. Go to the `dashboard` directory, see the README.md from the frontend and try running the project locally.
-2. Look at the folder `api` and see how the requests are made, copy and search for where those requests are being used and see if you can relate with the production dashboard.
+1. Go to the `dashboard` directory, see the [README.md](../dashboard/README.md) from the frontend and try running the project locally.
+2. Look at the folder `api` and see how the requests are made, search for where those functions are being used (where the requests are made) and see if you can relate with the production dashboard.
 3. Try to mess with the code, change some colors, add some logs, try to understand the code structure, if there is a library that you don't know, read the documentation on that.
 
 Definition of Done: You have the KernelCI Dashboard frontend running locally.
 
+
 ### Task 6: Run the project in docker
 
 > [!TIP]