unillett/impact repository overview

Master:

Development:

⁠Introduction

multIMedia interface: Presentation – Analysis – CommenT

A Laravel 12 app with react components.

⁠Development with Docker

⁠Docker installation

A working Docker⁠ installation is mandatory.

⁠Environment files

Please make sure to copy & rename the db.env.example file to db.env.

cp docker/db.env.example docker/db.env

You can replace the values if needed, but the default ones should work for local development.

Please also make sure to copy & rename the docker-compose.override.yml.dev file to docker-compose.override.yml.

cp docker-compose.override.yml.dev docker-compose.override.yml

You can replace the values if needed, but the default ones should work for local development.

⁠Edit hosts file

Edit hosts file to point impact.lan to your docker host.

⁠Installation & configuration

Build & run all the containers for this project.

docker compose up (add -d if you want to run in the background and silence the logs)

⁠Populate the database

The first time you run the application you'll need to populate your database with initial data.

docker exec impact-app php artisan db:seed

If you want completely wipe your database and populate it with fresh data, you can use the following command.

docker exec impact-app php artisan migrate:fresh --seed

⁠Performance data

A separate seeder adds a course big enough to measure the performance of the finder: 1000 cards spread over 120 folders on three levels, 150 enrolled users the cards are assigned to, and 30 tags. It is not part of the seeders above, and adds a new course every time it is run without touching the existing data.

docker exec impact-app php artisan db:seed --class=PerformanceTableSeeder

The users of that course are perf<course_id>-user<n>@example.com / password, the first five being the managers. The volumes are constants at the top of database/seeders/PerformanceTableSeeder.php.

⁠Assets

Assets are compiled when the container is built, but if you want to recompile them, you can use the following command.

docker exec impact-app pnpm run dev

or if you want to watch for changes.

docker exec impact-app pnpm run watch

⁠Frontends

To access the main application please use the following link.

http://impact.lan:8787⁠

• [email protected]⁠ / password

⁠Telescope

To access the debug tool please use the following link.

http://impact.lan:8787/telescope⁠

⁠MailHog

To access mails please use the following link.

http://impact.lan:8025⁠

Or to get the messages in JSON format.

http://impact.lan:8025/api/v2/messages⁠

⁠Database

To access the database please use the following credentials.

• Host: 127.0.0.1:3303
• Username: user
• Password: password

⁠PHP code style

All PHP files will be inspected during CI for code style issues. If you want to make a dry run beforehand, use the following command.

docker exec impact-app ./vendor/bin/pint --test

And if you want to automatically fix the issues.

docker exec impact-app ./vendor/bin/pint

⁠Tests

⁠Unit/Feature tests

To run the full suite:

docker exec -it impact-app php artisan test

⁠Browser tests

You need to install Chrome Driver first:

docker exec -it impact-app php artisan dusk:chrome-driver

To run the full suite:

docker exec -it impact-app php artisan dusk --env=testing

To run a specific class:

docker exec -it impact-app php artisan dusk tests/Browser/MyTest.php --env=testing

To view the integration tests running in the browser, go to http://impact.lan:4444⁠, click on Sessions, you should see a line corresponding to the running tests and a camera icon next to it, click on it to open a VNC viewer ("secret" as password).

⁠Deployment with Docker

⁠Environment files

Copy and rename the following environment files.

cp docker/db.env.example docker/db.env
cp docker/shibboleth.env.example docker/shibboleth.env
cp site/.env.example site/.env

You should replace the values since the default ones are not ready for production.

To authenticate with Shibboleth, set SHIB_HOSTNAME and SHIB_CONTACT in docker/shibboleth.env, and set SHIBBOLETH_AUTH_ENABLED to true in site/.env. If SHIBBOLETH_AUTH_ENABLED is set to false, you will only be able to use the local authentication.

Please also make sure to copy & rename the docker-compose.override.yml.prod file to docker-compose.override.yml.

cp docker-compose.override.yml.prod docker-compose.override.yml

You can replace the values if needed, but the default ones should work for production.

⁠Shibboleth certificates

On first startup the proxy generates a service provider key & certificate and persists them in the shibboleth-certs volume. That certificate must be registered on the AAI Resource Registry⁠ before authentication works.

To reuse an already registered certificate instead, set SHIB_SP_KEY and SHIB_SP_CERT in docker/shibboleth.env.

⁠Installation & configuration

Build & run all the containers for this project.

docker compose up -d

⁠Reverse proxy

Use a reverse proxy configuration to map the url to port 8787, which is served by the Shibboleth proxy. SWITCHaai requires HTTPS, so the reverse proxy must terminate TLS.

⁠Docker images

GitHub Actions workflows generate Docker image tags based on these events:

• Push to development: {service}-dev-latest, {service}-stage-latest, {service}-stage-<sha>-<timestamp> (immutable)
• Push to master: {service}-latest
• Push a git tag: {service}-vX.Y.Z (immutable)

Weekly cron jobs:

• Create an updated staging image: {service}-stage-<sha>-<timestamp> (immutable)
• Create an updated production candidate: {service}-vX.Y.Z-<sha>-<timestamp> (immutable)

All the immutable tags are committed to the k8s⁠ repository.

⁠Error tracker

https://www.bugsnag.com⁠

⁠Helm

The Helm charts for this project are available at https://github.com/unil-lettres/k8s⁠, in the impact directory.