fix: update install docs (#39)

* fix: update install docs

* fix: make PR requested changes

docs/developer/getting-started.md

@@ -2,7 +2,7 @@
 sidebar_position: 2
 ---
 
-# Getting Started
+# Getting Started {#getting-started}
 
 In this page we guide you through setting up a working local development environment.
 By the end of this guide you should have a working version of the Graasp platform running on your computer.
@@ -16,15 +16,28 @@ You can head over to [the Graasp App Development section](/developer/apps/intro)
 We will assume that you have a UNIX compatible machine at your disposal (Mac, Linux or Windows with WSL). All instructions should work independently of the environment. If you encounter problems, please [open an issue](https://github.com/graasp/docs/issues/new).
 :::
 
-## Requirements
+## Requirements {#requirements}
 
 If not done already please install these required tools
 
 - [Docker Desktop](https://www.docker.com/products/docker-desktop/) (if using Mac or Windows), on Linux you should be good with installing the docker package.
-- [Node](https://nodejs.org/en/download) version 20 or above with `nvm` (recommend)
+- [Node](https://nodejs.org/en/download) version 20 or above with `volta` or `nvm` (recommend, see the [intro section](./intro#required))
 - `git` for version control operations
 
-### Enabling Yarn with `nvm`
+### Installing Yarn with `volta` {#with-volta}
+
+Volta allows you to use global packages as if you were using local ones.
+
+```bash
+volta install node
+volta install yarn
+```
+
+### Enabling Yarn with `nvm` {#with-nvm}
+
+:::note
+Skip this section if you are using `volta` as your package manager.
+:::
 
 Yarn is a package manager for node and javascript projects. It is faster than `npm`.
 The recommended way of enabling yarn is using `corepack`.
@@ -38,52 +51,105 @@ You should now have `yarn` enabled with your version of node defined by nvm. To
 This operation should be repeated every time you update the version of node you use.
 :::
 
-## Backend installation
+## Backend installation {#backend}
 
 ### Getting the source code
 
 Go to the [Graasp backend repo](https://github.com/graasp/graasp) and clone it locally.
 
-### Opening dev containers
+:::tip
+If you are using the [`Github CLI`](https://cli.github.com/) simply `gh repo clone graasp/graasp`.
+We recommend using the Github CLI as it helps with interacting with GitHub trough the terminal if this is your thing. (We think it is is faster for a lot of things, but you are welcome to use a GUI (Graphical user interface) if you prefer.)
+:::
 
-Open the repo in VSCode. Make sure the ["Dev Containers" extension](https://code.visualstudio.com/docs/devcontainers/tutorial#_install-the-extension) is downloaded and enabled.
+### Opening dev containers {#dev-containers}
 
-Then open the folder in the dev-container by using the command palette `cmd`+`shift`+`P` (or `ctrl` instead of `cmd`), and typing **Open Folder in Container**.
+1. Open the Docker Desktop app.
 
-### Installing dependencies
+:::note
+This app should run in the background. You do not need to add have it automatically start when you open your session. It simply needs to run when you want to use the backend to code.
+:::
+
+2. Open the repo in VSCode. Make sure the ["Dev Containers" extension](https://code.visualstudio.com/docs/devcontainers/tutorial#_install-the-extension) is downloaded and enabled.
+
+3. Then open the folder in the dev-container by using the command palette `cmd`+`shift`+`P` (or `ctrl` instead of `cmd`), and typing **Open Folder in Container**.
+
+4. You should now wait for VSCode to pull the containers and initialize the development environnement. You will know that the process if finished once the window says: `workspace [Dev Container: Node.js & PostgreSQL @desktop-linux]` and no more loaders are present.
+
+If you encounter an error at this stage, make sure that the Docker Desktop app is open. If you encounter an issue with the definition of the dev-container not willing to start you can open an issue on the [graasp backend repository on GitHub](https://github.com/graasp/graasp/issues/new) or send an email to [the graasp developers](mailto:dev@graasp.org). We try to offer support as best as we can.
 
-After the containers are up and running execute `yarn` (you can do `yarn install` which is the same) in the container terminal to install dependencies.
+### Installing dependencies {#dependencies}
 
-### Add environment variables
+After the containers are up and running execute `yarn` (you can also run `yarn install` which is the same) in the dev-container terminal (in VSCode) to install the backend dependencies.
 
-Go to [the configuration in the Readme](https://github.com/graasp/graasp#configuration) and copy it to a new root file in your backend folder named `.env.development`.
+:::tip
+The install command will take some time to run the first time. This is a good time to take a small break, enjoy a :coffee: or a :tea:.
+:::
+
+:::note
+If the command exits with an error you might have to allocate more resources to the docker container.
 
-You will need to generate a few secret values. Open the `.env.development` file and look of places that ask for these.
+For this go to the Docker Desktop app settings and under "Resources" allocate up to 8GB of RAM (depending on your system resources you might want to allocate less) and up to 4CPUs.
+:::
+
+### Add environment variables {#env-variables}
+
+Open [the configuration in the README.md](https://github.com/graasp/graasp#configuration).
+Copy it to a new file named `.env.development` in the root of your backend folder.
+
+Most of the configuration values have already been set for you in the readme, but you will need to generate some secret keys for your application.
+
+#### Secret keys {#secret-keys}
+
+Open the `.env.development` file and look for places that ask for `<secret-key>`.
 The first one should be `SECURE_SESSION_SECRET_KEY`.
 To generate a secret you can simply run:
 
 ```sh
 npx @fastify/secure-session > secret-key && node -e "let fs=require('fs'),file=path.join(__dirname, 'secret-key');console.log(fs.readFileSync(file).toString('hex'));fs.unlinkSync(file)"
 ```
 
-Replace the `<content>` placeholder with the output of the command (a string of numbers).
-Repeat the process until you have generated all necessary keys. You can search for `<content>` in the file in order to located them.
+Replace the `<secret-key>` placeholder with the output of the command (a string of numbers).
+Repeat the process until you have generated all necessary keys. You can search for `<secret-key>` in the file in order to located them  (you can use `cmd+f` to search in the file).
+
+#### Google RECAPTCHA key
+
+:::note
+This part should be optional, but if you want to be as close as possible to the how the app works in the real world, it is recommended to set it up.
+
+See detailed information in the [section below](#recaptcha-key)
+:::
+
+<!-- TODO: this needs to be further detailed before we can make it visible
+#### OpenAI API Key {#open-ai-key}
+
+:::note
+Also optional, this part allows you to have access to ChatGPT functionality in the Graasp Apps running in your local environnement.
 
-### Running backend
+This requires an OpenAI account and a payment method. See [OpenAI documentation](https://openai.com/pricing).
+::: -->
 
-We should be all set. Run `yarn watch` to start the backend server.
+### Launching the backend server {#running-backend}
+
+We should be all set. Run `yarn watch` in the VSCode terminal to start the backend server.
+
+Wait a moment, for the server to build, will see the `[Node] [nodemon] restarting due to changes...` text printed to the console. Wait to see:
+
+```text
+[Node] {"level":30,"time":1709056074491,"pid":33974,"hostname":"4ca0ec878e31","msg":"Server listening at http://0.0.0.0:3000"}
+```
 
-If everything went well, opening `http://localhost:3000/status` in your browser should greet you with "OK".
+If everything went well, opening [`http://localhost:3000/status`](http://localhost:3000/status) in your browser should greet you with "OK".
 
-If you are facing an error, check [the Troubleshooting page](/developer/trouble-shooting) to see if your issue is mentioned there.
+If you are facing an error, check [the Troubleshooting page](./trouble-shooting) to see if your issue is mentioned there.
 
 :::tip
 Your browser might not be able to resolve the `localstack` domain when uploading and viewing files. To use localstack with the Docker installation, it is necessary to edit your `/etc/hosts` with the following line `127.0.0.1 localstack`. This is necessary because the backend creates signed urls with the localstack container hostname. Without changing the hosts, the development machine cannot resolve the `http://localstack` hostname.
 
 **Do not forget to reboot your computer for these changes to take effect**
 :::
 
-## Frontend installation
+## Frontend installation {#frontend}
 
 With the backend server running we will now need to clone, install and run the client applications.
 
@@ -106,7 +172,7 @@ For each one:
 - Create the necessary `.env.development` file in each project. Look for instructions and examples about this in the Readme of each project
 - Start each project with `yarn start`
 
-### Generating reCaptcha keys for auth and the backend
+### Generating reCaptcha keys for auth and the backend {#recaptcha-key}
 
 You will likely need to generate your own RECAPTCHA key in order for the auth frontend to be able to send requests to the backend. For this you will need a Google account.
 
@@ -118,14 +184,14 @@ You will likely need to generate your own RECAPTCHA key in order for the auth fr
 - Add the `localhost` domain
 
 Once that is done, you should get 2 keys, a **Site key** and a **Secret key**.
-The **Site key** should go into the `.env.development` file from the Auth project.
-The **Secret key** should go into the `.env.development` file from the backend project.
+The **Site key** should go into the `.env.development` file from the Auth project under the `VITE_RECAPTCHA_SITE_KEY` variable.
+The **Secret key** should go into the `.env.development` file from the backend project under the `<google-recaptcha-key>` placeholder.
 
 :::danger
 Do not share these keys with anyone. Do not push them to version control (git). If you loose them, you can always re-generate new keys.
 :::
 
-## Making sure everything works
+## Making sure everything works {#everything-together}
 
 With the default setup you should have the following:
 
@@ -154,7 +220,7 @@ If you are able to upload but there is an error when you want to display the fil
 If you restart you computer, the stored files will disappear, but not their item record. This is expected as localstack (the solution we use to fake s3 storage) does not provide persistence without buying the "pro" license.
 :::
 
-## Conclusion
+## Conclusion {#conclusion}
 
 If you are still here, congratulations, you have successfully installed a development version of Graasp. You can take a well deserved break with a coffee or tea.
 

docs/developer/intro.md

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-# Introduction
+# Introduction {#intro}
 
 This is the documentation of the Graasp digital education platform targeted at developers.
 
@@ -20,7 +20,7 @@ This documentation focuses on:
 - the guidelines and protocols to participate and contribute in the development of Graasp
 - a technical description of the architecture and features of Graasp
 
-## Prerequisites
+## Prerequisites {#pre-requisites}
 
 This documentation assumes that you are familiar with the command line.
 We will guide you and tell you which commands to run, but it is best if you can understand what they will do.
@@ -31,25 +31,27 @@ If you need a complete refresher on how to do web development you should have a
 
 Here we list the tools that you should have installed in order to make your development work easier.
 
-### Required
+### Required {#required}
 
 - A modern browser: Chrome, Firefox or others will work, choose based on your personal preference
 - [Node.js](https://nodejs.org/en/download) version 20.0 or above:
-  - We recommend to use [`nvm`, the node version manager](https://github.com/nvm-sh/nvm)
+  - We recommend to use [`volta`, a node version manager](https://volta.sh/)
+  - You can also use [`nvm`, an older node version manager](https://github.com/nvm-sh/nvm)
 - A code editor: we recommend that you use [VSCode](https://code.visualstudio.com) because we will be using [devcontainers](https://code.visualstudio.com/docs/devcontainers/containers) to create our development environment for the backend.
 - [Docker Desktop](https://www.docker.com/products/docker-desktop/): to run containers
 
-### Nice to have
+### Nice to have {#nice-to-have}
 
 - [Postman](https://www.postman.com/downloads): lets you send API requests with a GUI
 - [Starship](https://starship.rs/): a utility to improve your terminal prompt (git branch, node version etc...)
 
-## Best practices
+## Best practices {#tools}
 
 We use:
 
 - [Typescript](https://www.typescriptlang.org/)
 - [Linters](https://eslint.org/)
 - [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
 - Test suits: [Cypress](https://www.cypress.io/) and [Playwright](https://playwright.dev/)
-- [Semantic versionning](https://semver.org/)
+- [Storybook](https://storybook.js.org/) for component library design, prototyping and documentation
+- [Semantic versioning](https://semver.org/)