diff --git a/README.md b/README.md
index 7389ccc..ea3c8d4 100644
--- a/README.md
+++ b/README.md
@@ -9,3 +9,121 @@ You need [Docker](https://docs.docker.com/engine/) and its [compose](https://doc
 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 or Prettier with fix-on-save).
+
+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 **5006**.
+
+## 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 an ad by its uuid
+
+    ```json
+    {
+        "uuid": "80126a61-d128-4f96-afdb-92e33c75a3e1"
+    }
+    ```
+
+-   **Create** : create an ad (note that uuid is optional, a uuid will be automatically attributed if it is not provided)
+
+    ```json
+    {
+        "userUuid": "113e0000-0000-4000-a000-000000000000",
+        "driver": true,
+        "passenger": false,
+        "frequency": "PUNCTUAL",
+        "departure": "2023-01-15",
+        "toDate": "2023-08-01",
+
+        "marginDurations": {
+            "mon": 800
+        },
+        "seatsPassenger": 0,
+        "seatsDriver": 3,
+        "addresses": [
+            {
+                "lon": 48.68944505415954,
+                "lat": 6.176510296462267,
+                "houseNumber": "5",
+                "street": "Avenue Foch",
+                "locality": "Nancy",
+                "postalCode": "54000",
+                "country": "France"
+            },
+            {
+                "lon": 48.8566,
+                "lat": 2.3522,
+                "locality": "Paris",
+                "postalCode": "75000",
+                "country": "France"
+            }
+        ]
+    }
+    ```
+
+## Messages
+
+As mentionned earlier, RabbitMQ messages are sent after these events :
+
+-   **Create** (message : the created ad informations)
+
+## Tests / ESLint / Prettier
+
+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
+
+# ESLint
+npm run lint
+
+# Prettier
+npm run pretty
+```
+
+## License
+
+Mobicoop V3 - Ad Service is [AGPL licensed](LICENSE).