diff --git a/README.md b/README.md
index a38b152..416cf6c 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,138 @@
 # Mobicoop V3 - Configuration Service
 
-Configuration management.
+Configuration items management. Used to configure all services using a broker to disseminate the configuration items.
+
+Each item consists in :
+
+-   a **domain** : each service is associated with one or more domains, represented by an uppercase string (eg. _USER_)
+-   a **key** : the key of the configuration item (a string)
+-   a **value** : the value of the configuration item (always a string, each service must cast the value if needed)
+
+## Available domains
+
+-   **USER** : user related configuration item
+
+## Requirements
+
+You need [Docker](https://docs.docker.com/engine/) and its [compose](https://docs.docker.com/compose/) plugin.
+
+You also need NodeJS installed locally : we **strongly** advise to install [Node Version Manager](https://github.com/nvm-sh/nvm) and use the latest LTS version of Node (check that your local version matches with the one used in the Dockerfile).
+
+The API will run inside a docker container, **but** the install itself is made outside the container, because during development we need tools that need to be available locally (eg. ESLint, Prettier...).
+
+A RabbitMQ instance is also required to send / receive messages when data has been inserted/updated/deleted.
+
+## Installation
+
+-   copy `.env.dist` to `.env` :
+
+    ```bash
+    cp .env.dist .env
+    ```
+
+    Modify it if needed.
+
+-   install the dependencies :
+
+    ```bash
+    npm install
+    ```
+
+-   start the containers :
+
+    ```bash
+    docker compose up -d
+    ```
+
+    The app runs automatically on port **5003**.
+
+## Database migration
+
+Before using the app, you need to launch the database migration (it will be launched inside the container) :
+
+```bash
+npm run migrate
+```
+
+## Usage
+
+The app exposes the following [gRPC](https://grpc.io/) services :
+
+-   **FindByUuid** : find a configuration item by its uuid
+
+    ```json
+    {
+        "uuid": "80126a61-d128-4f96-afdb-92e33c75a3e1"
+    }
+    ```
+
+-   **FindAll** : find all configuration items; you can use pagination with `page` (default:_1_) and `perPage` (default:_10_)
+
+    ```json
+    {
+        "page": 1,
+        "perPage": 10
+    }
+    ```
+
+-   **Create** : create a configuration item (note that uuid is optional, a uuid will be automatically attributed if it is not provided)
+
+    ```json
+    {
+        "domain": "USER",
+        "key": "key1",
+        "value": "value1"
+    }
+    ```
+
+-   **Update** : update a configuration item
+
+    ```json
+    {
+        "value": "value2",
+        "uuid": "30f49838-3f24-42bb-a489-8ffb480173ae"
+    }
+    ```
+
+-   **Delete** : delete a configuration item by its uuid
+
+    ```json
+    {
+        "uuid": "80126a61-d128-4f96-afdb-92e33c75a3e1"
+    }
+    ```
+
+## Messages
+
+As mentionned earlier, RabbitMQ messages are sent after these events :
+
+-   **Create** (message : the created configuration item informations)
+
+-   **Update** (message : the updated configuration item informations)
+
+-   **Delete** (message : the uuid of the deleted configuration item)
+
+Various messages are also sent for logging purpose.
+
+## Tests
+
+Tests are run outside the container for ease of use (switching between different environments inside containers using prisma is complicated and error prone).
+The integration tests use a dedicated database (see _db-test_ section of _docker-compose.yml_).
+
+```bash
+# run all tests (unit + integration)
+npm run test
+
+# unit tests only
+npm run test:unit
+
+# integration tests only
+npm run test:integration
+
+# coverage
+npm run test:cov
+```
+
+## License
+
+Mobicoop V3 - Configuration Service is [AGPL licensed](LICENSE).