unillett/training repository overview

Master:

Development:

⁠Introduction

Development of technical skills in the Faculty of Arts.

A Laravel 13 app with a Filament⁠ administration panel.

⁠Development with Docker

⁠Docker installation

A working Docker⁠ installation is mandatory.

⁠Environment files

Please make sure to copy & rename the example.env file to .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 training.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 train-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 train-app php artisan migrate:fresh --seed

⁠Assets

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

docker exec train-app pnpm run dev

or if you want to watch for changes.

docker exec train-app pnpm run watch

⁠Frontends

To access the main application please use the following link.

http://training.lan:8686⁠

To access the administration please use the following link.

http://training.lan:8686/admin⁠

• [email protected]⁠ / password

⁠Telescope

To access the debug tool please use the following link.

http://training.lan:8686/telescope⁠

⁠MailHog

To access mails please use the following link.

http://training.lan:8025⁠

Or to get the messages in JSON format.

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

⁠Database

To access the database please use the following credentials.

• Server: 127.0.0.1:3309
• 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 train-app ./vendor/bin/pint --test

And if you want to automatically fix the issues.

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

⁠Tests

⁠Unit/Feature tests

To run the full suite:

docker exec -it train-app php artisan test

⁠Browser tests

To run the full suite:

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

To run a specific class:

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

To view the browser tests running in the browser, go to http://training.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 Filament 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 8686, 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: dev-latest, stage-latest, stage-<sha>-<timestamp> (immutable)
• Push to master: latest
• Push a git tag: vX.Y.Z (immutable)

Weekly cron jobs:

• Create an updated staging image: stage-<sha>-<timestamp> (immutable)
• Create an updated production candidate: 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 training directory.