Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/se2p/scratchlog


https://github.com/se2p/scratchlog

Last synced: 5 days ago
JSON representation

Awesome Lists containing this project

README 

        
# ScratchLog



## Installation



### Requirements



- Apache Maven

- A MySQL database

- npm

- for data acquisition: instrumented Scratch GUI and Scratch VM



To access the database, you only need to change the connection details in the `application.properties` file.



### Run from within an IDE



Create a new database with a database user to grant the application access and specify the connection details in the

`application.properties` file. Add the necessary tables and constraints using the `schema.sql` file in the

`main/resources` folder.



Install npm in the `resources/static` folder via the following command:

```bash

npm install

```

The result page of this project uses Google's `Blockly` and `Scratch Blocks` to display the participant code. Since this

project is build with the Spring framework, you can run this project from within an IDE. You will still need to do the

necessary configurations described below.



#### Standard configuration



To get the project up and running, you need to adapt the `application.properties` file in the `resources` folder as

follows:

- Configure the database connection and mail sending to match your system.

- If you want to use the application without a mail server, set the *app.mail* boolean to false. With this setting,

  you will not be able to use the reset password functionality of this application. Please note that switching between

  mail server options, e.g. first using the application without a mail server and then using one, might cause the

  application to not work properly anymore.

- Change the *app.url* string to the application base URL, e.g. `scratch.fim.uni-passau.de`.

- Change the *app.gui* string to the URL under which the instrumented Scratch GUI is available.

- Set the *app.gui.base* string to the base URL of the Scratch GUI. This might be the same as the *app.gui* property.

  However, if you have deployed the GUI under a relative context path, e.g. `scratch.fim.uni-passau.de/gui`, *app.gui*

  would have to be set to the full path (`scratch.fim.uni-passau.de/gui`) while *app.gui.base* will only be

  `scratch.fim.uni-passau.de`.

- If you only want to use the `application.properties` file, you can comment out the *spring.profiles.active* line.

- Optional: Set the log level to *Warn* or *Error*.



Since the `application.properties` file contains some critical data (e.g. login information for the database) that might

easily be committed by accident, some sections have been commented out. You should put these in a file named

`application-local.properties` in the `resources` folder, uncomment them and adapt them there. This file has been added

to the `.gitignore` file and the *spring.profiles.active* configuration in the `application.properties` file has been

set accordingly for spring to automatically pick up the configurations.



#### Using Flyway



The application uses `Flyway` for database versioning. As `Flyway` will need to create and alter tables, it will require

more access privileges than the standard database user. Therefore, it is recommended to create a separate database user

used by `Flyway`. This user can be specified in the matching section in the `application.properties` file. If you wish

to use `Flyway`, make sure to at least copy or uncomment the `spring.flyway.create-schemas` line. If you do not wish to

use any database versioning, you can set the `spring.flyway.enabled` property to false and

`spring.datasource.initialization-mode=never`. The `schema.sql` file contains the latest database version and is updated

accordingly with every new migration. You can simply create the database tables using the schema. However, you will then

have to incorporate subsequent updates to the database manually.



#### Configuring multiple Scratch GUI instances



Since the URL to the instrumented Scratch-GUI instance is saved per experiment, it is possible to use different Scratch

GUIs for individual experiments. To take advantage of this feature, the *app.gui* property can contain a list of

comma-separated URLs **without whitespaces**. The provided URLs will be available as options in a dropdown-menu when

creating a new experiment. The *app.gui.base* property has to be configured accordingly to contain a comma-separated

string of all the unique base URLs of the different Scratch GUI instances (no need to specify the same base URL twice).



#### Deployment under a relative context path



If you plan to deploy the project under a relative context path, e.g.`scratch.fim.uni-passau.de/scratchlog` instead of

`scratch.fim.uni-passau.de`, you need to change the `server.servlet.context-path` in the `application.properties` file

accordingly, e.g. to `/scratchlog` while the *app.url* value is `scratch.fim.uni-passau.de`.



#### Configuring the instrumented Scratch instance



You also have to make some changes to the instrumented Scratch instance:

- Change the *baseUrl* in `logging.js` in the instrumented `scratch-vm` to ` + 

  /store`.

- Change the `window.location.href` in the *handleFinishExperiment()* method in `menu-bar.jsx` in the instrumented

  `scratch-gui` to ` + `.

- The instrumented `scratch-gui` and `scratch-vm` need to be linked via the `npm link` setting, as described

  [here](https://github.com/LLK/scratch-gui/wiki/Getting-Started).



On application startup, a first administrator is added automatically, if no other administrator could be found in the

database. The login credentials are specified in the `UserInitialization` class. You should change these credentials

immediately after you have logged in.



#### Configuring SSO Authentication



The application offers functionality to use single sign on through an identity service provider with SAML2. In order to

use this feature, you will have to do some additional configuration in the properties file(s):

- Add `saml2` to the *spring.profiles.active* property.

- Change the *app.saml2.base* string to the base URL of the IdP.

- Change the *saml.username* string to the username pattern with which the username can be extracted from the SAML2

authentication.

- Change the *saml.email* string to the email pattern with which the email can be extracted from the SAML2

authentication.

- Change the *saml.extraction.key* string if needed.

- Change the *saml.extraction.value* string if needed.

- Change the *saml.metadata* string to the path at which the IdP's metadata file is located.

- Change the *saml.idp* string to the name of the IdP.

- Change the *saml.entity* string to the address at which ScratchLog will be available.

- Change the *saml.certificate* and *saml.key* strings to the paths at which the server certificate and the key file are

available.



Please note that username or email changes from the IDP side are not propagated to the application. This means that if a

user has been authenticated via SSO once and the user has been added to the database, if the user changes their name and

authenticates via SSO again, a new user profile will be created.



## Build and Deployment



### Deployment

To deploy the project, just execute

```bash

mvn clean compile package

```

This will package the project in a jar ready for execution. In order for the project to work properly, however, it still

requires a running instance of the instrumented `Scratch GUI` linked to the instrumented `Scratch VM` that is accessible

over the `GUI_URL` constant.



### Starting the application



To run the jar, execute

```bash

java -jar scratchLog-0.0.1-SNAPSHOT.jar

```