docs: improve documentation

JeromeBu · JeromeBu · commit d9bb99a1a35b · 2025-06-06T14:52:21.000+02:00
diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@ The full documentation is available [here](https://codegouvfr.github.io/catalogi
 
 1. [https://code.gouv.fr/sill](https://code.gouv.fr/sill/) for the
 list of recommanded Free Software for French administrations.
-2. [https://logiciels.catalogue-esr.fr/](https://logiciels.catalogue-esr.fr/) for the CNRS, listing mostly HAL softwares.
+2. [https://logiciels.catalogue-esr.fr/](https://logiciels.catalogue-esr.fr/) for the French Research Minister, listing mostly HAL softwares.
 
 ## Code organization
 
diff --git a/docker-compose.resources.yml b/docker-compose.resources.yml
@@ -24,7 +24,6 @@ services:
 # an OIDC provider, Keycloak
   keycloak:
     image: quay.io/keycloak/keycloak:26.2.5
-    container_name: keycloak-standalone
     environment:
       KC_BOOTSTRAP_ADMIN_USERNAME: admin
       KC_BOOTSTRAP_ADMIN_PASSWORD: admin
diff --git a/docs/1-about-catalogi.md b/docs/1-about-catalogi.md
@@ -10,18 +10,30 @@ The catalogi software is deployed on different places, such as :
 
 1. [https://code.gouv.fr/sill](https://code.gouv.fr/sill/) for the
 list of recommanded Free Software for French administrations.
-1. [https://logiciels.catalogue-esr.fr/](https://logiciels.catalogue-esr.fr/) for the CNRS, listing mostly HAL softwares.
+1. [https://logiciels.catalogue-esr.fr/](https://logiciels.catalogue-esr.fr/) for the French Research Minister, listing mostly HAL softwares.
 
 
 [Summary](_sidebar.md)
 
 Doc deployment (folder `/docs`) uses [docsify-dsfr-template](https://github.com/codegouvfr/docsify-dsfr-template).
 
-# Contribute
+## Source code
+
+All the source code is hosted on the monorepo : [https://github.com/codegouvfr/catalogi](https://github.com/codegouvfr/catalogi).
+
+It is the source code for 3 differents apps :
+
+* `/web`: The web application, runs in the browser.
+* `/api`: The RPC API consumed by the web application. The code for different jobs is also in this folder.
+* `/docs`: The documentation. It is hosted on [https://codegouvfr.github.io/sill](https://codegouvfr.github.io/sill)
+
+The data is kept in a postgres database .
+
+## Contribute
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-# License
+## License
 
 2021-2025 Direction interministérielle du numérique, mission logiciels libres.
 
diff --git a/docs/2-getting-started.md b/docs/2-getting-started.md
@@ -0,0 +1,81 @@
+# Getting started with Catalogi
+
+## Run in local
+
+To run the application in local, you need :
+- docker and docker-compose, do setup the database, and local keycloak server.
+- nodejs 22 and yarn to run the web application (front and back)
+
+
+1. Clone the repository
+
+```bash
+git clone git@github.com:codegouvfr/catalogi.git
+```   
+
+2. Install the dependencies
+
+```bash
+cd catalogi
+yarn install
+```
+
+3. Create a `.env` file and set the environment variables as needed. You can copy the `.env.sample` file to start with a template.
+
+```bash
+cp .env.sample .env
+```
+
+Than you should adjust the variables in the `.env`, look at [the different variables here](6-env-variables-and-customization.md) for more details.
+
+4. start the local resources with docker-compose
+
+```bash
+docker compose -f docker-compose.resources.yml up --build -d
+```
+
+5. start the frontend and backend in dev
+
+```bash
+yarn dev # from the root, this will run both the frontend and backend `yarn dev`
+```
+
+
+The docker-compose.resources.yml will start: 
+- a postgres database
+- an adminer instance so that you can access the database with a UI (http://localhost:8082)
+- a keycloak server (http://localhost:8080/) in dev mode, with a default admin user `admin` and password `admin`.
+
+## Pushing a new version
+
+When you want to push a new release, you need to update the version number in the root `package.json`.
+The CI will :
+- validate the code
+- create a release on GitHub
+- create the corresponding docker images and push them on docker hub : 
+  - [codegouvfr/catalogi-web](https://hub.docker.com/r/codegouvfr/catalogi-web/tags)
+  - [codegouvfr/catalogi-api](https://hub.docker.com/r/codegouvfr/catalogi-api/tags)
+
+## Deployments
+
+You can deploy Catalogi with the following methods:
+
+- [Docker Compose](4-deploying-with-docker-compose.md)
+- [Kubernetes (with Helm charts)](5-deploying-with-kubernetes.md)
+
+
+## Source code
+
+All the source code is hosted on this repository.
+
+The repository is the source code for 3 differents apps :
+
+* `/web`: The web application, runs in the browser. The site is here : [https://code.gouv.fr/sill](https://code.gouv.fr/sill)
+* `/api`: The RPC API consumed by the web application.
+* `/docs`: The documentation. It is hosted on [https://codegouvfr.github.io/sill](https://codegouvfr.github.io/sill)
+
+The data is hosted on separate repositories:
+* [codegouvfr/sill-data](https://github.com/codegouvfr/sill-data): Production database (private repository).
+* [codegouvfr/sill-data-test](https://github.com/codegouvfr/sill-data-test): Preprod database
+* [codegouvfr/sill-data-template](https://github.com/codegouvfr/sill-data-template): Template for creating new database.
+
diff --git a/docs/3-setup-a-keycloak b/docs/3-setup-a-keycloak
@@ -0,0 +1 @@
+TODO : Document how to set up a Production Keycloak server
diff --git a/docs/4-deploying-with-docker-compose.md b/docs/4-deploying-with-docker-compose.md
@@ -1,5 +1,12 @@
 ## Deploying the web app with docker-compose
 
+# Requirements
+
+To deploy the app using docker compose you need :
+- Docker
+- Docker Compose
+- An OIDC provider like Keycloak, that is already independently deployed
+
 There is an example of how to deploy the sill web app with docker-compose [here](https://github.com/codegouvfr/sill/tree/main/deployments/docker-compose-example).
 
 You can copy paste the folder. Than you will need `.env` file to configure the environnement variables. You can get it by copying the `.env.sample` file from the sill-api repository and modifying it to your needs.
@@ -8,9 +15,7 @@ You can copy paste the folder. Than you will need `.env` file to configure the e
 cp .env.sample .env
 ```
 
-You will need to provide an ssh key in SILL_SSH_PRIVATE_KEY, and it should have the access to the repo you provide in SILL_DATA_REPO_SSH_URL
-
-You will also need to provide a GITHUB_TOKEN.
+Than ajust the variables in the `.env` file to match your OIDC provider, your database and all. [More details about the variables can be found here]()
 
 You can change the way you handle the frontal part in the [nging configuration file](https://github.com/codegouvfr/sill/blob/main/deployments/docker-compose-example/nginx/default.conf).
 The provided example is basic, and for example it does not provide support for `https` (you would need to configure it with you SSL certificates).
diff --git a/docs/5-deploying-with-kubernetes.md b/docs/5-deploying-with-kubernetes.md
@@ -1,3 +1,8 @@
+
+# Deploying Catalogi with Kubernetes
+
+⚠ WARNING - This page of the documentation is obsolete, and will be updated soon. - ⚠
+
 This is a step by step guide for deploying sill.code.gouv.fr
 
 ## The Git based Database
diff --git a/docs/6-env-variables-and-customization.md b/docs/6-env-variables-and-customization.md
@@ -0,0 +1,50 @@
+# Environment Variables and Customization
+
+## Environment variables
+
+The following environment variables are used to configure the Catalogi web application. 
+You can set them in a `.env` file or directly in your environment.
+
+| Variable Name | Required | Default Value | Example Value |
+|----------------|----------|----------------|----------------|
+| OIDC_ISSUER_URI | ✅ | - | `http://localhost:8080/realms/catalogi` |
+| OIDC_CLIENT_ID | ✅ | - | `catalogi` |
+| DATABASE_URL | ✅ | - | `postgresql://catalogi:pg_password@localhost:5432/catalogi` |
+| API_PORT | ❌ | `8080` | `1234` |
+| IS_DEV_ENVIRONNEMENT | ❌ | `false` | `true` |
+| EXTERNAL_SOFTWARE_DATA_ORIGIN | ❌ | `wikidata` | `wikidata` or `HAL` |
+| INIT_SOFT_FROM_SOURCE | ❌ | `false` | `true` |
+| BOT_AGENT_EMAIL | ❌ | - | `bot@example.com` |
+| IMPORT_WIKIDATA | ❌ | - | `Q123,Q456,Q789` |
+| REDIRECT_URL | ❌ | - | `https://catalogi.example.com` |
+
+There is another variable that is purely for frontend configuration, which can contain HTML code, that will be injected in the `<head>` of the web application. It is useful to add meta tags, or other HTML elements that you want to be present in the head of the page. Note that you cannot use the syntay with backticks '`'.
+
+```
+VITE_HEAD="
+  <title>Catalogi - Deployment exemple</title>
+
+  <script defer>
+    console.log('This is a custom code in head');
+  </script>
+"
+```
+
+There are also some variables that are used only for the docker-compose.resources.yml to work properly in dev env. Make sure it is aligned with the `DATABASE_URL` variable above.
+
+```
+POSTGRES_DB=db
+POSTGRES_USER=catalogi
+POSTGRES_PASSWORD=pg_password
+```
+
+## UI Configuration
+
+The UI can be customized, some tabs might not be relevant for your use case. We have a json file that can be used to configure the UI. It is located in `api/src/customization/ui-config.json`. It has to follow the schema defined in `api/src/core/uiConfigSchema.ts`.
+
+
+## Translations
+
+The translations are also configurable, so you can choose any wording you want. Is is defined in `api/src/customization/translations`. There you can add your own translations, providing a `en.json` and `fr.json` file. For now we support only English and French, but fill free to [raise an issue](https://github.com/codegouvfr/catalogi/issues/new) if you want to add more languages.
+
+Please note that you can override the translations you want, and all those that are not overridden will fallback to the default translations provided by the application.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -1,7 +1,14 @@
-* [ℹ README](README.md)
+<!-- * [ℹ About catalogi](1-about-catalogi.md)
 * [🎯 Index](index.md)
 * [🏁 Deploying the web App (Kubernetes)](deploying-with-kubernetes.md)
 * [🏁 Deploying the web App (docker-compose)](deploying-with-docker-compose.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) -->
+
+
+* [ℹ About catalogi](1-about-catalogi.md)
+* [🎯 Getting started](2-getting-started.md)
+* [🏁 Deploying the web App (docker-compose)](4-deploying-with-docker-compose.md)
+* [🏁 Deploying the web App (Kubernetes)](5-deploying-with-kubernetes.md)
+* [⚙ Environment variables and customization](6-env-variables-and-customization.md)
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/setting-up-a-development-environment.md b/docs/setting-up-a-development-environment.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+TODO : Document how to set up a Production Keycloak server`