Graasp Admin

This is the codebase for the Graasp admin platform written in Elixir using the Phoenix web framework.

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 for tasks and tool versions. Install mise from the instructions

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)

Elixir

You will need Elixir and OTP installed. On MacOS simply run: brew install elixir For installation instructions refer to the elixir installation guide

You can test you installation by running elixir -v. It should output something like:

Erlang/OTP 28 [erts-16.0.2] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit] [dtrace]

Elixir 1.18.4 (compiled with Erlang/OTP 27)

Also install elixir-ls (one of) the Elixir Language server. With brew:

brew install elixir-ls

PostgreSQL

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 on MacOS.

Devcontainer database

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 want to run the admin standalone, you can use the following command to start a postgresql server in a docker container.

docker run -d -p 5432:5432 \
              -e POSTGRES_USER=graasper \
              -e POSTGRES_DB=graasp \
              -e POSTGRES_PASSWORD="graasper" \
              --name postgres postgres:17.5-alpine

Local database (gui client)

You can also use a graphical client like Postgres.app on MacOS.

Getting Started

0. Ensure you have Elixir installed (elixir -v should show you the version)
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:

   # .env.sh
   export AWS_ACCESS_KEY_ID=GK3b...
   export AWS_SECRET_ACCESS_KEY=a03cf77e181...
   export AWS_DEFAULT_REGION=garage

   You will need to source this file in your shell before starting the server:

   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 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. It is in charge of registering the service and starting the tasks with the proper environment variables. This repo simply builds the docker images and pushes them to the private ECR registry.

Please checkout the setup docs for more information on how to bootstrap a server to deploy your app in production.

Translations

This project uses gettext for translations. Gettext works by extracting strings from the code and storing them in a .pot file. This file is the template and should not be modified directly. Active translations are stored in .po files. These are the files that translators need to work on.

Gettext allows to group translations by domain. This is useful to separate translations for different parts of the application. The default domain is used when nothing is specified.

Gettext allows to define multiple backends. This allows to separate translations for different concerns. In our application, we have the application UI and the email templates. Since the user's interface can be in a different language than the email template, we use two backends: AdminWeb.Gettext for the UI and AdminWeb.EmailTemplates.Gettext for the email templates. This allows us to set a locale for each backend independently.

The UI translations are stored in priv/gettext/*. The email template translations are stored in priv/gettext_email_templates/*.

The next sections describe how to work with translations. A commodity mix alias is provided to make it easier to update and merge translations: mix i18n.

Extracting strings from code

To extract translation strings from the code, run mix gettext.extract.

The message strings should be literal strings solvable at compile time.

Translating strings

Translated message strings are stored in .po files. The language specific translation files are stored in admin/priv/gettext/<lang>/LC_MESSAGES/<domain>.po. For example, the en (English) translations for the default domain are stored in admin/priv/gettext/en/LC_MESSAGES/default.po. To sync the translations, run mix gettext.merge priv/gettext and mix gettext.merge priv/gettext_email_templates.

Adding new languages

To support a new language, create a new folder in priv/gettext then run mix gettext.merge priv/gettext. Do the same for priv/gettext_email_templates.

Correctly extracting strings from MJML-enabled templates

Email templates under lib/admin_web/email_templates/templates_html are MJML-enabled. In order for gettext to correctly extract the translation strings at compile time we need to:

• include <% use Gettext, backend: AdminWeb.EmailTemplates.Gettext %> at the top of the template file.
• use the gettext macro with literal strings in the template body

This should allow to correctly extract the translation strings at compile time. It can be verified by adding a new string to a template and running mix gettext.extract then mix gettext.merge priv/gettext_email_templates.

Common commands

Checkout the memento for an overview of helpful commands for managing the project (deployment and development).

Troubleshooting and general help

Cleaning artifacts after making a release

If you made a release localy it is possible that you end-up with a lot of files in the priv/static/ folder.

Before committing, run: mix phx.digest.clean --all to clean them.