fixup! 📝(project) add a ralph lrs tutorial

docs/tutorials/lrs/authentication/basic.md

@@ -23,7 +23,7 @@ To create a new user credentials, Ralph CLI provides a dedicated command:
 === "Docker Compose"
 
     ```bash
-    docker compose run --rm ralph-lrs \
+    docker compose run --rm lrs \
       bin/ralph auth \
         --username janedoe \
         --password supersecret \
@@ -59,7 +59,7 @@ The credentials file can also be created manually. It is expected to be a valid
 specified by the `RALPH_AUTH_FILE` configuration value. 
 
 !!! tip
-    By default, Ralph LRS will look for the `auth.json` file in the application directory (see [click
+    By default, Ralph LRS looks for the `auth.json` file in the application directory (see [click
     documentation for
     details](https://click.palletsprojects.com/en/8.1.x/api/#click.get_app_dir)).
 
@@ -78,12 +78,12 @@ The expected format is a list of entries (JSON objects) each containing:
 ## Making a GET request
 
 After changing the `docker-compose.yml` file as follow:
-``` yaml hl_lines="10"
+``` yaml hl_lines="10" title="docker-compose.yml"
 version: "3.9"
 
 services:
 
-  ralph-lrs:
+  lrs:
     image: fundocker/ralph:latest
     environment:
       - RALPH_APP_DIR: /app/.ralph
@@ -102,11 +102,20 @@ services:
 and running the Ralph LRS with:
 
 ```bash
-docker compose up -d
+docker compose up -d lrs
 ```
 
 we can try to make a request to the `whoami` endpoint again, but this time sending our username and password through Basic Auth:
 
+=== "curl"
+
+    ```
+    curl --user janedoe:supersecret http://localhost:8100/whoami
+    ```
+    ``` console
+    {"agent":{"mbox":"mailto:[email protected]","objectType":"Agent","name":null},"scopes":["janedoe_scope"]}
+    ```
+
 === "HTTPie"
 
     ``` 
@@ -130,12 +139,3 @@ we can try to make a request to the `whoami` endpoint again, but this time sendi
         ]
     }
     ```
-
-=== "curl"
-
-    ```
-    curl --user janedoe:supersecret http://localhost:8100/whoami
-    ```
-    ``` console
-    {"agent":{"mbox":"mailto:[email protected]","objectType":"Agent","name":null},"scopes":["janedoe_scope"]}
-    ```

docs/tutorials/lrs/authentication/oidc.md

@@ -23,17 +23,6 @@ The [Learning analytics playground](https://github.com/openfun/learning-analytic
 
 With the Keycloak instance running, we can get the access token from Keycloak:
 
-=== "HTTPie"
-
-    ```bash
-    http --form POST :8090/auth/reals/fun-mooc/protocol/openid-connect/token \
-      client_id="ralph" \
-      client_secret="super-secret" \
-      username="ralph_admin" \
-      password="funfunfun" \
-      grant_type="password"
-    ```
-
 === "curl"
 
     ```bash
@@ -46,6 +35,17 @@ With the Keycloak instance running, we can get the access token from Keycloak:
       --data-urlencode 'grant_type=password'
     ```
 
+=== "HTTPie"
+
+    ```bash
+    http --form POST :8090/auth/reals/fun-mooc/protocol/openid-connect/token \
+      client_id="ralph" \
+      client_secret="super-secret" \
+      username="ralph_admin" \
+      password="funfunfun" \
+      grant_type="password"
+    ```
+
 which outputs (*tokens truncated for example purpose*):
 
 ```json
@@ -63,16 +63,17 @@ which outputs (*tokens truncated for example purpose*):
 
 If we now send the access token to the API server as a Bearer header:
 
-=== "HTTPie"
-    ```bash
-    http -A bearer -a eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSTWlLM :8100/whoami
-    ```
-
 === "curl"
     ```bash
     curl http://localhost:8100/whoami --A "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSTWlLM"
     ```
 
+=== "HTTPie"
+    ```bash
+    http -A bearer -a eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJSTWlLM :8100/whoami
+    ```
+
+
 Ralph LRS returns our authenticated user:
 
 ``` console

docs/tutorials/lrs/backends.md

@@ -12,7 +12,7 @@ Let's add the service of your choice to the `docker-compose.yml` file:
 
 === "Elasticsearch"
 
-    ``` yaml hl_lines="4-19 25"
+    ``` yaml title="docker-compose.yml" hl_lines="4-19 25"
     version: "3.9"
 
     services:
@@ -55,18 +55,21 @@ Let's add the service of your choice to the `docker-compose.yml` file:
     ```
 
     Before using elasticsearch, we need to create an index, here `statements`:
