ScalableTeaching is a complete software suite that enables easy assignment and task handling for the development of software.

ScalableTeaching currently relies on a GitLab + GitLab CI environment to serve as the backbone.

Installation instructions

Requirements

• PHP 8.1 installed on your machine
• Comoposer installed.
• A MySQL instance
• Node ~18
• Yarn (install with Node)

The solution is built on top of the Laravel web framework (v9), with Vue 2 powering some frontend components.

1. Installing dependencies

Run composer install to install Laravel and the project's dependencies (Note: If you are on windows you will need to add --ignore-platform-req=ext-pcntl --ignore-platform-req=ext-posix since these packages are not supported on windows and laravel/horizon will run without them)

Run yarn to install the node dependencies for the frontend.

2. Configure environment variables

Copy the .env.example to a new .env file, and edit the following variables:

1. Setup the authentication. The authentication service uses GitLab's OAuth - configure the values below. If you are uncertain, these can be retrieved by inquirying the IT department. (Note: if you are running Scalable teaching locally, only GITLAB_URL (e.g. https://gitlab.sdu.dk), GITLAB_GROUP (e.g. the ID of the group Scalable should put repo's in) and GITLAB_ACCESS_TOKEN are needed.)
   1. GITLAB_CLIENT_ID
   2. GITLAB_CLIENT_SECRET
   3. GITLAB_REDIRECT_URL should be set to the host and port of your application and append /login/callback to it.
   4. GITLAB_GROUP Should be set to the id of the group id that all repositories and tasks should be created within.
   5. GITLAB_URL should refer to the url of the gitlab instance.
   6. GITLAB_ACCESS_TOKEN of the user ScalableTeaching should act as within GitLab.
   7. GITLAB_WEBHOOK_URL the link to the WebHook for the GitLab projects
2. Configure the database such that the application can establish a connection to your database
   1. DB_HOST
   2. DB_USERNAME
   3. DB_PASSWORD
3. Configure the SCALABLE_SECRET. This secret is used to ensure that student's don't tamper with the runner settings within their repo.
4. When running locally you may consider switching the LOG_CHANNEL to single instead of stack, this will stop the system from attempting to log to Teams

3. Migrate the database

Use the php artisan migrate command to migrate the database.

Additionally, if you want to populate it with dummy data, add --seed to the command, and if you want to migrate it from scratch again then run migrate:fresh instead.

4. Setting up local issuer certificate

You may get this error when attempting to create tasks: cURL error 60: SSL certificate problem: unable to get local issuer certificate If you do, follow these steps

1. Download this file: http://curl.haxx.se/ca/cacert.pem

2. Place this file in the C:\path\to\php folder

3. Open php.iniand find this line: ;curl.cainfo

4. Change it to: curl.cainfo = "C:\path\to\php\cacert.pem"

5. Make sure you remove the semicolon at the beginning of the line.

6. Save changes to php.ini, rerun php artisan serve and it should work

Development environment and CI

To enhance the developer workflow, this repository includes various tools to ensure a high quality of code. Specifically:

• php-cs-fixer that ensures a consistent code style. Install php-cs-fixer globally by running composer global require friendsofphp/php-cs-fixer, after which you can run php-cs-fixer fix within the root of this project to fix issues.
• larastan that runs a suite of static analyses. You may check your code for pitfalls using the php vendor/bin/phpstan

A large portion of the code base is also covered by both unit and feature tests, these can be inspected within the /tests directory. The tests are written using the PEST PHP testing framework.

You may trigger the tests by using the command php artisan test

You can also generate coverage by running php artisan test --coverage-html html-coverage

php-cs-fixer, larastan and tests are validated whenever you submit changes to the repo.

Gitlab Backbone

As mentioned in the beginning ScalableTeaching is built on top of GitLab and GitLab CI.

This application communicates with GitLab via their GraphQL API.
We generate schema query objects with the package php-graphql-oqm, and any generated files can be found in the /GraphQL folder.

