About launching Hyperion and creating your own admin user

Author: Marc-Andrieu

README.md

@@ -255,53 +255,85 @@ The `config.yaml` contains environment variables that are internal to the Python
 
 ## Launch the API
 
+> [!WARNING]
+> Beforehand, check that your venv is activated.
+
+### Using VS Code
+
+1. In the activity bar (the leftmost part), click the _Run and Debug_ icon (the play button).
+2. Click the green play button.
+
+Check that your Hyperion instance is up and running by navigating to http://localhost:8000/information.
+
+### Using the command-line interface
+
 ```bash
 fastapi dev app/main.py
 ```
 
-## Use Alembic migrations
+Check that your Hyperion instance is up and running by navigating to http://localhost:8000/information.
 
-See [migrations README](./migrations/README)
+## Create your own user
 
-Warning : on SQLite databases, you have to drop the database and recreate it to apply the new DDL.
+There are many ways to do so, ranked here from easiest (GUI only) to hardest (CLI only).
+Note that registration and activation are distinct steps, so for fun you may register one way and activate your account another way.
 
-## OpenAPI specification
+### With CalypSSO
 
-API endpoints are parsed following the OpenAPI specifications at `http://127.0.0.1:8000/openapi.json`.
+#### Registering your account
 
-A Swagger UI is available at `http://127.0.0.1:8000/docs`. For authentication to work, a valid `AUTH_CLIENT` must be defined in the `.env`, with `http://127.0.0.1:8000/docs/oauth2-redirect` as the redirect URI, and `scope=API` must be added to the authentication request.
+Go to http://localhost:8000/calypsso/register and type a valid email address to register (start the creation of) your account.
 
-## Create the first user
+#### Activating your account
 
-You can create the first user either using Titan or calling the API directly.
+Go back to the shell running your Hyperion instance, in the logs look for a link looking like http://localhost:3000/calypsso/activate?activation_token=12345.
+Open it and activate (end the creation of) your account.
 
-> You need to use an email with the format `[email protected]` or `[email protected]`
+### With Titan
 
-To activate your account you will need an activation token which will be printed in the console.
+1. Click "_Se connecter_" on the login page: you land CalypSSO's login page.
+2. Click "_Créer un compte_" and create your account using CalypSSO as above.
 
-### With Titan
+### Using the API through the swagger
 
-Press "Créer un compte" on the first page and follow the process.
+#### Registering your account
 
-### Using the API directly
+1. Go to http://localhost:8000/docs: this is called the _swagger_, a web interface to interact with the API, it is a layer on top of the "automatic documentation" (the _OpenAPI specification_) generated by FastAPI at http://localhost:8000/openapi.json.
+2. Search `/users/create`.
+3. Open it, click "Try it out".
+4. Fill in your email address, and click "Execute".
 
-Create the account:
+#### Activating your account
+
+1. Go back to the shell running your Hyperion instance, in the logs look for a link looking like http://localhost:3000/calypsso/activate?activation_token=12345.
+2. Copy this activation token.
+3. Go again on the swagger and search `/users/activate`.
+4. Open it, click "Try it out".
+5. Fill in your information, using the `activation_token` you copied (click "Schema" next to "Edit Value" so see what fields are optional), and click "Execute".
+
+### Using the API in command line
+
+> [!TIP]
+> On Windows, `curl` is different.
+> To get the same results as on Linux and MacOS:
+>
+> - either replace `curl` with `curl.exe`
+> - or run the `curl` commands below in a bash (using WSL or using Git Bash)
+
+#### Registering your account
 
 ```bash
-curl --location 'http://127.0.0.1:8000/users/create' \
---header 'Content-Type: application/json' \
---data-raw '{
-    "email": "<...>@etu.ec-lyon.fr",
-    "account_type": "39691052-2ae5-4e12-99d0-7a9f5f2b0136"
-}'
+curl --json '{"email": "[email protected]"}' http://localhost:8000/users/create
 ```
 
-Activate the account:
+#### Activating your account
+
+1. Go back to the shell running your Hyperion instance, in the logs look for a link looking like http://localhost:3000/calypsso/activate?activation_token=12345.
+2. Copy this activation token.
+3. Use this `activation_token` in:
 
 ```bash
-curl --location 'http://127.0.0.1:8000/users/activate' \
---header 'Content-Type: application/json' \
---data '{
+curl --json '{
     "name": "<Name>",
     "firstname": "<Firstname>",
     "nickname": "<Nickname>",
@@ -311,15 +343,18 @@ curl --location 'http://127.0.0.1:8000/users/activate' \
     "phone": "<Phone>",
     "promo": 0,
     "floor": ""
-}'
+}' http://localhost:8000/users/activate
 ```
 
 ## Make the first user admin
 
+> [!WARNING]
+> This may not work if you ran the factories
+
 If there is exactly one user in the database, you can make it admin using the following command:
 
 ```bash
-curl --location --request POST 'http://127.0.0.1:8000/users/make-admin'
+curl -X POST http://localhost:8000/users/make-admin
 ```
 
 ## Install docker or an equivalent