\chapter{Introduction}

\code{djehuty} is the data repository system developed by
4TU.ResearchData and Nikhef.  The name finds its inspiration in
\href{https://en.wikipedia.org/wiki/Thoth}{Thoth}, the Egyptian
entity that introduced the idea of writing.

\section{Obtaining the source code}
\label{sec:obtaining-tarball}

  \begin{sloppypar}
  The source code can be downloaded at the
  \href{https://github.com/4TUResearchData/djehuty/releases}%
  {Releases}%
  \footnote{\url{https://github.com/4TUResearchData/djehuty/releases}}
  page.  Make sure to download the {\fontfamily{\ttdefault}\selectfont
    djehuty-\djehutyversion{}.tar.gz} file.
  \end{sloppypar}

  Or, directly download the tarball using the command-line:

\begin{lstlisting}[language=bash]
curl -LO https://github.com/4TUResearchData/djehuty/releases/\(@*\\*@)download/v(@*\djehutyversion{}*@)/djehuty-(@*\djehutyversion{}*@).tar.gz
\end{lstlisting}

  After obtaining the tarball, it can be unpacked using the \t{tar}
  command:

\begin{lstlisting}[language=bash]
tar zxvf djehuty-(@*\djehutyversion{}*@).tar.gz
\end{lstlisting}

\section{Installing the prerequisites}
\label{sec:prerequisites}

  The \code{djehuty} program needs Python (version 3.9 or higher) and
  Git to be installed.  Additionally, a couple of Python packages need
  to be installed.  The following sections describe installing the
  prerequisites on various GNU/Linux distributions.  To put the software in
  the context of its environment, figure \ref{fig:references-graph} displays
  the complete run-time dependencies from \t{djehuty} to \t{glibc}.

  \includefigure{references-graph}{Run-time references when constructed with
    the packages from GNU Guix.}

  The web service of \code{djehuty} stores its information in a SPARQL 1.1
  \citep{sparql-11} endpoint.  We recommend either
  \href{https://blazegraph.com/}{Blazegraph}%
  \footnote{https://blazegraph.com/}
  or \href{http://vos.openlinksw.com/owiki/wiki/VOS}%
  {Virtuoso open-source edition}%
  \footnote{http://vos.openlinksw.com/owiki/wiki/VOS}.

\subsection{Optional installation requirements depending on configuration}

  For specific features \code{djehuty} may require additional packages to be
  installed.  Whether this is the case depends on the run-time configuration.
  When an optional package is required \code{djehuty} will report which one in
  its logs.  There are three configuration scenarios that require the
  additional packages: SAML, S3 and IIIF.

\subsubsection{SAML}

  When configuring the use of an identity provider via SAML \code{djehuty}
  requires the \code{python3-saml} Python package to be installed.  This
  package provides the implementation of the SAML protocol.

\subsubsection{S3}

  When configuring file access in S3 buckets \code{djehuty} requires the
  \code{boto3} Python package to be installed.  This package is used to
  authenticate to the S3 endpoints and to download (or stream) data.

\subsubsection{IIIF}

  When enabling the IIIF functionality \code{djehuty} requires the
  \code{pyvips} Python package to be installed.  This package is used to
  perform image transformations.

\section{Installation instructions}

  After obtaining the source code (see section \refer{sec:obtaining-tarball})
  and installing the required tools (see section \refer{sec:prerequisites}),
  building involves running the following commands:

\begin{lstlisting}[language=bash]
cd djehuty-(@*\djehutyversion{}*@)
autoreconf -vif # Only needed if the "./configure" step does not work.
./configure
make
make install
\end{lstlisting}

  To run the \t{make install} command, super user privileges may be
  required.  Specify a \t{-{}-prefix} to the \t{configure}
  script to install the tools to a user-writeable location to avoid
  needing super user privileges.

  After installation, the \t{djehuty} program will be available.

\section{Pre-built containers}

  4TU.ResearchData provides Docker container images as a convenience service
  for each monthly \t{djehuty} release.  The following table outlines the
  meaning of each image provided.  The images are published to
  \href{https://hub.docker.com/r/4turesearchdata/djehuty}{Docker Hub}%
  \footnote{\dhref{https://hub.docker.com/r/4turesearchdata/djehuty}}.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Image tag}  & \textbf{Description}\\
  \t{devel}           & Image meant for development purposes.  Before it
                        executes the \t{djehuty} command it checks out the
                        latest codebase.  So re-running the same container
                        image may result in running a different version of
                        \t{djehuty}.\\
  \t{latest}          & This image points to the latest \t{djehuty} release.
                        It does not automatically update the \t{djehuty}
                        codebase.\\
  \t{XX.X}            & 4TU.ResearchData releases a version each month where
                        the number before the dot refers to the year and the
                        number after the dot refers to the month.  Use a
                        specific version image when you want to upgrade at
                        your own pace.
\end{tabularx}

  To build the container images for yourself, see the build instructions in
  the \file{docker/Dockerfile} file.

\section{RPM packages}

  4TU.ResearchData provides RPM packages built for Enterprise Linux 9.  This
  RPM depends on packages in the \href{https://docs.fedoraproject.org/en-US/epel}%
  {Extra Packages for Enterprise Linux (EPEL)} repository.

\begin{tabularx}{\textwidth}{*{1}{!{\VRule[-1pt]}l}!{\VRule[-1pt]}X}
  \headrow
  \textbf{Filename}  & \textbf{Description}\\
  \href{https://github.com/4TUResearchData/djehuty/releases/download/v\djehutyversion/djehuty-\djehutyversion-1.el9.noarch.rpm}%
  {djehuty-\djehutyversion-1.el9.noarch.rpm} & Binary RPM, to install and run \t{djehuty}.\\
  \href{https://github.com/4TUResearchData/djehuty/releases/download/v\djehutyversion/djehuty-\djehutyversion-1.el9.src.rpm}%
  {djehuty-\djehutyversion-1.el9.src.rpm} & Source RPM, to (re)build from source code.
\end{tabularx}

  RPM packages for more distributions are
  \href{https://copr.fedorainfracloud.org/coprs/4turesearchdata/djehuty}%
  {built via Copr}.
