From 3cc8dca015bf23bea7b948891e72e0625270b736 Mon Sep 17 00:00:00 2001 From: spaenleh Date: Tue, 16 Dec 2025 15:31:04 +0100 Subject: [PATCH 1/2] fix: improve readme --- README.md | 68 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index a522bbdca..bf8eb5289 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,19 @@ -# 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`): @@ -16,6 +21,11 @@ Install all dependencies with (installs `elixir` and `erlang`): mise i ``` +As of writing this, the following versions are used: + +- elixir: 1.19.4 +- erlang: 28 (OTP 28) +
Installing Elixir with brew (not recommended) @@ -43,30 +53,44 @@ 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 and in case you would only need access to things that the admin does (nothing related to graasp) you would 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 devcotnainer. +In this case, you should have a the 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 do not want to use the devcontainer, 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 +5. 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 +101,16 @@ With a graphical client like [Postgres.app](https://postgresapp.com/) on MacOS. ```sh source .env.sh ``` +6. 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. From fdfb405e366f34866a1b41da118fa5b25bbc9602 Mon Sep 17 00:00:00 2001 From: spaenleh Date: Thu, 18 Dec 2025 15:07:51 +0100 Subject: [PATCH 2/2] fix: make requested changes to improve clarity --- README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index bf8eb5289..75a4fcac0 100644 --- a/README.md +++ b/README.md @@ -57,19 +57,19 @@ 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 and in case you would only need access to things that the admin does (nothing related to graasp) you would 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. +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 -You want to use all features of graasp and have an install of the core project running in the devcotnainer. -In this case, you should have a the user `graasper` owning the `graasp` database accessible on `localhost:5432` from the host machine. +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. 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 do not want to use the devcontainer, you can use the following command to start a postgresql server in a docker container. +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 \ @@ -89,8 +89,7 @@ You can also use a graphical client like [Postgres.app](https://postgresapp.com/ 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 -5. Create a `.env.sh` file with the following content. Use the values you get from configuring garage in the core project: +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... @@ -101,7 +100,7 @@ You can also use a graphical client like [Postgres.app](https://postgresapp.com/ ```sh source .env.sh ``` -6. Start Phoenix endpoint with `mix phx.server` or inside IEx with `iex -S mix phx.server` +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