\chapter{Configuring \texttt{djehuty}}
\label{chap:configuring-djehuty}
Now that \code{djehuty} is installed, it's a good moment to look into its
run-time configuration options.  All configuration can be done through a
configuration file, for which an example is available at
\file{etc/djehuty/djehuty-example-config.xml}.

\section{Essential options}

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}            & \textbf{Description}\\
  \t{bind-address}           & The address to bind a TCP socket on.\\
  \t{port}                   & The port to bind a TCP socket on.\\
  \t{alternative-port}       & A fall-back port to bind on when \t{port} is
                               already in use.\\
  \t{base-url}               & The URL on which the instance will be available
                               to the outside world.\\
  \t{allow-crawlers}         & Set to 1 to allow crawlers in the \t{robots.txt},
                               otherwise set to 0.\\
  \t{production}             & Performs extra checks before starting. Enable
                               this when running a production instance.\\
  \t{live-reload}            & When set to 1, it reloads Python code on-the-fly.
                               We recommend to set it to 0 when running in
                               production.\\
  \t{debug-mode}             & When set to 1, it will display backtraces and
                               error messages in the web browser. When set to 0,
                               it will only show backtraces and error messages
                               in the web browser.\\
  \t{use-x-forwarded-for}    & When running \t{djehuty} behind a reverse-proxy
                               server, use the HTTP header \t{X-Forwarded-For}
                               to log IP address information.\\
  \t{disable-collaboration}  & When set to 1, it disables the ``collaborators''
                               feature.\\
  \t{allowed-depositing-domains} & When unset, any authenticated user may
                               deposit data.  Otherwise, this option limits the
                               ability to deposit to users with an e-mail
                               address of the listed domain names.\\
  \t{cache-root}             & \t{djehuty} can cache query responses to lower
                               the load on the database server.  Specify the
                               directory where to store cache files.  This
                               element takes an attribute \t{clear-on-start},
                               and when set to 1, it will remove all cache files
                               on start-up of \t{djehuty}.\\
  \t{profile-images-root}    & Users can upload a profile image in \t{djehuty}.
                               This option should point to a filesystem directory
                               where these profile images can be stored.\\
  \t{disable-2fa}            & Accounts with privileges receive a code by e-mail
                               as a second factor when logging in.  Setting this
                               option to 1 disables the second factor
                               authentication.\\
  \t{sandbox-message}        & Display a message on the top of every page.\\
  \t{notice-message}         & Display a message on the main page.\\
  \t{maintenance-mode}       & When set to 1, all HTTP requests result in the
                               displayment of a maintenance message. Use this
                               option while backing up the database, or when
                               performing major updates.
\end{tabularx}

