Add more detailed instructions to README.md
This commit is contained in:
Tim Schubert
parent
01bfb44c73
commit
a4a85ce1b8
1 changed files with 99 additions and 37 deletions
136
README.md
136
README.md
|
|
@ -1,53 +1,115 @@
|
|||
# The abgabesystem
|
||||
|
||||
## Setup
|
||||
## About
|
||||
|
||||
Operations 1 and 2 require super user privileges to the API. The rest don't.
|
||||
*Behold, the (almighty) abgabesystem!**
|
||||
|
||||
1. Import the students participating in the course into Gitlab. This is required to assign projects to each student. If you have exported a list of groups and functions from Stud.IP you can use that.
|
||||
```
|
||||
# abgabesystem users -s <students.csv> -b <LDAP base domain> -p main
|
||||
```
|
||||
The aim of this project is to automate the handling of students' homework
|
||||
solutions using Gitlab. So far It can
|
||||
|
||||
2. Create a group for your course using
|
||||
```
|
||||
# abgabesystem courses -c <some_course>
|
||||
```
|
||||
|
||||
3. Create a fork of this project inside the namespace of the group that has been created and configure your API token (`PRIVATE_API_TOKEN`) and deploy key (`SSH_PRIVATE_KEY`) (see .gitlab-ci.yml) for the forked project.
|
||||
- import student accounts from LDAP,
|
||||
- import a list of users from Stud.IP,
|
||||
- create groups for courses in Gitlab,
|
||||
- set up repositories for the students
|
||||
- run automated style-checks and
|
||||
- test for plagiarisms.
|
||||
|
||||
4. Set up the project for the example solutions and the student projects. If you have pre-existing example solutions place them in `<some_course>/solutions/solutions`.
|
||||
```
|
||||
# abgabesystem projects -c <some_course> -d <deploy key> -s <students.csv>
|
||||
```
|
||||
## Setup Gitlab and CI runners
|
||||
|
||||
5. Add all administrative users (e.g. users supervising the course or checking homework solutions) to the group of the course.
|
||||
There are multiple components involved in the abgabesystem. The CI script uses a
|
||||
[https://github.com/timschubert/docker-abgabesystem](Docker Container) that
|
||||
contains the Python module and the [https://jplag.ipd.kit.edu/](JPlag)
|
||||
plagiarism checker. Another container with
|
||||
[https://github.com/timschubert/docker-checkstyle](Checkstyle) is optionally
|
||||
required for style checking of each student repository.
|
||||
|
||||
6. At the deadline of each exercise trigger the plagiarism checker using
|
||||
```
|
||||
# git tag <exercise_name>
|
||||
# git push --tags
|
||||
```
|
||||
It can be useful to do this from a cronjob.
|
||||
If you do not already have a working Gitlab instance see
|
||||
[https://docs.gitlab.com/omnibus/README.html#installation](here) how to install
|
||||
and configure it. Additionally you will need the
|
||||
[https://docs.gitlab.com/runner/](Gitlab CI runner). For performance reasons,
|
||||
you might want to have the CI runner on another host than Gitlab or otherwise
|
||||
limit the resources available to the runner (depending on the number of students
|
||||
and CI jobs).
|
||||
|
||||
## Recommended settings for gitlab.rb
|
||||
See [https://docs.gitlab.com/ce/administration/auth/ldap.html#doc-nav](here) on
|
||||
how to configure LDAP authentication.
|
||||
|
||||
## Install the python module
|
||||
|
||||
Install the python module using
|
||||
|
||||
```
|
||||
gitlab_rails['gitlab_default_can_create_group'] = false
|
||||
|
||||
# see gitlab documentation and add your ldap config
|
||||
gitlab_rails['ldap_enabled'] = true
|
||||
$ virtualenv abgabesystem
|
||||
$ source abgabesystem/bin/activate
|
||||
$ pip install .
|
||||
```
|
||||
|
||||
Also, you should
|
||||
## Set up the course
|
||||
|
||||
- set the default project limit for each user to 0
|
||||
- set default settings for projects to partially protected so that developers (e.g. students) can not force push tags and commits to protected branches (master) which is important for plagiarism controls.
|
||||
To proceed, you need to have an
|
||||
[https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html](API token)
|
||||
with administrative privileges. After having configured Gitlab and the runner,
|
||||
continue with setting up your course. Gitlab can only add existing users to
|
||||
projects, so we create pseudo-users that later will be fetched from LDAP, the
|
||||
first time each user logs in.
|
||||
|
||||
## Workflow
|
||||
First create your course either using the Gitlab UI or
|
||||
|
||||
To trigger the deadline of an exercise (e.g. Sunday at 15:00), push a tag (e.g.
|
||||
ex1) to the cloned abgabesystem project.
|
||||
The abgabesystem's CI job creates a tag of this name inside each student's project and then creates a checkout of each project's repository and runs [JPlag](https://github.com/jplag/jplag) to check for plagiates.
|
||||
The results can be found inside the job artifacts.
|
||||
The results are saved for each tag and can be downloaded as an archive.
|
||||
```
|
||||
$ abgabesystem courses -c <some_course>
|
||||
```
|
||||
|
||||
Next, since there is currently no API available to export a list of participants
|
||||
from [https://www.studip.de/](Stud.IP), we use the CSV file (encoded as latin-1
|
||||
🤢) that lists all students currently enrolled in the course. This list may of
|
||||
course change from time to time, so make sure to re-run the script regularly.
|
||||
|
||||
```
|
||||
$ abgabesystem users -s <students.csv> -b <LDAP base domain> -p main
|
||||
```
|
||||
|
||||
Now create a fork of this repository inside the namespace of the course.
|
||||
|
||||
This repository contains CI jobs that need their own
|
||||
[https://github.com/timschubert/docker-abgabesystem](Docker Container). Build
|
||||
the container, push it to the container registry and create a new runner that
|
||||
uses the container. You can also
|
||||
[https://docs.gitlab.com/ce/ci/docker/using_docker_build.html](automate this)
|
||||
using the CI scripts included in the Docker container projects and let your
|
||||
Gitlab CI build and deploy the updated containers for you.
|
||||
|
||||
Proceed by creating an API token that has access to the group of the course. Add
|
||||
this token as `PRIVATE_API_TOKEN` to the
|
||||
[https://docs.gitlab.com/ce/ci/variables/](secret variables) of the forked
|
||||
abgabesystem project. Then generate an SSH deploy key and add the private part
|
||||
as `SSH_PRIVATE_KEY` to the secret variables. The key will be used by the CI
|
||||
script to fetch from the student projects.
|
||||
|
||||
Set up the the student projects using
|
||||
|
||||
```
|
||||
$ abgabesystem projects -c <some_course> -d <deploy key> -s <students.csv>
|
||||
|
||||
```
|
||||
|
||||
Here deploy_key is the *PUBLIC* part of the deploy key. This creates one
|
||||
project per student, that each is forked from a project where your example
|
||||
solutions will be stored (`<course>/solutions/solutions`). Check that
|
||||
`<course>/solutions/` a contains project for each student.
|
||||
|
||||
At last, you can add everyone with permission to view all student solutions to
|
||||
the group of the course.
|
||||
|
||||
## Checking student solutions
|
||||
|
||||
When you have reachd the deadline for an exercise, push a new tag to
|
||||
`<course>/abgabesystem` to trigger the plagiarism checker and automatically
|
||||
create a tag in each student project.
|
||||
|
||||
```
|
||||
$ git tag <exercise_name>
|
||||
$ git push --tags
|
||||
```
|
||||
|
||||
Check the build artifacts of the CI job for the results of the plagiarism
|
||||
checker.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue