Configuration
=============

.. _configuration:

.. toctree::
   :caption: Configuration

.. index:: Configuration Documentation

System Configuration
####################

The system configuration depends on the systems d-gree is running one. There are multiple possible variants:

* Combined management and serving parts. Management is concerned with the :ref:`workflows` on behalf of the lecturers or course responsibles, whereas serving is concerned with enabling successful participants retrieve their micro-credentials.
* Decoupled management and serving parts. Serving is restricted to static artefacts and could therefore even be delegated to a minimalistic web server.
* No serving, only management. Recipients get notified of their achievements including embedded/attached portable micro-credentials such as badges and confirmation documents. This is the case when no storage infrastructure is considered, however, this impacts the triple safety negatively as outlined in :ref:`concepts`.

Depending on the policies, at-rest encryption, in-flight encryption and log file handling need to be configured separately. When deployed on the Internet Computer, in-flight encryption through HTTPS is enabled by default; otherwise, the appropriate certificates need to be obtained and installed separately.
At-rest encryption might not be strictly necessary for the badges themselves are they are anonymised with only hashed identities.

The log file analysis is discussed in :ref:`analytics`.

Workspace Configuration
#######################

In the following, several key-value pairs grouped in sections are presented that control the micro-credential production workflows for the CLI components. The configuration can be produced manually for direct use with the 'automatic.sh' script, or automatically with the :ref:`configurator` component. One can assume the support for multi-lingual configuration in case documents such as confirmation letters should be produced in multiple languages.

First, a certificate- or degree-issuing institution that decides to use d-gree will configure its own identity. The university (or training centre) name, department and location, as well as contact information (URL, e-mail address) and quality assurance statements such as accreditations. This information should rarely change, and is replicated to every new workspace.

 | [issuer]
 | uni = ... Awesome University
 | dept = ... Awesome Department
 | loc = ... Some Town
 | url = ... https://...
 | email = ... info@university.invalid
 | qa = ... Accredited by government

Next, for each achievement that can be obtained, the course/event information is given. This relates to the title (usually 'micro-credential'), the achievement itself as degree as well as the title of the correponding participation confirmation, and the associated learning activity, form and workload in credit point equivalents. The level refers to the expected qualification level of the participants.

 | [achievement]
 | title = ... Micro-credential
 | degree = ... Guru-level Hacking
 | participation = ... Participation confirmation
 | learningactivity = ... Advanced Guru Course
 | learningform = ... Onsite
 | workload = ... 9
 | level = ... Master students
 | objectives = ... Hacking in 99 programming languages, and everything else
 | description = ... Touch assessment on whether candidates understand variables and loops

Next, the configuration encompasses course responsibles and lecturers who appear as signatories. For e-signed confirmation documents, the e-mail address is necessary, otherwise it is optional. The list of signatories can references signatory-specific sections, indicated by the dollar sign ($) in the given syntax.

 | sigs = $sig:1
 | [sig:1]
 | name = ... Jane Lect
 | role = ... Lecturer
 | institution = ... Awesome University Advanced Education Staff
 | email = ... jane@university.invalid

To customise the appearance especially of confirmation documents, further configuration of visuals is supported, such as an institutional logo and a competence diagram appearing on the second page.

 | [layout]
 | logo = ... awesomeuni.png
 | bottomline = ... The best university in town
 | bottomlogo = ... unibanner.jpg # mutually exclusive with bottomline
 | competences = ... competencespider.pdf

Finally, in case the badges are hosted on a web server, they need a base URL that all generated URLs relate to, in addition to a base image that is used for the achievement-specific badge image production as defined in :ref:`artefacts`.

 | [badge]
 | baseurl = ... https://...
 | image = ... badge.png