Last schema generation was: February 19th 2024, and the gitlab.sdu.dk was running on version 16.9.

Diagrams

The diagrams in the documentation are generated using Mermaid.

You can find the diagrams in the /docs/diagrams folder.

For it to render properly when previewing, you can download the markdown extension any IDE you're using.

Running the application

Frontend

Use yarn watch to create a development build of the frontend. This command will keep watching for file changes and automatically recreate the underlying files whenever you make changes.

Laravel

Run php artisan serve to start the laravel application.

Database

Start the database.

This can be done by running docker compose up, which runs a development database and a in-memory MySQL test database, to avoid having to re-seed everytime the test are ran.
Once you're done, you can shut them down by running docker compose down

Bonus

For testing Gitlab webhook changes, you can use the free tier of Ngrok to expose your local environment to the outside world. On your ngrok account, you will find a static domain, you can use this to ensure it's the same URL every time you spin it up.

Note: I would not recommend developing against this tunnel connection, but purely use it for testing gitlab webhook events.

After installed, you can run ngrok http 8000 --domain <your static domain> in the root of the project, which will spin up a tunnel connection for the static url.
You can then set this static url in your .env file, the key is GITLAB_WEBHOOK_URL.

Note: If you own your own domain, I recommend using cloudflare tunnels as they are much more reliably. Can also be used without a domain, but requires switching the webhook url in GitLab every time you spin up the tunnel.

Production server

Server location

The server which runs ScalableTeaching is located on the SDU network, and it is therefore required for you to connect with the SDU VPN (Cisco). It's also REQUIRED to login to the VPN with your employee account so the account that ends in @mmmi.sdu.dk, this ensures you get routed differently on the SDU server.

Then you can SSH into the server with the account created like so: <ACCOUNT_NAME>@scalable.srv.sdu.dk and the password is your account password.

Note: If you get "Corrupted MAC on input." when trying to access the server you may have to add ssh -m hmac-sha2-512 <ACCOUNT_NAME>@scalable.srv.sdu.dk instead.

Deployment

Once logged in you can navigate to the /var/www/sites/main directory, and do a deploy with the latest changes by running the deploy.sh script.

DISCLAIMER: The script needs to be run as sudo to pull the deploy key and ssh config from the root folder

In the case that changes are made to the deploy.sh script, it needs to be run twice

Backup

Login to the server and run the following command to back up the app files. This will copy the files to your home directory, remove the storage, vendor and node_modules directories, and then compress the files into a tarball.

cp -r /var/www/sites/main/ ~/backup-app && rm -rf ~/backup-app/storage && rm -rf ~/backup-app/vendor && rm -rf ~/backup-app/node_modules && tar -zcvf ~/backup-app.tar.gz ~/backup-app

Next up backup the current database with mysqldump. This will create a dump of the database in a sql file, that can be replayed with

mysqldump -u <USERNAME> -p <DATABASE_NAME> --result-file=~/scalable-db-backup.sql --no-tablespaces 

The backed up files can be copied to your local machine through the use of SCP.

Restoring a backup

To restore the database backup, you can run the following command. This will create a new database, and then replay the sql file into it.

mysql -u <USERNAME> -p && create database <DATABASE_NAME>; && use <DATABASE_NAME>; && source <PATH_TO_SQL_BACKUP_FILE>; 

TBD: Restoring the app files.

FAQ

Fatal error: Allowed memory size of 134217728 bytes exhausted (tried to allocate 36864 bytes)

This means your PHP is configured with a memory limit that is too low to run the tests.

Update it by going to your php.ini file, and then searching for the field memory_limit and upping it. (Recommendation is to set it to 1G)

Command not found: php-cs-fixer (Mac/Linux)

Ensure you have updated your . profile, for your terminal.

Example: export PATH=<laravel vendor bin location>:$PATH, for me it was under ~/.composer/vendor/bin.