diff --git a/README.md b/README.md
index 23b8fb9..272b145 100644
--- a/README.md
+++ b/README.md
@@ -6,32 +6,42 @@ Authentication (AuthN) and Authorization (AuthZ) data management.
 
 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` :
+- copy `.env.dist` to `.env` :
 
-```bash
-cp .env.dist .env
-```
+    ```bash
+    cp .env.dist .env
+    ```
 
-and modify it to suit your needs.
+    Modify it if needed.
 
-Then execute :
+- start the containers :
 
-```bash
-docker compose up -d
-```
+    ```bash
+    docker compose up -d
+    ```
 
-The app runs automatically on the port defined in `SERVICE_PORT` of `.env` file (default : _5002_).
+    The app runs automatically on port **5002**.
+
+- install the dependencies :
+
+    ```bash
+    npm install
+    ```
 
 ## Database migration
 
-Before using the app, you need to launch the database migration :
+Before using the app, you need to launch the database migration (it will be launched inside the container) :
 
 ```bash
-docker exec v3_user sh -c "npx prisma migrate dev"
+npm run migrate
 ```
 
 ## Usage
@@ -116,18 +126,25 @@ For AuthN, the app exposes the following [gRPC](https://grpc.io/) services :
 
 Various RabbitMQ messages are sent for logging purpose.
 
-## Test
+## 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
-# unit tests
-docker exec v3_user sh -c "npm run test"
+# run all tests (unit + integration)
+npm run test
 
-# test coverage
-docker exec v3_user sh -c "npm run test:cov"
+# unit tests only
+npm run test:unit
+
+# integration tests only
+npm run test:integration
+
+# coverage
+npm run test:cov
 ```
 
-Note : you can run all npm commands directly _outside_ the container (see _scripts_ section of `package.json` for available commands), but you 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.
-
 ## License
 
 Mobicoop V3 - Auth Service is [AGPL licensed](LICENSE).
diff --git a/package.json b/package.json
index 4fc96c2..dc128b4 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,7 @@
     "test:integration": "npm run migrate-test && dotenv -e .env.test -- jest --testPathPattern 'integration' --verbose",
     "test:cov": "npm run migrate-test && dotenv -e .env.test -- jest --coverage",
     "test:e2e": "jest --config ./test/jest-e2e.json",
+    "migrate": "docker exec v3-user sh -c 'npx prisma migrate dev'",
     "migrate-test": "dotenv -e .env.test -- npx prisma migrate dev --name postgres-init"
   },
   "dependencies": {