update documentation to have it up to date with latest sill-docs version

docs/README.md

@@ -1,27 +1,33 @@
-# ℹ README
-
-**Le problème à résoudre**
+# Le problème
 
 Les administrations sont encouragées par la loi pour une République numérique à privilégier des logiciels libres pour préserver « la maîtrise, la pérennité et l'indépendance de leurs systèmes d'information » (cf. [Article 16](https://www.legifrance.gouv.fr/loda/article_lc/LEGIARTI000033205068)).
 
-Mais quels logiciels libres utiliser et pourquoi ?  Quand plusieurs logiciels libres remplissent la même fonction, lequel privilégier ?  Quelle version minimale est acceptable ?
+Mais quels logiciels libres utiliser et pourquoi ? Quand plusieurs logiciels libres remplissent la même fonction, lequel privilégier ? Quelle version minimale est acceptable ?
 
 La mise en oeuvre de la loi exige que les administrations puissent se renseigner directement sur les logiciels libres déjà utilisés par d'autres administrations.
 
 Le SILL, Socle Interministeriel de Logiciel Libre, s'attaque à ce problème de partage de l'information.
 
-**Historique**
+# Historique
 
 Le SILL était à l'origine une liste sous format PDF qui était mise à jour tous les ans par les groupes MIM (Mutualisation InterMinistérielle).
 
-La version publique de la liste indiquait les logiciels libres utilisés au sein des administrations centrales et la version à utiliser.  Une liste privée accessibles aux membres des groupes MIM indiquait en plus le nom de l'agent public référent.
+La version publique de la liste indiquait les logiciels libres utilisés au sein des administrations centrales et la version à utiliser. Une liste privée accessibles aux membres des groupes MIM indiquait en plus le nom de l'agent public référent.
 
 Cette liste servaient aux DSI des ministères à faire les mises à jour nécessaires et à découvrir des logiciels libres utilisés par d'autres ministères.
 
 En 2019, le SILL a été publié sous forme d'une application web à l'adresse https://sill.etalab.gouv.fr, qui redirigeait vers https://sill.code.gouv.fr depuis février 2023 jusqu'à présent, et désormais sur https://code.gouv.fr/sill. La page de visualisation était générée à partir de fichiers `csv` maintenus manuellement sur un dépôt public.
 
-En 2022, le SILL a été repensé pour permettre aux agents publics de référencer eux-mêmes des logiciels libres ou de contacter directement l'agent public référent d'un logiciel.  Cette nouvelle version a également vocation de permettre aux agents inscrits des logiciels au sein même de leur navigateur.
+En 2022, le SILL a été repensé pour permettre aux agents publics de référencer eux-mêmes des logiciels libres ou de contacter directement l'agent public référent d'un logiciel. Cette nouvelle version a également vocation de permettre aux agents inscrits des logiciels au sein même de leur navigateur.
 
 [Summary](_sidebar.md)
 
 Ce site de documentation utilise [docsify-dsfr-template](https://github.com/codegouvfr/docsify-dsfr-template).
+
+# Contribuer
+
+Voir [CONTRIBUTING.md](CONTRIBUTING.md).
+
+# Licence
+
+Les contenus de ce dépôt de documentation sont publiés sous [licence Ouverte Etalab 2.0](LICENSES/LICENSE.Etalab-2.0.md).

docs/_sidebar.md

@@ -3,4 +3,4 @@
 * [🏁 Deploying the web App (Kubernetes)](deploying.md)
 * [⚒ Deploying the web App (Bare metal)](deploying-the-web-app-bare-metal.md)
 * [👩💻 Setting up a development environment](setting-up-a-development-environment.md)
-* [🤝 Contributing](contributing.md)
+* [🤝 Contributing](CONTRIBUTING.md)

docs/contributing.md

@@ -1,5 +1,5 @@
-Thank you for you willingnes to contribute, all PRs are welcome!
+Vous pouvez contribuer à ce dépôt de documentation en envoyant des [pull requests](https://github.com/codegouvfr/sill-docs/pulls) ou en remontant des [issues](https://github.com/codegouvfr/sill-docs/issues).
 
-If you don't know where to start, go ahead an try to run the WebApp locally you can start hacking from here.
+Pour contribuer à l'interface, voir le dépôt [sill-web](https://github.com/codegouvfr/sill-web/.)
 
-Here are the [issues](https://github.com/codegouvfr/sill-web/issues) for which your help are welcome.
+Pour contribuer au *backend*, voir le dépôt [sill-api](https://github.com/codegouvfr/sill-api/.)

docs/deploying-the-web-app-bare-metal.md

@@ -48,8 +48,10 @@ sudo apt-get install git
 git clone https://github.com/codegouvfr/sill-api
 git clone https://github.com/codegouvfr/sill-web
 
-# Don't forget to replace by the correct values! 
-# (or at least everywhere there is "xxxx")
+# You can look at 
+# https://github.com/codegouvfr/sill-api/blob/main/.env.sh
+# and https://github.com/codegouvfr/sill-api/blob/main/src/env.ts  
+# For more info on the configuration available.  
 cat << EOF > sill-api/.env.local
 export SILL_KEYCLOAK_URL=https://auth.code.gouv.fr/auth
 export SILL_KEYCLOAK_REALM=codegouv
@@ -68,6 +70,8 @@ export SILL_GITHUB_TOKEN=ghp_xxxxxx
 export SILL_WEBHOOK_SECRET=xxxxxxx
 export SILL_API_PORT=3084
 export SILL_IS_DEV_ENVIRONNEMENT=false
+# Can be "wikidata" or "HAL" (See: https://hal.science/)
+export SILL_EXTERNAL_SOFTWARE_DATA_ORIGIN=wikidata 
 EOF
 ```
 

docs/deploying.md

@@ -85,6 +85,15 @@ https://github.com/codegouvfr/paris-sspcloud/tree/main/cert-manager
 
 ## Installing Keycloak
 
+> UPDATE: Note in this guide we give the instructions for installing Keycloak version 18.  
+> Today it's quite outdated, the latest version ok Keycloak at the time of writing this lines
+> is 23. 
+> I won't update this instruction by fear of making an error if I don't test thoroughly.  
+> You can however refer to the installation guide of Onyxia and adapt the instruction
+> for the SILL: https://docs.onyxia.sh/admin-doc/readme/user-authentication  
+> If you install Keycloak 23 or up don't forget to use `keycloak-theme.jar` instead of `retrocompat-keycloak-theme.jar`
+> (See note below)  
+
 ```bash
 helm repo add codecentric https://codecentric.github.io/helm-charts
 
@@ -131,7 +140,8 @@ extraInitContainers: |
       - |
         curl -L -f -S -o /extensions/keycloak-franceconnect-4.2.0.jar https://github.com/InseeFr/Keycloak-FranceConnect/releases/download/4.2.0/keycloak-franceconnect-4.2.0.jar
         # Here be carefull, the version number should match the version of sill-web in production.
-        curl -L -f -S -o /extensions/sill-web.jar https://github.com/codegouvfr/sill-web/releases/download/v0.0.1/keycloak-theme.jar
+        # Also note that if you are deploying Keycloak 23 or later you should remove the "retrocompat-" in the url below. Keycloak 22 is not supported.  
+        curl -L -f -S -o /extensions/sill-web.jar https://github.com/codegouvfr/sill-web/releases/download/v1.40.3/retrocompat-keycloak-theme.jar
     volumeMounts:
       - name: extensions
         mountPath: /extensions
@@ -242,7 +252,7 @@ You can now login to the **administration console** of **https://sill-auth.my-do
       2. _Email theme_: **dsfr**
       3. _Internationalization_: **Enabled**
       4. _Supported locales_: **en fr**
-    5. On the tab Token
+    5. On the tab Session
        1. SSO Session Idle: 14 days - This setting and the following two are so that when the user click "remember me" when he logs in, he dosen't have to loggin again for the next two weeks.
        2. SSO Session Idle Remember Me: 14 days
        3. SSO Session Max Remember Me: 14 days
@@ -367,6 +377,10 @@ DATA_REPO_SSH_URL="git@github.com:codegouvfr/sill-data.git" # Replace by the rep
 KEYCLOAK_PASSWORD=yyyyyy # Make sure it's the same that the one you defined earlyer
 WEBHOOK_SECRET=dSdSPxxxxxx # (optional) Some random caracters 
 GITHUB_TOKEN=ghp_xxxxxx # A token, just for the GitHub API rate limit.  
+SOFTWARE_DATA_ORIGIN=wikidata # Can be "wikidata" or "HAL" (See: https://hal.science/)
+
+WEB_VERSION="1.41.2" # To keep up to date with https://github.com/codegouvfr/sill-web/releases/
+API_VERSION="1.20.5" # To keep up to date with https://github.com/codegouvfr/sill-api/releases/
 
 cat << EOF > ./sill-values.yaml
 ingress:
@@ -381,7 +395,7 @@ ingress:
 web:
   replicaCount: 2
   image:
-    version: 0.0.1
+    version: $WEB_VERSION
   nodeSelector:
     infra: "true"
   tolerations:
@@ -391,13 +405,14 @@ web:
 api:
   replicaCount: 1
   image:
-    version: 0.0.1
+    version: $API_VERSION
   nodeSelector:
     infra: "true"
   tolerations:
     - key: "infra"
       operator: "Exists"
   env:
+    # For seeing all what's available: https://github.com/codegouvfr/sill-api/blob/main/src/env.ts
     CONFIGURATION: |
       {
         "keycloakParams": {
@@ -419,6 +434,7 @@ api:
         "sshPrivateKeyForGit": "$SSH_PRIVATE_KEY",
         "githubWebhookSecret": "$WEBHOOK_SECRET",
         "githubPersonalAccessTokenForApiRateLimit": "$GITHUB_TOKEN",
+        "externalSoftwareDataOrigin": "$SOFTWARE_DATA_ORIGIN"
       }
 
 EOF
@@ -434,6 +450,6 @@ If you want, and if you data repo is hosted on GitHub you can enable a Webhook t
 
 ![](./assets/webhook.png)
 
-Type some random string as secret. You then need to provide it to `sill-api` so it know it can trust the ping to be genuin (you can do that later, for now just write down the secret).
+Type some random string as secret. You then need to provide it to `sill-api` so it know it can trust the ping to be genuine (you can do that later, for now just write down the secret).
 
 ![](./assets/webhook-2.png)

docs/setting-up-a-development-environment.md

@@ -1,32 +1,71 @@
-You can copy the `.env.sample` to `.env` with the following command:
+## Defining the sill-api parameter
 
-```bash
-cp .env.sample .env
-```
-
-Then you can edit the `.env` file to set the environment variables.
+There are two way to provide the parameter required to run `sill-api`.  
+You can either sourcing environement variables or edit the `.env.local.sh` file.  
 
-You will need to setup the SSH keys.
-These are your github SSH keys. The SSH keys you would use to access to the repo which will be in the `SILL_DATA_REPO_SSH_URL` env variable.
-You need to provide the name of your SSH key too.
-In your local, you can find them in your `~/.ssh` folder.
+### Option 1: Sourcing environement variables
 
-Exemple :
+Makes sure to put the name of your SSH key and the private key (generated when you created the sill-data repo) in your `~/.bash_profile` example:
 
 ```
-SILL_DATA_REPO_SSH_URL=git@github.com:codegouvfr/sill-data-test.git
-SILL_SSH_NAME=your_ssh_key_name
-SILL_SSH_PRIVATE_KEY=your_ssh_key
+export SILL_KEYCLOAK_URL=https://auth.code.gouv.fr/auth
+export SILL_KEYCLOAK_REALM=codegouv
+export SILL_KEYCLOAK_CLIENT_ID=sill
+export SILL_KEYCLOAK_ADMIN_PASSWORD=xxxxxx
+export SILL_KEYCLOAK_ORGANIZATION_USER_PROFILE_ATTRIBUTE_NAME=agencyName
+export SILL_README_URL=https://git.sr.ht/~codegouvfr/logiciels-libres/blob/main/sill.md
+export SILL_TERMS_OF_SERVICE_URL=https://code.gouv.fr/sill/tos_fr.md
+export SILL_JWT_ID=sub
+export SILL_JWT_EMAIL=email
+export SILL_JWT_ORGANIZATION=organization
+export SILL_DATA_REPO_SSH_URL=git@github.com:codegouvfr/sill-data-test.git
+export SILL_SSH_NAME=id_ed25xxxxx
+export SILL_SSH_PRIVATE_KEY="-----BEGIN OPENSSH PRIVATE KEY-----\nxxxx\nxxxx\nxxxx\nAxxxx\nxxxx\n-----END OPENSSH PRIVATE KEY-----\n"
+export SILL_GITHUB_TOKEN=ghp_xxxxxx
+export SILL_WEBHOOK_SECRET=xxxxxxx
+export SILL_API_PORT=3084
+export SILL_IS_DEV_ENVIRONNEMENT=true
 ```
 
-You also need to configuer Keycloak. Most of the information in the `.env.sample` are already set up for you. You just need to set the `SILL_KEYCLOAK_ADMIN_PASSWORD` variable (ask the team).
-
-```
-SILL_KEYCLOAK_URL=https://auth.code.gouv.fr/auth
-SILL_KEYCLOAK_REALM=codegouv
-SILL_KEYCLOAK_CLIENT_ID=sill
-SILL_KEYCLOAK_ADMIN_PASSWORD=xxx_to_provide_it_xxx
-SILL_KEYCLOAK_ORGANIZATION_USER_PROFILE_ATTRIBUTE_NAME=agencyName
+### Option 2: Editing `.env.local.sh`
+
+If you dont like having to source thoses env variables you can prvide them
+by editing the `.env.local.sh` at the root of the `sill-api` project.  
+
+> Skip to the next step and come back here once you'll have cloned the projects.  
+
+`~/sill/sill-api/.env.local.sh`
+```sh
+#!/bin/bash
+
+export CONFIGURATION=$(cat << EOF
+{
+  "keycloakParams": {
+    "url": "https://auth.code.gouv.fr/auth",
+    "realm": "codegouv",
+    "clientId": "sill",
+    "adminPassword": "xxxxxx",
+    "organizationUserProfileAttributeName": "agencyName"
+  },
+  "readmeUrl": "https://git.sr.ht/~codegouvfr/logiciels-libres/blob/main/sill.md",
+  "termsOfServiceUrl": "https://code.gouv.fr/sill/tos_fr.md",
+  "jwtClaimByUserKey": {
+    "id": "sub",
+    "email": "email",
+    "organization": "organization"
+  },
+  "dataRepoSshUrl": "git@github.com:codegouvfr/sill-data-test.git",
+  "sshPrivateKeyForGitName": "id_ed25xxxxx",
+  "sshPrivateKeyForGit": "-----BEGIN OPENSSH PRIVATE KEY-----\nxxxx\nxxxx\nxxxx\nAxxxx\nxxxx\n-----END OPENSSH PRIVATE KEY-----\n",
+  "githubPersonalAccessTokenForApiRateLimit": "ghp_xxxxxx",
+  "githubWebhookSecret": "xxxxxxx",
+  "port": 3084,
+  "isDevEnvironnement": true
+}
+EOF
+) 
+
+$@
 ```
 
 You'll need [Node](https://nodejs.org/) and [Yarn 1.x](https://classic.yarnpkg.com/lang/en/). (Find [here](https://docs.gitlanding.dev/#step-by-step-guide) instructions by OS on how to install them)
@@ -57,7 +96,7 @@ npx tsc -w
 
 # Open a new terminal
 cd ~/sill/sill-api
-yarn dev # Note, there is no hot reload.
+yarn start # Note, there is no hot reload.  
 
 # Open a new terminal
 cd ~/sill/sill-web
@@ -70,7 +109,7 @@ yarn start
 
 ### Frontend (sill-web)
 
-Update [the package.json version number](https://github.com/codegouvfr/sill-web/blob/faeeb89792ee1174fd345717a94ca6677a2adb42/package.json#L4) and push.
+Update [the package.json version number](https://github.com/codegouvfr/sill-web/blob/faeeb89792ee1174fd345717a94ca6677a2adb42/package.json#L4) and push.  
 
 ### Backend (sill-api)