Skip to content
Snippets Groups Projects
Commit c28aa16a authored by Ruben Backx's avatar Ruben Backx :coffee:
Browse files

Update readme and contributing files

parent f6209a2c
No related branches found
No related tags found
2 merge requests!827New release: 3.4.0,!817Update readme and contributing files
Show whitespace changes
Inline Side-by-side
CONTRIBUTING.md
+ 88
− 67
View file @ c28aa16a
# Contributing to the queue (Queue) #
This guide has the following goals
1. Get a fork of the Queue repository setup. ([Getting access](#getting-access))
2. Get the project running on your machine. ([Project Setup](#project-setup))
3. Introduce the technologies used in Queue. ([Queue in context](#queue-in-context))
4. Give you some directions to navigate the codebase. ([Navigating the code base](#navigating-the-code-base))
5. Cover the process of submitting your changes! ([Submitting your changes](#submitting-your-changes))
1. [Get a fork of the Queue repository.](#getting-access)
2. [Get the project running on your machine.](#project-setup)
3. [Introduce the technologies used in Queue.](#queue-in-context)
4. [Give you some directions to navigate the codebase.](#navigating-the-code-base)
5. [Cover the process of submitting your changes.](#submitting-your-changes)
## Getting access ##
You can fork the repository [on gitlab.com](https://gitlab.com/eip-ewi/queue).
You can fork the repository [on gitlab.com](https://gitlab.com/eip-ewi/queue)
Everybody should be able to do this provided they have a gitlab.com account.
If you are a TU Delft student or employee, please use a gitlab.com account created with your TU Delft email address.
This repository is bidirectionally mirrored,
so any merged contributions will be automatically pushed to this repository.
You can also can request a fork for [on gitlab.ewi.tudelft.nl](https://gitlab.ewi.tudelft.nl/eip/labrador/queue) by emailing [support-eip-ewi@tudelft.nl](mailto:support-eip-ewi@tudelft.nl).
After you created a fork, you can continue to the next steps.
......@@ -21,18 +22,84 @@ After you created a fork, you can continue to the next steps.
In order to have the project setup properly for development a few steps need to be taken.
These steps assume you have already cloned the project (`git clone git@gitlab.ewi.tudelft.nl:eip/labrador/queue.git`)
1. First, the config file should be moved from the template into the actual properties file by executing
`cp src/main/resources/application.yaml.template src/main/resources/application.yaml`
1. Install OpenJDK 21 or later.
1. Install sass from npm (`npm install sass -g`) or install sassc (`sudo apt install sassc`).
1. The template config file at `src/main/resources/application.template.yml` should be copied to `src/main/resources/application.yaml`.
You can do this by hand or by executing `cp src/main/resources/application.template.yml src/main/resources/application.yaml`
from the root directory of the project.
2. Install [IntelliJ IDEA Professional](https://www.jetbrains.com/idea/) ([free for students](https://www.jetbrains.com/student/))
3. [Import project from Gradle model](https://www.jetbrains.com/idea/help/importing-project-from-gradle-model.html)
4. For IntelliJ to run the project make sure you are running jdk 8.
5. Start the project by right-clicking `QueueApplication` and clicking 'Run'
6. Visit http://localhost:8081/courses, please note that the regular login button currently doesn't work in the development setup,
however visiting any other url (like /courses) in the queue will prompt you with a login screen.
Various test users include: `Email: assistant1@tudelft.nl Username: assistant1` or `Email: student1@tudelft.nl Username: student1` and of course `Email: admin1@tudelft.nl User: admin1`. A password is **not** needed to login for the users mentioned above.
1. Edit the necessary properties in the `application.yaml` file:
- Turn off OpenTelemetry with `otel.sdk.disabled: true`.
1. In a separate directory clone LabraCore (`git clone git@gitlab.ewi.tudelft.nl:eip/labrador/labracore.git`).
1. Repeat steps 1 and 2 for the LabraCore repository.
1. Install [IntelliJ IDEA Professional](https://www.jetbrains.com/idea/) ([free for students](https://www.jetbrains.com/student/))
1. [Import project from Gradle model](https://www.jetbrains.com/idea/help/importing-project-from-gradle-model.html)
1. Open the Queue project in IntelliJ.
1. Either:
- Start LabraCore by opening the project in IntelliJ, right-clicking `LabraCoreApplication` and clicking 'Run'.
- Start LabraCore by running `gradle assemble` and then `java -jar $LABRACORE/build/libs/labracore*.jar` in the LabraCore directory.
1. Start the project by right-clicking `QueueApplication` and clicking 'Run'
1. Visit http://localhost:8081.
Various test users include `cseteacher1` ... `cseteacher4`, `csestudent1` ... `csestudent8`, and `admin1`.
For any test user, the password is the same as the username.
A list of all users and other things set up in the development environment can be found in the [DevDataBaseLoader](https://gitlab.ewi.tudelft.nl/eip/labrador/labracore/-/blob/development/src/main/java/nl/tudelft/labracore/DevDatabaseLoader.java) class in the LabraCORE repository.
## Submitting your changes ##
The merge request template should already contain a checklist for you to go through, but we also list some of the steps here.
1. Make sure your code is formatted properly.
You can check this by using two different gradle tasks: `./gradlew spotlessCheck` and `./gradlew spotlessApply`
1. Ensure your commit message has a title explaining what the change is and a body explaining why you made this change.
1. Ensure your commit message ends with a `Signed-off-by`.
This can be automated by running a script once following [the steps below](#signing-your-work)
1. Ensure your code is tested.
1. Ensure CI passes.
1. Ensure the significant changes you made are listed in the changelog.
1. Log changes in the [Unreleased] tag
1. Put changes under appropriate tag, choose from list at the top
### Signing your work ###
**If you are brand new to Queue**, you'll need to run a script that adds `Signed-off-by` to each of your commits. This trailer means that the author agrees with the [Developer Certificate of Origin (DCO)](docs/developer-certificate-of-origin) and with licensing the work under the [AGPL v3](LICENSE). This is important for our team and our users, legally. The [setup_commit_msg_hook.sh](contributing/hooks/setup_commit_msg_hook.sh) script will setup a Git commit-msg hook that will add this trailer to all the commit messages you write in that repository. This is not as complicated as it sounds: it is similar to typing `git commit --signoff` every time you commit. Just download the script and run it once from the root folder of whatever Git repository you are in (for example, queue or labrador).
The Developer Certificate of Origin (DCO) is a document that certifies you own and/or have the right to contribute the work and license it appropriately. The DCO is used instead of a [CLA (Contributor License Agreement)](https://en.wikipedia.org/wiki/Contributor_License_Agreement). With the DCO, you retain copyright of your own work. The DCO originated in the Linux community, and is used by other projects like Git and Docker. To learn more about the DCO see this [posts on elinux.org](http://elinux.org/Developer_Certificate_Of_Origin) or how [docker uses the DCO](https://blog.docker.com/2014/01/docker-code-contributions-require-developer-certificate-of-origin/).
#### Commit messages ####
Your commit messages should end with the following trailer:
```
Signed-off-by: User Name <email@address>
```
where "User Name" is the author's real (legal) name and email@address is one of the author's valid email addresses.
As explained in more details above, this is easy to fix by running once the [setup_commit_msg_hook.sh](contributing/hooks/setup_commit_msg_hook.sh) script in the root folder of the repository. If you are familiar with terminals, you probably know how to do this. If you use a special application for making commits, such as Sourcetree or GitKraken, or if you are working with git bash, then please refer to the instructions below.
#### Windows / Git Bash ####
If you are using Git Bash / Git Shell / Git Gui for windows then you can do the following to setup the commit hook.
1. Open the parent directory of the repository in Explorer, and use right click on the queue directory, git bash here.
![Git Bash Example](docs/GitBashExample.png)
1. In the window that opens, type
`sh contributing/hooks/setup_commit_msg_hook.sh`
and press enter
1. You should see a message stating that installation is successful
#### Mac / Git ####
If you are using Git on Mac then you can do the following to setup the commit hook.
1. Open a terminal
1. Navigate to the queue folder with the cd command
1. Type
`sh contributing/hooks/setup_commit_msg_hook.sh`
and press enter
1. You should see a message stating that installation is successful
## Disclaimer ##
All information above is checked and up-to-date as of 1st October 2024.
You can find some more information below, but it might not be as up-to-date as possible.
We are in the process of moving this information to a central Labrador documentation repository.
## Queue in context ##
In this section we give a joint context / development view of Queue.
That is, we place Queue, the databases Queue owns, and the browser it will interact with each in its own environment.
......@@ -99,12 +166,6 @@ Hence we cover the first three together and cover Liquibase individually.
That is, Spring uses Hibernate to execute the queries.
All these interfaces are found in the repository package of Queue.
3. [Query Dsl](http://www.querydsl.com/) is a domain specific language for writing SQL queries in java code rather than in strings.
In order to do this, it generates classes at compile time capturing information about the schema in the database so that the types in the queries match the types of our schema.
Like Spring repositories Query Dsl also does not talk to the database directly but does so through hibernate.
![Persistence Stack](docs/PersistenceStack.png)
Finally [Liquibase](https://www.liquibase.org/) is a tool for database migrations.
So the Queue, once it is up and running, actually has nothing to do with it.
However, it bridges changes you make to the schema in terms of the Hibernate model classes to the schema actually running in production.
......@@ -160,42 +221,11 @@ With that in place you can update the logic in the controller to hopefully finis
#### A small side note on configuration ####
A lot of changes to the queue also require changes to the way spring is configured in the project.
The `applications.properties` file that we had you copy over in the setup section is the most important part of spring configuration.
The `applications.yaml` file that we had you copy over in the setup section is the most important part of spring configuration.
We do not cover the meaning of the properties here, but note it as an important file in the repository.
Besides the configuration in this file, the rest of the configuration is done in code. See `QueueApplication` for this.
## Submitting your changes ##
After building your awesome new feature time has come to submit a merge request.
The merge request template should already contain a check list for you to go through but we also list some of the steps here.
1. Make sure your code is formatted properly.
You can check this by using two different gradle tasks: `./gradlew spotlessCheck` and `./gradlew spotlessApply`
1. Ensure your commit message has a title explaining what the change is and a body explaining why you made this change.
1. Ensure your commit message ends with a `Signed-off-by`.
This can be automated by running a script once following [the steps below](#signing-your-work)
1. Ensure your code is tested.
1. Ensure CI passes.
1. Ensure the significant changes you made are listed in the changelog.
1. Log changes in the [Unreleased] tag
1. Put changes under appropriate tag, choose from list at the top
### Signing your work ###
**If you are brand new to Queue**, you'll need to run a script that adds `Signed-off-by` to each of your commits. This trailer means that the author agrees with the [Developer Certificate of Origin (DCO)](docs/developer-certificate-of-origin) and with licensing the work under the [AGPL v3](LICENSE). This is important for our team and our users, legally. The [setup_commit_msg_hook.sh](contributing/hooks/setup_commit_msg_hook.sh) script will setup a Git commit-msg hook that will add this trailer to all the commit messages you write in that repository. This is not as complicated as it sounds: it is similar to typing `git commit --signoff` every time you commit. Just download the script and run it once from the root folder of whatever Git repository you are in (for example, queue or labrador).
The Developer Certificate of Origin (DCO) is a document that certifies you own and/or have the right to contribute the work and license it appropriately. The DCO is used instead of a [CLA (Contributor License Agreement)](https://en.wikipedia.org/wiki/Contributor_License_Agreement). With the DCO, you retain copyright of your own work. The DCO originated in the Linux community, and is used by other projects like Git and Docker. To learn more about the DCO see this [posts on elinux.org](http://elinux.org/Developer_Certificate_Of_Origin) or how [docker uses the DCO](https://blog.docker.com/2014/01/docker-code-contributions-require-developer-certificate-of-origin/).
#### Commit messages ####
Your commit messages should end with the following trailer:
```
Signed-off-by: User Name <email@address>
```
where "User Name" is the author's real (legal) name and email@address is one of the author's valid email addresses.
As explained in more details above, this is easy to fix by running once the [setup_commit_msg_hook.sh](contributing/hooks/setup_commit_msg_hook.sh) script in the root folder of the repository. If you are familiar with terminals, you probably know how to do this. If you use a special application for making commits, such as Sourcetree or GitKraken, or if you are working with git bash, then please refer to the instructions below.
#### Windows / Git Bash ####
If you are using Git Bash / Git Shell / Git Gui for windows then you can do the following to setup the commit hook.
......@@ -217,6 +247,8 @@ If you are using Git on Mac then you can do the following to setup the commit ho
1. You should see a message stating that installation is successful
#### Sourcetree ####
**!!! SourceTree is not recommended. Its authentication procedure is likely to get you in the GitLab firewall. !!!**
If you are using sourcetree, you need to ensure that sourcetree uses the system git.
1. Install Git Bash for [Windows](https://github.com/git-for-windows/git/releases/latest) / Install git for [Mac](https://git-scm.com/download/mac)
......@@ -237,18 +269,7 @@ If you are using GitKraken, you can execute the following instructions. The same
1. Your commits made in GitKraken will automatically be signed off
## Production
Queue runs on queue.tudelft.nl (alias for queue.ewi.tudelft.nl).
This server is managed by the developers of the CSE Teaching Team (eip-ewi@tudelft.nl).
### Error logging
All exceptions in the production environment are logged to our [self-hosted Sentry instance](https://sentry.ewi.tudelft.nl).
Access to Sentry can be requested via the server maintainers.
In order to send the logs to the Sentry instance you need to create a properties file called `sentry.properties` next to the `application.yaml` file.
This file should contain the following (exact URL can be found in the Sentry project):
Queue runs on queue.tudelft.nl.
This server is managed by the developers of the CSE Teaching Team (support-eip-ewi@tudelft.nl).
```
dsn=https://[identifier]@sentry.ewi.tudelft.nl
```
For local development your local logs should be sufficient to debug errors.
When the above key is not set in the `sentry.properties` file then the Sentry Exception Handler will be ignored.
README.md
+ 8
− 57
View file @ c28aa16a
......@@ -2,44 +2,9 @@
A queueing system to be used at labs at EWI (tudelft.nl).
## Contributing
## Contributing and Setup
Please read our [contribution guide](CONTRIBUTING.md).
## Requirements
- Java 17+
## Project setup
In order to have the project setup properly for development a few steps need to be taken.
1. First the config file should be moved from the template into the actual properties file
by executing `cp src/main/resources/application.yaml.template src/main/resources/application.yaml`
from the root directory of the project.
1. For tests to work, `application-test.properties` file (which the GitLab pipeline copies from application-h2.properties) should be created in `src/test/resources`.
1. Make sure to also have an `application.properties` file in `src/test/resources` with the content `spring.profiles.active=testing`.
1. The `test-connection` setting in `application.yaml` is set to `false` by default for the development environment, but it is advised to set this to `true` for production deployment.
1. Follow these [instructions](https://gitlab.ewi.tudelft.nl/eip/labrador/queue/-/blob/master/CONTRIBUTING.md#submitting-your-changes)
to submit your work
### Run website from IDE
1. Install [IntelliJ IDEA Professional](https://www.jetbrains.com/idea/) ([free for students](https://www.jetbrains.com/student/))
1. [Import project from Gradle model](https://www.jetbrains.com/idea/help/importing-project-from-gradle-model.html)
1. For IntelliJ to run the project make sure are running jdk 8.
1. Start the project by right-clicking `QueueApplication` and clicking 'Run'
1. Visit http://localhost:8081/
1. Finally visit http://localhost:8081/login to login.
Various test users credentials can be found in the `DataBaseLoader` class or in [Test Data](https://gitlab.ewi.tudelft.nl/groups/eip/labrador/-/wikis/test-data).
### Run website from CLI
1. `gradle build`
1. `sudo java -jar build/libs/queue-0.0.1-SNAPSHOT.jar`
1. Visit http://localhost:8081/
1. Finally visit http://localhost:8081/login to login.
Various test users credentials can be found in the `DataBaseLoader` class.
Please read our [contribution guide](CONTRIBUTING.md) for information about project setup and contributing guidelines.
## Deployment
......@@ -52,28 +17,14 @@ The `deploy/` directory contains an Ansible playbook that can be used to provisi
To run the playbook, first replace the hostname and your SSH key in `deploy/hosts`, then run `./deploy/run.sh`.
Note that the current `application.yaml` contains `spring.jpa.hibernate.ddl-auto=create` which will drop and create the database upon reboot!
## Configuration
See `application.yaml`. Chrome does not yet fully support the Web Push API and uses GCM to handle sending and delivery of push messages. To use the GCM API you need a GCM API key. [This](https://developers.google.com/web/updates/2015/03/push-notifications-on-the-open-web#make-a-project-on-the-google-developer-console) page explains how to obtain one.
You can place an `application.yaml` on the classpath which overrides the `application.yaml` in the jar itself.
> Nowadays, Chrome supports VAPID (Voluntary Application Identification) for Web Push API and it is no longer necessary to obtain an API key. The Web Push library should be updated to the latest version that I'm maintaining at https://github.com/MartijnDwars/web-push. For VAPID, we need to generate yet another keypair..
### Environments
The system distinguishes two profiles: `development` and `production`. Use the `application.yaml` file to set the active profile. The active profile has the following impact:
- The `DatabaseLoader`, which loads the database with dummy data, is only run if the `development` profile is active.
- The `error.html` page only shows stack traces if the `development` profile is active.
## Domain
- A `Request` is always initiated by a student. At some point, it will be handled by an assistant.
## Database migrations
The queue uses [liquibase](https://www.liquibase.org/index.html) for database migrations.
The changelog can be found in src/main/resources/changeLog.yaml, the corresponding documentation can be found
[here](https://www.liquibase.org/documentation/index.html). To run and test a liquibase migration in the development
......@@ -84,18 +35,18 @@ environment you need to change a few settings in the application properties file
## Roles
A user has a single _default_ role and a single _contextual_ role for every course that he participates in. This distinction is necessary because, for example, a teacher may not be a teacher in every course. The default roles are `STUDENT`, `TEACHER`, and `ADMIN`. The contextual roles are `STUDENT`, `ASSISTANT`, `MANAGER` and `TEACHER`.
A user has a single _default_ role and a single _contextual_ role for every course that he participates in. This distinction is necessary because, for example, a teacher may not be a teacher in every course. The default roles are `STUDENT`, `TEACHER`, and `ADMIN`. The contextual roles are `STUDENT`, `TA`, `HEAD_TA` and `TEACHER`.
A user can have at most one contextual role within a course. An `ASSISTANT` is able to handle requests. A `MANAGER` can do everything an `ASSISTANT` can, but may also manage assignments and labs. A `TEACHER` can do everything an `ASSISTANT` can, but can also remove the course and change the course's name.
A user can have at most one contextual role within a course. A `TA` is able to handle requests. A `HEAD_TA` can do everything an `TA` can, but may also manage assignments and labs. A `TEACHER` can do everything an `TA` can, but can also remove the course and change the course's name.
The default roles form a hierarchy. That is, an `ADMIN` can do everything a `TEACHER` can, and a `TEACHER` can do everything a `STUDENT` can. A user with default role `STUDENT` has no special permissions. A user with default role `TEACHER` is allowed to create courses. A user with default role `ADMIN` is allowed to change a user's default role.
When an `ADMIN` operates within a course, he acts as a `TEACHER`. It is adviced to use the admin account solely for administrative usages (such as setting up a course).
When an `ADMIN` operates within a course, he acts as a `TEACHER`. It is advised to use the admin account solely for administrative usages (such as setting up a course).
## Security
- Passwords are encrypted with bcrypt, which protects against rainbow table attacks and remains resistant to brute-force attacks when computing power increases.
- All forms are accomodated with an `_csrf` field to protect against CSRF attacks.
- All forms are accommodated with an `_csrf` field to protect against CSRF attacks.
- We only support HTTPS connections, because supporting both HTTP and HTTPS is too much of an effort (and there is little to no reason to support HTTP). Spring Security will make sure the HTTP Strict Transport Security (HSTS) headers are set. In development mode, make sure you accept the certificate. On OS X, adding `keystore.p12` to Keychain will get you a green padlock in Chrome. This is required for push notifications, among others.
- All `User`s have a `Role`, which is one of: STUDENT, ASSISTANT, TEACHER, ADMIN.
......@@ -103,7 +54,7 @@ When an `ADMIN` operates within a course, he acts as a `TEACHER`. It is adviced
SAML provides Single Sign On (SSO). The Queue system acts as a Service Provider (SP). It requests and obtains an identity assertion from the identity provider (TUDelft gatekeeper). By default, only identity assertions with a max age of 7200 seconds are trusted. This can be changed by updating `maxAuthenticationAge` on the `WebSSOProfileImpl` object. Alternatively, you can force the IDP to re-authenticate the user by setting `forceAuthN` to `true` on the `WebSSOProfileOptions` object.
In development you may not want to go through the SAML process. The traditional login page is still available at `/login`. This requires that a `User` with a username and password exists.
In development you may not want to go through the SAML process. An in-memory option is available for development and is turned on by default.
### Crypto
......
docs/PersistenceStack.png deleted 100644 → 0
NaN GiB (NaN%)
View file @ f6209a2c
File suppressed by a .gitattributes entry, the file's encoding is unsupported, or the file size exceeds the limit.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please to comment