+    === "curl"
+
+        ```bash
+        curl -X PUT http://localhost:9200/statements
+        ```
+
     === "HTTPie"
 
         ```bash
         http PUT :9200/statements
         ```
-    === "curl"
-        ```bash
-        curl -X PUT http://localhost:9200/statements
 
 === "Mongo"
 
-    ``` yaml hl_lines="4-12 18"
+    ``` yaml title="docker-compose.yml" hl_lines="4-12 18"
     version: "3.9"
 
     services:
@@ -102,7 +105,7 @@ Let's add the service of your choice to the `docker-compose.yml` file:
 
 === "ClickHouse"
 
-    ``` yaml hl_lines="4-22 28"
+    ``` yaml title="docker-compose.yml" hl_lines="4-22 28"
     version: "3.9"
 
     services:
@@ -126,7 +129,7 @@ Let's add the service of your choice to the `docker-compose.yml` file:
             interval: 1s
             retries: 60
 
-      ralph-lrs:
+      lrs:
         image: fundocker/ralph:latest
         environment:
           - RALPH_APP_DIR: /app/.ralph
@@ -155,18 +158,6 @@ docker compose up -d lrs
 
 We can finally send some xAPI statements to Ralph LRS:
 TODO simplify this step, by providing some simple statements in a local file
-=== "HTTPie"
-
-    ```bash
-    curl -sL \
-      https://github.com/openfun/potsie/raw/main/fixtures/elasticsearch/lrs.json.gz | \
-    gunzip | \
-    head -n 100 | \
-    jq -s . | \
-    sed "s/@timestamp/timestamp/g" | \
-    http -a janedoe:supersecret POST :8100/xAPI/statements
-    ```
-
 === "curl"
 
     ```bash
@@ -184,19 +175,32 @@ TODO simplify this step, by providing some simple statements in a local file
       -d @-
     ```
 
-And fetch, them back: 
-
 === "HTTPie"
 
     ```bash
-    http -a janedoe:supersecret :8100/xAPI/statements
+    curl -sL \
+      https://github.com/openfun/potsie/raw/main/fixtures/elasticsearch/lrs.json.gz | \
+    gunzip | \
+    head -n 100 | \
+    jq -s . | \
+    sed "s/@timestamp/timestamp/g" | \
+    http -a janedoe:supersecret POST :8100/xAPI/statements
     ```
 
+
+And fetch, them back: 
+
 === "curl"
 
     ```bash
     curl \
       --user janedoe:supersecret \
       -X GET \
       "http://localhost:8100/xAPI/statements"
-    ```
+    ```
+
+=== "HTTPie"
+
+    ```bash
+    http -a janedoe:supersecret :8100/xAPI/statements
+    ```

docs/tutorials/lrs/first-steps.md

@@ -10,7 +10,7 @@ version: "3.9"
 
 services:
 
-  ralph-lrs:
+  lrs:
     image: fundocker/ralph:latest
     environment:
       - RALPH_APP_DIR: /app/.ralph
@@ -31,12 +31,21 @@ For now, we are using the `fs` (File System) backend, meaning that Ralph LRS wil
 We can run Ralph LRS from a terminal with the command:
 
 ```bash
-docker compose up -d
+docker compose up -d lrs
 ```
 
 Ralph LRS server should be up and running!
 
-We can try making a request to the `whoami` endpoint, which checks if the user is authenticated and returns their username and permission scopes.
+We can try making a request to the `whoami` endpoint, to check if the user is authenticated and returns their username and permission scopes.
+
+=== "curl"
+
+    ```bash
+    curl http://localhost:8100/whoami
+    ```
+    ```console
+    {"detail":"Could not validate credentials"}% 
+    ```
 
 === "HTTPie"
 
