fix: improve readme

README.md

@@ -1,21 +1,31 @@
-# Graasp Phoenix
+# Graasp Admin
 
-This is the codebase for the Graasp platform written in
-[Elixir](https://elixir-lang.org/) using
-[the Phoenix web framework](https://phoenixframework.org)
+This is the codebase for the Graasp admin platform written in [Elixir](https://elixir-lang.org/) using [the Phoenix web framework](https://phoenixframework.org).
 
-This project was generated with phoenix version 1.8.0
+The admin platform enables administrators to:
+
+- manage publications
+- send messages to target audiences
+- manage interactive applications
+- perform operational tasks (re-indexation, ...)
+- explore analytics data
 
 ## Required tools
 
-This project uses [mise](https://mise.jdx.dev/).
+This project uses [mise](https://mise.jdx.dev/) for tasks and tool versions.
+Install mise from [the instructions](https://mise.jdx.dev/getting-started.html)
 
 Install all dependencies with (installs `elixir` and `erlang`):
 
 ```sh
 mise i
 ```
 
+As of writing this, the following versions are used:
+
+- elixir: 1.19.4
+- erlang: 28 (OTP 28)
+
 <details>
     <summary>Installing Elixir with brew (not recommended)</summary>
 
@@ -43,30 +53,43 @@ brew install elixir-ls
 
 ### PostgreSQL
 
-You will need a running PostgreSQL server.
+The admin platform uses the same database as the core platform.
+
+We recommend that you use the database provided by the devcontainer for the graasp/core project when running the admin.
+
+For tests or if you only need to access admin's related data, you will be fine using a local postgres instance for example via a docker container, or with an app such as [Postgres.app](https://postgresapp.com/) on MacOS.
+
+#### Devcontainer database
 
-This project is made to work with the postgresql server running in the devcontainer for the graasp/core project.
+You want to use all features of graasp and have an install of the core project running in the devcontainer.
+In this case, you should find a user `graasper` owning the `graasp` database accessible on `localhost:5432` from the host machine.
+Ensure this postgres is running when running the admin.
 
-In case you do not want to use the devcontainer, you can use the following command to start a postgresql server:
+You should ensure that the migrations from the core project are applied. After that run the admin-specific migrations with: `mix ecto.migrate`.
+
+#### Local database docker
+
+In case you want to run the admin standalone, you can use the following command to start a postgresql server in a docker container.
 
 ```sh
 docker run -d -p 5432:5432 \
-              -e POSTGRES_USER=postgres \
-              -e POSTGRES_DB=postgres \
-              -e POSTGRES_PASSWORD="postgres" \
+              -e POSTGRES_USER=graasper \
+              -e POSTGRES_DB=graasp \
+              -e POSTGRES_PASSWORD="graasper" \
               --name postgres postgres:17.5-alpine
 ```
 
-With a graphical client like [Postgres.app](https://postgresapp.com/) on MacOS.
+#### Local database (gui client)
+
+You can also use a graphical client like [Postgres.app](https://postgresapp.com/) on MacOS.
 
 ## Getting Started
 
 0. Ensure you have Elixir installed (`elixir -v` should show you the version)
-1. Install project dependencies with: `mix setup`
-2. Start you Phoenix server:
-   - Run `mix setup` to install and setup dependencies
-   - Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
-3. Create a `.env.sh` file with the following content. Use the values you get from configuring garage in the core project:
+1. Install project dependencies with: `mix deps.get`
+2. Compile the project with: `mix compile`
+3. Run the migrations with: `mix ecto.migrate`
+4. Create a `.env.sh` file with the following content. Use the values you get from configuring garage in the core project:
    ```sh
    # .env.sh
    export AWS_ACCESS_KEY_ID=GK3b...
@@ -77,8 +100,16 @@ With a graphical client like [Postgres.app](https://postgresapp.com/) on MacOS.
    ```sh
    source .env.sh
    ```
+5. Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server`
    Now you can visit [`localhost:4000`](http://localhost:4000) from your browser.
 
+## Testing
+
+For tests you should have a database available on `localhost:5433` with user `postgres` and password `postgres`.
+To run the tests: `mix test`
+After some failed tests re-run only failed tests with: `mix test --failed`
+To debug failed tests: `iex -S mix test --failed --breakpoints --trace`
+
 ## Deployment
 
 The application is deployed using ECS. The deployment process is handled by the graasp/infrastrucutre repository.