diff --git a/docs/README.md b/docs/README.md index d0d7535b..aa32a993 100644 --- a/docs/README.md +++ b/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). diff --git a/docs/_sidebar.md b/docs/_sidebar.md index ce51e72d..9052a322 100644 --- a/docs/_sidebar.md +++ b/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) diff --git a/docs/contributing.md b/docs/contributing.md index 198b4965..d638e963 100644 --- a/docs/contributing.md +++ b/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/.) diff --git a/docs/deploying-the-web-app-bare-metal.md b/docs/deploying-the-web-app-bare-metal.md index 930b87d1..b6c05514 100644 --- a/docs/deploying-the-web-app-bare-metal.md +++ b/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 ``` diff --git a/docs/deploying.md b/docs/deploying.md index f6e01cbe..007e9e10 100644 --- a/docs/deploying.md +++ b/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) diff --git a/docs/setting-up-a-development-environment.md b/docs/setting-up-a-development-environment.md index 16499de8..f10c0aeb 100644 --- a/docs/setting-up-a-development-environment.md +++ b/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)