@@ -57,14 +66,5 @@ We can try making a request to the `whoami` endpoint, which checks if the user i
 
     ```
 
-=== "curl"
-
-    ```bash
-    curl http://localhost:8100/whoami
-    ```
-    ```console
-    {"detail":"Could not validate credentials"}% 
-    ```
-
 We cannot access this endpoint as we are not authenticated.
 Let's shutdown Ralph LRS server with the command `docker compose down` and set up authentication.

docs/tutorials/lrs/forwarding.md

@@ -20,12 +20,12 @@ the following key/value pairs:
 | `max_retries`    | `number`   | Specifies the number of times a failed forwarding request should be retried.  |
 | `timeout`        | `number`   | Specifies the duration in seconds of network inactivity leading to a timeout. |
 
-> Note that for a forwarding configuration to be valid it is required that all key/value
-> pairs are defined.
+!!! warning
+    For a forwarding configuration to be valid it is required that all key/value pairs are defined.
 
 Example of a valid forwarding configuration:
 
-```bash
+```bash title=".env"
 RALPH_XAPI_FORWARDINGS='
 [
   {

docs/tutorials/lrs/index.md

@@ -4,8 +4,8 @@ This tutorial shows you how to run Ralph LRS, step by step.
 
 !!! warning
 
-    Ralph LRS will be executed locally for a demonstration purpose.
-    If you want to deploy Ralph LRS on a production server, refer to the section **Ralph LRS deployment**.
+    Ralph LRS will be executed locally for demonstration purpose.
+    If you want to deploy Ralph LRS on a production server, please refer to the section **Ralph LRS deployment**.
 
 Ralph LRS is based on [FastAPI](https://fastapi.tiangolo.com/).
 In this tutorial, we will run the server manually with [Uvicorn](https://www.uvicorn.org/), but other alternatives exists ([Hypercorn](https://pgjones.gitlab.io/hypercorn/), [Daphne](https://github.com/django/daphne)).

docs/tutorials/lrs/multitenancy.md

@@ -7,7 +7,7 @@ By default, all authenticated users have full read and write access to the serve
 
 In Ralph LRS, all incoming statements are assigned an `authority` (or ownership) derived from the user that makes the call. You may restrict read access to users "own" statements (thus enabling multitenancy) by setting the following environment variable: 
 
-```bash
+```bash title=".env"
 RALPH_LRS_RESTRICT_BY_AUTHORITY = True # Default: False
 ```
 
@@ -22,14 +22,13 @@ RALPH_LRS_RESTRICT_BY_AUTHORITY = True # Default: False
 In Ralph, users are assigned scopes which may be used to restrict endpoint access or 
 functionalities. You may enable this option by setting the following environment variable:
 
-```bash
+```bash title=".env"
 RALPH_LRS_RESTRICT_BY_SCOPES = True # Default: False
 ```
 
 Valid scopes are a slight variation on those proposed by the
 [xAPI specification](https://github.com/adlnet/xAPI-Spec/blob/master/xAPI-Communication.md#details-15):
 
-
 - statements/write
 - statements/read/mine
 - statements/read

docs/tutorials/lrs/sentry.md

@@ -4,22 +4,25 @@
 Ralph provides Sentry integration to monitor its LRS server and its CLI.
 To activate Sentry integration, one should define the following environment variables:
 
-```bash
+```bash title=".env"
 RALPH_SENTRY_DSN={PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}{PATH}/{PROJECT_ID}
 RALPH_EXECUTION_ENVIRONMENT=development
 ```
 
 The Sentry DSN (Data Source Name) can be found in your project settings from Sentry application. The execution environment should reflect the environment Ralph has been deployed in (_e.g._ `production`).
 
 You may also want to [monitor the performance](https://develop.sentry.dev/sdk/performance/) of Ralph by configuring the CLI and LRS traces sample rates:
-```bash
+
+```bash title=".env"
 RALPH_SENTRY_CLI_TRACES_SAMPLE_RATE=0.1
 RALPH_SENTRY_LRS_TRACES_SAMPLE_RATE=0.3
 ```
-> Note that a sampling rate of `1.0` means 100% of transactions are sent to sentry and `0.1` only 10%.
+!!! info "Sample rate"
+
+    A sample rate of `1.0` means 100% of transactions are sent to sentry and `0.1` only 10%.
 
 If you want to lower noisy transactions (_e.g._ in a Kubernetes cluster), you can disable health checks related ones:
 
-```bash
+```bash title=".env"
 RALPH_SENTRY_IGNORE_HEALTH_CHECKS=True
 ```