\section{Configuring the Database}

  The \t{djehuty} program stores its state in a SPARQL 1.1 compliant
  RDF store.  Configuring the connection details is done in the
  \t{rdf-store} node.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}            & \textbf{Description}\\
  \t{state-graph}            & The graph name to store triplets in.\\
  \t{sparql-uri}             & The URI at which the SPARQL 1.1 endpoint can
                               be reached.\newline\newline
                               When the \t{sparql-uri} begins with \t{bdb://},
                               followed by a path to a filesystem directory,
                               it will use the BerkeleyDB back-end, for which
                               the \code{berkeleydb} Python package needs to
                               be installed.\\
  \t{sparql-update-uri}      & The URI at which the SPARQL 1.1 Update endpoint
                               can be reached (in case it is different from
                               the \t{sparql-uri}.
\end{tabularx}

\section{Audit trails and database reconstruction}

  The \t{djehuty} program can keep an audit log of all database modifications
  made by itself from which a database state can be reconstructed.  Whether
  \t{djehuty} keeps such an audit log can be configured with the following
  option:

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}            & \textbf{Description}\\
  \t{enable-query-audit-log} & When set to 1, it writes every SPARQL query that
                               modifies the database in the web logs.  This can
                               be replayed to reconstruct the database at a
                               later time.  Setting this option to 0 disables
                               this feature.  This element takes an attribute
                               \t{transactions-directory} that should specify
                               an empty directory to which transactions can be
                               written that are extracted from the audit log.
\end{tabularx}

\subsection{Reconstructing the database from the query audit log}

  Each query that modifies the database state while the query audit logs
  are enabled can be extracted from the query audit log using the
  \t{-{}-extract-transactions-from-log} command-line option.  A timestamp to
  specify the starting point to extract from can be specified as an argument.
  The following example displays its use:

\begin{lstlisting}[language=bash]
djehuty web --config-file=config.xml --extract-transactions-from-log="YYYY-MM-DD HH:MM:SS"
\end{lstlisting}

This will create a file for each query in the folder specified in the
\t{transactions-directory} attribute.

  To replay the extracted transactions, use the \t{apply-transactions}
  command-line option:
\begin{lstlisting}[language=bash]
djehuty web --config-file=config.xml --apply-transactions
\end{lstlisting}

  When a query cannot be executed, the command stops, allowing to fix or
  remove the query to-be-replayed.  Invoking the \t{-{}-apply-transactions}
  command a second time will continue replaying where the previous run stopped.

\section{Configuring storage}

  Storage locations can be configured with the \t{storage} node.
  When configuring multiple locations, \t{djehuty} attempts to find a
  file by looking at the first configured location, and in case it cannot
  find the file there, it will look at the second configured location,
  and so on, until it has tried each storage location.

  This allows for moving files between storage systems transparently
  without requiring specific interactions with \t{djehuty} other than
  having the files made available as a POSIX filesystem or in an S3 bucket.

  One use-case that suits this mechanism is letting uploads write to
  fast online storage and later move the uploaded files to a slower but
  less costly storage.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}            & \textbf{Description}\\
  \t{location}               & A filesystem path to where files are stored.
                               This is a repeatable property.\\
  \t{s3-bucket}              & An S3 bucket configuration. See section
                               \ref{sec:s3-buckets}. This is a repeatable
                               property.
\end{tabularx}

\subsection{Configuring S3 buckets}
\label{sec:s3-buckets}

  Other than configuring storage locations on a POSIX filesystem,
  \code{djehuty} can be configured to serve files from an S3 bucket.
  To do so, the following parameters must be configured within a\
  \code{s3-bucket} node.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{endpoint}                & Endpoint URL to connect to.\\
  \t{name}                    & Name of the bucket.\\
  \t{key-id}                  & Key ID for the bucket.\\
  \t{secret-key}              & Secret key for the bucket.
\end{tabularx}

  For example, configuring one filesystem location and one S3 bucket
  as storage locations looks as following:

\begin{lstlisting}[language=xml]
<storage>
  <location>/data</location>
  <s3-bucket>
    <endpoint>https://some.example</endpoint>
    <name>example-bucket</name>
    <key-id>...</key-id>
    <secret-key>...</secret-key>
  </s3-bucket>
</storage>
\end{lstlisting}

  There are a few scenarios in which \code{djehuty} downloads an S3 object
  to perform some operation on: creating thumbnails and IIIF image
  transformations.  To direct where these temporary files will be stored,
  the \t{s3-cache-root} can be configured.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{s3-cache-root}           & The directory to store the S3 objects
                                while performing some operation on the
                                objects.  This option can only be configured
                                globally and applies to all S3 buckets.
\end{tabularx}

\section{Configuring an identity provider}

  Ideally, \t{djehuty} makes use of an external identity provider.
  \t{djehuty} can use SAML2.0, ORCID, or an internal identity provider
  (for testing and development purposes only).

  This section will outline the configuration options for each
  identity provision mechanism.

\subsection {SAML2.0}

  For SAML 2.0, the configuration can be placed in the \t{saml}
  section under \t{authentication}.  That looks as following:

\begin{lstlisting}[language=xml]
<authentication>
  <saml version="2.0">
    <!-- Configuration goes here. -->
  </saml>
</authentication>
\end{lstlisting}

  The options outlined in the remainder of this section should be placed
  where the example shows \code{<!-- Configuration goes here. -->}.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{strict}                  & When set to 1, SAML responses must be signed.
                                \textbf{Never disable `strict' mode in a
                                production environment.}\\
  \t{debug}                   & Increases logging verbosity for SAML-related messages.\\
  \t{attributes}              & In this section the attributes provided by the
                                identity provider can be aligned to the
                                attributes \t{djehuty} expects.\\
  \t{service-provider}        & The \t{djehuty} program fulfills the role of
                                service provider.  In this section the
                                certificate and service provider metadata
                                can be configured.\\
  \t{identity-provider}       & In this section the certificate and
                                single-sign-on URL of the identity provider
                                can be configured.\\
  \t{sram}                    & In this section, SURF Research Access
                                Management-specific attributes can be
                                configured.
\end{tabularx}

\subsubsection{The \t{attributes} configuration}

  To create account and author records and to authenticate a user, \t{djehuty}
  stores information provided by the identity provider.  Each identity provider
  may provide this information using different attributes.  Therefore, the
  translation from attributes used by \t{djehuty} and attributes given by the
  identity provider can be configured.  The following attributes must be
  configured.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{first-name}              & A user's first name.\\
  \t{last-name}               & A user's last name.\\
  \t{common-name}             & A user's full name.\\
  \t{email}                   & A user's e-mail address.\\
  \t{groups}                  & The attribute denoting groups.\\
  \t{group-prefix}            & The prefix for each group short name.
\end{tabularx}

  As an example, the attributes configuration for SURFConext looks like this:

\begin{lstlisting}[language=xml]
<attributes>
  <first-name>urn:mace:dir:attribute-def:givenName</first-name>
  <last-name>urn:mace:dir:attribute-def:sn</last-name>
  <common-name>urn:mace:dir:attribute-def:cn</common-name>
  <email>urn:mace:dir:attribute-def:mail</email>
</attributes>
\end{lstlisting}

  And for SURF Research Access Management (SRAM), the attributes configuration
  looks like this:

\begin{lstlisting}[language=xml]
<attributes>
  <first-name>urn:oid:2.5.4.42</first-name>
  <last-name>urn:oid:2.5.4.4</last-name>
  <common-name>urn:oid:2.5.4.3</common-name>
  <email>urn:oid:0.9.2342.19200300.100.1.3</email>
  <groups>urn:oid:1.3.6.1.4.1.5923.1.1.1.7</groups>
  <group-prefix>urn:mace:surf.nl:sram:group:[organisation]:[service]</group-prefix>
</attributes>
\end{lstlisting}

\subsubsection{The \t{sram} configuration}

  When using SURF Research Access Management (SRAM),
  \t{djehuty} can persuade SRAM to send an invitation to anyone
  inside or outside the institution to join the SRAM collaboration
  that provides access to the \t{djehuty} instance.  To do so,
  the following attributes must be configured.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{organization-api-token}  & An organization-level API token.\\
  \t{collaboration-id}        & The UUID of the collaboration to invite
                                users to.
\end{tabularx}

\subsubsection{The \t{service-provider} configuration}

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}              & \textbf{Description}\\
  \t{x509-certificate}         & Contents of the public certificate without
                                 whitespacing.\\
  \t{private-key}              & Contents of the private key belonging to the
                                 \t{x509-certificate} to sign messages with.\\
  \t{metadata}                 & This section contains metadata that may be
                                 displayed by the identity provider to users
                                 before authorizing them.\\
  \cfgindent\t{display-name}   & The name to be displayed by the identity
                                 provider when authorizing the user to the
                                 service.\\
  \cfgindent\t{url}            & The URL to the service.\\
  \cfgindent\t{description}    & Textual description of the service.\\
  %\cfgindent\t{logo}          & \\
  \cfgindent\t{organization}   & This section contains metadata to describe the
                                organization behind the service.\\
  \cfgindent\cfgindent\t{name} & The name of the service provider's organization.\\
  \cfgindent\cfgindent\t{url}  & The URL to the web page of the organization.\\
  \cfgindent\t{contact}        & A repeatable section to list contact persons
                                 and their roles within the organization. The
                                 role can be configured by setting the \t{type}
                                 attribute.\\
  \cfgindent\cfgindent\t{first-name} & The first name of the contact person.\\
  \cfgindent\cfgindent\t{last-name} & The last name of the contact person.\\
  \cfgindent\cfgindent\t{email} & The e-mail address of the contact person.
                                  Note that some identity providers prefer
                                  functional e-mail addresses (e.g. support@...
                                  instead of jdoe@...).
\end{tabularx}

\subsection{ORCID}

  \href{https://orcid.org}{ORCID.org} plays a key role in making researchers
  findable.  Its identity provider service can be used by \t{djehuty} in two ways:
  \begin{enumerate}
  \item{As primary identity provider to log in and deposit data;}
  \item{As additional identity provider to couple an author record to its ORCID record.}
  \end{enumerate}

  When another identity provider is configured in addition to ORCID, that
  identity provider will be used as primary and ORCID will only be used to
  couple author records to the author's ORCID record.

  To configure ORCID, the configuration can be placed in the \t{orcid}
  section under \t{authentication}.  That looks as following:

\begin{lstlisting}[language=xml]
<authentication>
  <orcid>
    <!-- Configuration goes here. -->
  </orcid>
</authentication>
\end{lstlisting}

  Then the following parameters can be configured:

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{client-id}               & The client ID provided by ORCID.\\
  \t{client-secret}           & The client secret provided by ORCID.\\
  \t{endpoint}                & The URL to the ORCID endpoint to use.
\end{tabularx}

\section{Configuring an e-mail server}

  On various occassions, \t{djehuty} will attempt to send an e-mail to either
  an author, a reviewer or an administrator.  To be able to do so, an e-mail
  server must be configured from which the instance may send e-mails.

  The configuration is done under the \t{email} node, and the following
  items can be configured:

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{server}                  & Address of the e-mail server without protocol
                                specification.\\
  \t{port}                    & The port the e-mail server operates on.\\
  \t{starttls}                & When 1, \t{djehuty} attempts to use StartTLS.\\
  \t{username}                & The username to authenticate with to the
                                e-mail server.\\
  \t{password}                & The password to authenticate with to the
                                e-mail server.\\
  \t{from}                    & The e-mail address used to send e-mail from.\\
  \t{subject-prefix}          & Text to prefix in the subject of all e-mails
                                sent from the instance of \t{djehuty}.  This
                                can be used to distinguish a test instance from
                                a production instance.
\end{tabularx}

\section{Configuring DOI registration}

  When publishing a dataset or collection, \t{djehuty} can register a
  persistent identifier with DataCite.  To enable this feature, configure it
  under the \t{datacite} node. The following parameters can be configured:

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{api-url}                 & The URL of the API endpoint of DataCite.\\
  \t{repository-id}           & The repository identifier given by DataCite.\\
  \t{password}                & The password to authenticate with to DataCite.\\
  \t{prefix}                  & The DOI prefix to use when registering a DOI.
\end{tabularx}

\section{Configuring Handle registration}

  Each uploaded file can be assigned a persistent identifier using the Handle
  system.  To enable this feature, configure it under the \t{handle} node.
  The following parameters can be configured:

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{url}                     & The URL of the API endpoint of the Handle
                                system implementor.\\
  \t{certificate}             & Certificate to use for authenticating to the
                                endpoint.\\
  \t{private-key}             & The private key paired with the certificate
                                used to authenticate to the endpoint.\\
  \t{prefix}                  & The Handle prefix to use when registering a
                                handle.\\
  \t{index}                   & The index to use when registering a handle.
\end{tabularx}

\section{Configuring IIIF support}

  When publishing images, \t{djehuty} can enable the IIIF Image API for the
  images. It uses \t{libvips} and \t{pyvips} under the hood to perform image
  manipulation.  The following parameters can be configured:

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{enable-iiif}             & Enable support for the IIIF image API.  This
                                requires the \t{pyvips} package to be available
                                in the run-time environment.\\
  \t{iiif-cache-root}         & The directory to store the output of IIIF Image
                                API requests to avoid re-computing the image.
\end{tabularx}

\section{Customizing looks}

  With the following options, the instance can be branded as necessary.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}             & \textbf{Description}\\
  \t{site-name}               & Name for the instance used in the title of a
                                browser window and as default value in the
                                publisher field for new datasets.\\
  \t{site-description}        & Description used as a meta-tag in the HTML
                                output.\\
  \t{site-shorttag}           & Used as keyword and as Git remote name.\\
  \t{ror-url}                 & The ROR URL for this instance's organization.\\
  \t{support-email-address}   & E-mail address used in e-mails sent to users
                                in automated messages.\\
  \t{custom-logo-path}        & Path to a PNG image file that will be used as
                                logo on the website.\\
  \t{custom-favicon-path}     & Path to an ICO file that will be used as
                                favicon.\\
  \t{small-footer}            & HTML that will be used as footer for all
                                pages except for the main page.\\
  \t{large-footer}            & HTML that will be used as footer on the
                                main page.\\
  \t{show-portal-summary}     & When set to 1, it shows the repository summary
                                of number of datasets, authors, collections,
                                files and bytes on the main page.\\
  \t{show-institutions}       & When set to 1, it shows the list of
                                institutions on the main page.\\
  \t{show-science-categories} & When set to 1, it shows the subjects
                                (categories) on the main page.\\
  \t{show-latest-datasets}    & When set to 1, it shows the list of latest
                                published datasets on the main page.\\
  \t{colors}                  & Colors used in the HTML output. See section
                                \ref{sec:customize-colors}.
\end{tabularx}

\subsection{Customizing colors}
\label{sec:customize-colors}

  The following options can be configured in the \t{colors} section.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}              & \textbf{Description}\\
  \t{primary-color}            & The main background color to use.\\
  \t{primary-foreground-color} & The main foreground color to use.\\
  \t{primary-color-hover}      & Color to use when hovering a link.\\
  \t{primary-color-active}     & Color to use when a link is clicked.\\
  \t{privilege-button-color}   & The background color of buttons for
                                 privileged actions.\\
  \t{footer-background-color}  & Color to use in the footer.\\
  \t{background-color}         & Background color for the content section.
\end{tabularx}

\section{Configuring privileged users}

  By default an authenticated user may deposit data. But users can have
  additional roles; for example: a dataset reviewer, a technical
  administrator or a quota reviewer.

  Such additional roles are configured in terms of privileges.  The
  following privileges can be configured in the \t{privileges} section:

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Option}                     & \textbf{Description}\\
  \t{may-administer}                  & Allows access to perform maintenance
                                        tasks, view accounts and view reports
                                        on restricted and embargoed datasets.\\
  \t{may-run-sparql-queries}          & Allows to run arbitrary SPARQL queries
                                        on the database.\\
  \t{may-impersonate}                 & Allows to log in to any account and
                                        therefore perform any action as that
                                        account.\\
  \t{may-review}                      & Allows to see which datasets are sent
                                        for review, and allows to perform
                                        reviews.\\
  \t{may-review-quotas}               & Allows access to see requests for
                                        storage quota increases and approve or
                                        decline them.\\
  \t{may-review-integrity}            & Allows access to an API call that
                                        provides statistics on the accessibility
                                        of files on the filesystem.\\
  \t{may-process-feedback}            & Accounts with this privilege will
                                        receive e-mails with the information
                                        entered into the feedback form by other
                                        users.\\
  \t{may-receive-email-notifications} & This ``privilege'' can be used to disable
                                        sending any e-mails to an account by
                                        setting it to \t{0}.  The default is
                                        \t{1}.
\end{tabularx}

  To enable a privilege for an account, set the value of the desired privilege
  to \t{1}.  Privileges are disabled by default, except for
  \t{may-receive-email-notifications} which defaults to \t{1}.

\begin{lstlisting}[language=xml]
  <privileges>
    <account email="you@example.com" orcid="0000-0000-0000-0001">
      <may-administer>1</may-administer>
      <may-run-sparql-queries>1</may-run-sparql-queries>
      <may-impersonate>1</may-impersonate>
      <may-review>0</may-review>
      <may-review-quotas>0</may-review-quotas>
      <may-review-integrity>0</may-review-integrity>
      <may-process-feedback>0</may-process-feedback>
      <may-receive-email-notifications>1</may-receive-email-notifications>
    </account>
  </privileges>
\end{lstlisting}
