%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax

\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
 \ifdefined\DeclareUnicodeCharacterAsOptional
  \DeclareUnicodeCharacter{"00A0}{\nobreakspace}
  \DeclareUnicodeCharacter{"2500}{\sphinxunichar{2500}}
  \DeclareUnicodeCharacter{"2502}{\sphinxunichar{2502}}
  \DeclareUnicodeCharacter{"2514}{\sphinxunichar{2514}}
  \DeclareUnicodeCharacter{"251C}{\sphinxunichar{251C}}
  \DeclareUnicodeCharacter{"2572}{\textbackslash}
 \else
  \DeclareUnicodeCharacter{00A0}{\nobreakspace}
  \DeclareUnicodeCharacter{2500}{\sphinxunichar{2500}}
  \DeclareUnicodeCharacter{2502}{\sphinxunichar{2502}}
  \DeclareUnicodeCharacter{2514}{\sphinxunichar{2514}}
  \DeclareUnicodeCharacter{251C}{\sphinxunichar{251C}}
  \DeclareUnicodeCharacter{2572}{\textbackslash}
 \fi
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage[dontkeepoldnames]{sphinx}

\usepackage{geometry}

% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}
\addto\captionsenglish{\renewcommand{\contentsname}{Contents:}}

\addto\captionsenglish{\renewcommand{\figurename}{Fig.}}
\addto\captionsenglish{\renewcommand{\tablename}{Table}}
\addto\captionsenglish{\renewcommand{\literalblockname}{Listing}}

\addto\captionsenglish{\renewcommand{\literalblockcontinuedname}{continued from previous page}}
\addto\captionsenglish{\renewcommand{\literalblockcontinuesname}{continues on next page}}

\addto\extrasenglish{\def\pageautorefname{page}}

\setcounter{tocdepth}{1}



\title{Labfolder at FHI Documentation}
\date{Jan 11, 2018}
\release{1.0}
\author{Stefan Weiher}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex

\begin{document}

\maketitle
\sphinxtableofcontents
\phantomsection\label{\detokenize{index::doc}}



\chapter{Installation of labfolder}
\label{\detokenize{installation:welcome-to-elog2labfolder-s-documentation}}\label{\detokenize{installation::doc}}\label{\detokenize{installation:installation-of-labfolder}}
Labfolder is easy to install. Follow the instructions given in the \sphinxstyleemphasis{labfolder Installation Manual}. The broad steps are: \sphinxstylestrong{install MySQL, docker and labolder; configure labfolder via the server.cnf file}. This labfolder config file could look like this:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZsh{} Network settings
DEFAULT\PYGZus{}HTTP\PYGZus{}PROTOCOL=https://
DEFAULT\PYGZus{}DOMAIN=labfolder.rz\PYGZhy{}berlin.mpg.de

\PYGZsh{} JDBC Properties
JDBC\PYGZus{}SERVER\PYGZus{}TIMEZONE=Europe/Berlin
JDBC\PYGZus{}DATABASE\PYGZus{}URL=jdbc:mysql://localhost:3306/labfolder?useUnicode=true\PYGZam{}characterEncoding=UTF\PYGZhy{}8
JDBC\PYGZus{}USERNAME=labfolder
JDBC\PYGZus{}PASSWORD=fhilab
JDBC\PYGZus{}SCHEMA\PYGZus{}NAME=labfolder
\PYGZsh{}REMOVE\PYGZus{}ABANDONED\PYGZus{}TIMEOUT=60

\PYGZsh{} Mail client properties
MAIL\PYGZus{}STARTTLS=false
MAIL\PYGZus{}AUTHENTICATION\PYGZus{}ENABLE=false
MAIL\PYGZus{}HOST=mail.fhi\PYGZhy{}berlin.mpg.de
MAIL\PYGZus{}PORT=25
\PYGZsh{}MAIL\PYGZus{}USERNAME=
\PYGZsh{}MAIL\PYGZus{}PASSWORD=
MAIL\PYGZus{}EMAIL=ppb@fhi\PYGZhy{}berlin.mpg.de

\PYGZsh{} Server Event logging
LOG\PYGZus{}TO\PYGZus{}FILE=true

\PYGZsh{}Maximum upload file size
FILEUPLOAD\PYGZus{}MAXUPLOADSIZE=25000000

\PYGZsh{} User and group control
DEFAULT\PYGZus{}GROUP\PYGZus{}SIZE=50
DEFAULT\PYGZus{}GROUP\PYGZus{}TYPE\PYGZus{}MAXI=true
DEFAULT\PYGZus{}USER\PYGZus{}STORAGE=3221225472
FEATURE\PYGZus{}GLOBAL\PYGZus{}PREVENT\PYGZus{}DELETE\PYGZus{}CONTENT=false

\PYGZsh{} Terms and Privacy links
TERMS\PYGZus{}OF\PYGZus{}USE\PYGZus{}LINK=https://www.labfolder.com/terms\PYGZhy{}external\PYGZhy{}servers/
PRIVACY\PYGZus{}LINK=https://www.labfolder.com/privacy\PYGZhy{}external\PYGZhy{}servers/

\PYGZsh{} LDAP Authentication
FEATURE\PYGZus{}LDAP\PYGZus{}AUTHENTICATION=true
LDAP\PYGZus{}URL=ldap://ldap.rz\PYGZhy{}berlin.mpg.de:389
LDAP\PYGZus{}BASE=ou=people,dc=ppb,dc=rz\PYGZhy{}berlin,dc=mpg,dc=de
\PYGZsh{}LDAP\PYGZus{}SERVER\PYGZus{}TYPE=
LDAP\PYGZus{}USER\PYGZus{}DN=cn=pwCheck,dc=rz\PYGZhy{}berlin,dc=mpg,dc=de
LDAP\PYGZus{}PASSWORD=ProstetnikVogonJeltz
\PYGZsh{}LDAP\PYGZus{}ANONYMOUS\PYGZus{}READ\PYGZus{}ONLY=
LDAP\PYGZus{}USER\PYGZus{}DN\PYGZus{}PATTERNS=uid=\PYGZob{}0\PYGZcb{}
\PYGZsh{}LDAP\PYGZus{}IS\PYGZus{}TLS\PYGZus{}ENABLED=
\PYGZsh{}LDAP\PYGZus{}IS\PYGZus{}ATTRIBUTE\PYGZus{}SEARCH\PYGZus{}ENABLED=
\PYGZsh{}LDAP\PYGZus{}ATTRIBUTE\PYGZus{}SEARCH\PYGZus{}NAME=

\PYGZsh{} Usage monitoring
ACTIVE\PYGZus{}USER\PYGZus{}REPORT\PYGZus{}USE\PYGZus{}DEFAULT\PYGZus{}MAIL\PYGZus{}CLIENT=true
CUSTOMER\PYGZus{}IDENTIFIER=\PYGZsq{}Fritz\PYGZhy{}Haber\PYGZhy{}Institut\PYGZsq{}

\PYGZsh{} Mendeley
FEATURE\PYGZus{}MENDELEY=false
\PYGZsh{}MENDELEY\PYGZus{}CLIENT\PYGZus{}ID=
\PYGZsh{}MENDELEY\PYGZus{}CLIENT\PYGZus{}SECRET=
\PYGZsh{}MENDELEY\PYGZus{}CLIENT\PYGZus{}CALLBACKURL=http://localhost:9091/eln/mendeley/oauthCallback

\PYGZsh{} Dropbox
FEATURE\PYGZus{}DROPBOX=false
\PYGZsh{}DROPBOX\PYGZus{}CONSUMER\PYGZus{}KEY=
\PYGZsh{}DROPBOX\PYGZus{}CONSUMER\PYGZus{}SECRET=

\PYGZsh{} Figshare
FEATURE\PYGZus{}FIGSHARE=false

\PYGZsh{} XHTML Export
FEATURE\PYGZus{}XHTML\PYGZus{}EXPORT=true
EXPORT\PYGZus{}DOCUMENT\PYGZus{}REPOSITORY\PYGZus{}TYPE=fileSystem
\end{sphinxVerbatim}

The configuration is explained in detail in the installation manual. Now, \sphinxstylestrong{create the labfolder database and run labfolder} (see the manual for details). Additionally, you could install Apache and set it up as a reverse proxy in order to make labfolder only available through https. The exact steps are:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
labfolder@lf:\PYGZti{}\PYGZdl{} sudo apt\PYGZhy{}get install build\PYGZhy{}essential
labfolder@lf:\PYGZti{}\PYGZdl{} sudo apt install apache2
labfolder@lf:\PYGZti{}\PYGZdl{} sudo a2enmod proxy proxy\PYGZus{}ajp proxy\PYGZus{}http rewrite deflate headers proxy\PYGZus{}balancer proxy\PYGZus{}connect proxy\PYGZus{}html xml2enc
labfolder@lf:\PYGZti{}\PYGZdl{} sudo a2enmod ssl

\PYGZsh{}\PYGZsh{}\PYGZsh{} Use certificates from e.g. let\PYGZsq{}s encrypt. Please see below for more information.

\PYGZsh{}\PYGZsh{}\PYGZsh{} create /etc/apache2/sites\PYGZhy{}available/labfolder.conf with virtual hosts for http and https:
labfolder@lf:\PYGZti{}\PYGZdl{} sudo a2ensite labfolder.conf
labfolder@lf:\PYGZti{}\PYGZdl{} sudo a2dissite 000\PYGZhy{}default.conf
labfolder@lf:\PYGZti{}\PYGZdl{} sudo service apache2 restart
\end{sphinxVerbatim}

To get SSL certificates from letsencrypt is quite straight forward. For example this guide shows how to set up SSL certificates:

\sphinxurl{https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-16-04}

The Apache labfolder config file could look like this:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{o}{\PYGZlt{}}\PYG{n}{VirtualHost} \PYG{o}{*}\PYG{p}{:}\PYG{l+m+mi}{80}\PYG{o}{\PYGZgt{}}
    \PYG{n}{ErrorLog} \PYG{o}{/}\PYG{n}{var}\PYG{o}{/}\PYG{n}{log}\PYG{o}{/}\PYG{n}{apache2}\PYG{o}{/}\PYG{n}{error}\PYG{o}{.}\PYG{n}{log}
    \PYG{n}{LogLevel} \PYG{n}{warn}

    \PYG{n}{ServerName} \PYG{n}{labfolder}\PYG{o}{.}\PYG{n}{rz}\PYG{o}{\PYGZhy{}}\PYG{n}{berlin}\PYG{o}{.}\PYG{n}{mpg}\PYG{o}{.}\PYG{n}{de}
    \PYG{n}{Redirect} \PYG{o}{/} \PYG{n}{https}\PYG{p}{:}\PYG{o}{/}\PYG{o}{/}\PYG{n}{labfolder}\PYG{o}{.}\PYG{n}{rz}\PYG{o}{\PYGZhy{}}\PYG{n}{berlin}\PYG{o}{.}\PYG{n}{mpg}\PYG{o}{.}\PYG{n}{de}\PYG{o}{/}
\PYG{o}{\PYGZlt{}}\PYG{o}{/}\PYG{n}{VirtualHost}\PYG{o}{\PYGZgt{}}

\PYG{o}{\PYGZlt{}}\PYG{n}{VirtualHost} \PYG{o}{*}\PYG{p}{:}\PYG{l+m+mi}{443}\PYG{o}{\PYGZgt{}}
    \PYG{n}{ErrorLog} \PYG{o}{/}\PYG{n}{var}\PYG{o}{/}\PYG{n}{log}\PYG{o}{/}\PYG{n}{apache2}\PYG{o}{/}\PYG{n}{error}\PYG{o}{.}\PYG{n}{log}
    \PYG{n}{LogLevel} \PYG{n}{warn}

    \PYG{n}{ServerName} \PYG{n}{labfolder}\PYG{o}{.}\PYG{n}{rz}\PYG{o}{\PYGZhy{}}\PYG{n}{berlin}\PYG{o}{.}\PYG{n}{mpg}\PYG{o}{.}\PYG{n}{de}

    \PYG{n}{SSLEngine} \PYG{n}{On}
    \PYG{n}{SSLCertificateFile} \PYG{o}{/}\PYG{n}{etc}\PYG{o}{/}\PYG{n}{letsencrypt}\PYG{o}{/}\PYG{n}{live}\PYG{o}{/}\PYG{n}{labfolder}\PYG{o}{.}\PYG{n}{rz}\PYG{o}{\PYGZhy{}}\PYG{n}{berlin}\PYG{o}{.}\PYG{n}{mpg}\PYG{o}{.}\PYG{n}{de}\PYG{o}{/}\PYG{n}{fullchain}\PYG{o}{.}\PYG{n}{pem}
    \PYG{n}{SSLCertificateKeyFile} \PYG{o}{/}\PYG{n}{etc}\PYG{o}{/}\PYG{n}{letsencrypt}\PYG{o}{/}\PYG{n}{live}\PYG{o}{/}\PYG{n}{labfolder}\PYG{o}{.}\PYG{n}{rz}\PYG{o}{\PYGZhy{}}\PYG{n}{berlin}\PYG{o}{.}\PYG{n}{mpg}\PYG{o}{.}\PYG{n}{de}\PYG{o}{/}\PYG{n}{privkey}\PYG{o}{.}\PYG{n}{pem}

    \PYG{n}{ProxyPass} \PYG{o}{/} \PYG{n}{http}\PYG{p}{:}\PYG{o}{/}\PYG{o}{/}\PYG{l+m+mf}{141.14}\PYG{o}{.}\PYG{l+m+mf}{138.230}\PYG{p}{:}\PYG{l+m+mi}{9091}\PYG{o}{/}
    \PYG{n}{ProxyPassReverse} \PYG{o}{/} \PYG{n}{http}\PYG{p}{:}\PYG{o}{/}\PYG{o}{/}\PYG{l+m+mf}{141.14}\PYG{o}{.}\PYG{l+m+mf}{138.230}\PYG{p}{:}\PYG{l+m+mi}{9091}\PYG{o}{/}
\PYG{o}{\PYGZlt{}}\PYG{o}{/}\PYG{n}{VirtualHost}\PYG{o}{\PYGZgt{}}
\end{sphinxVerbatim}


\chapter{Groups, ownership and sharing in labfolder}
\label{\detokenize{groups:groups-ownership-and-sharing-in-labfolder}}\label{\detokenize{groups::doc}}
As labfolder user you can create groups (ultimately: group projects) and private projects. In \sphinxstyleemphasis{Manage \textgreater{} Projects} you see all projects that you own and that you are a member of.


\section{Private projects}
\label{\detokenize{groups:private-projects}}
You alone are the owner of these projects in \sphinxstyleemphasis{My Private Projects}. Their ownership cannot be transfered from you to anyone else via the webinterface. Only via directly manipulating the database the ownership can be changed to an active user.

\noindent{\hspace*{\fill}\sphinxincludegraphics[width=0.700\linewidth]{{private_projects}.png}\hspace*{\fill}}


\section{Group projects}
\label{\detokenize{groups:group-projects}}
Any labfolder user can create groups and subgroups in \sphinxstyleemphasis{Manage \textgreater{} Groups \textgreater{} Button “+Add”}. Within (sub)groups you can create group projects of which you are the administrator (admin). In the role of the admin you can do the following:
\begin{itemize}
\item {} 
invite users to your (sub)group via e-mail

\item {} 
move users between subgroups

\item {} 
set and remove (sub)group members as admins

\item {} 
remove users from a (sub)group e.g. when they are leaving the institute (\sphinxstylestrong{In this case the ownership of this user’s projects within the (sub)group needs to be transfered first!})

\item {} 
delete (sub)groups (before deleting it you need to remove all group members)

\end{itemize}


\section{Group settings}
\label{\detokenize{groups:group-settings}}
Administrators of groups (but not the ones of the subgroups) can edit the general settings of groups.

\noindent{\hspace*{\fill}\sphinxincludegraphics[width=0.700\linewidth]{{group_settings}.png}\hspace*{\fill}}
\begin{itemize}
\item {} 
Through the option \sphinxstyleemphasis{Prevent group members from deleting content} all users (including the admin) are prevented from deleting projects or any other data from the labfolder database. Projects will merely be hidden if a user decides to \sphinxstyleemphasis{Remove} it from their list of projects.

\item {} 
By checking the option \sphinxstyleemphasis{Prevent group members from having private projects}, group members will not be allowed to have private projects. All private projects of group members will be moved into the group projects, but will not be shared with any other group members.

\item {} 
By switching on \sphinxstyleemphasis{Users can be members of several subgroups}, users which are already members of a group can be invited again to another subgroup within the group. If switched to off members cannot be invited to subgroups of their current group.

\end{itemize}


\chapter{Import and export of projects and entries}
\label{\detokenize{import_export::doc}}\label{\detokenize{import_export:import-and-export-of-projects-and-entries}}

\section{Import}
\label{\detokenize{import_export:import}}
The import of projects (from another labfolder instance or from another logbook software) is only possible via the labfolder API. An import of labfolder-own projects via webinterface is not possible to date. You can find the API documentation here:

\begin{DUlineblock}{0em}
\item[] Version 1: \sphinxurl{http://labfolder.rz-berlin.mpg.de:9091/api/v1}
\item[] Version 2: \sphinxurl{https://labfolder.rz-berlin.mpg.de/api/v2/docs/development.html}
\end{DUlineblock}

Version 2 is still in the development phase.


\section{Export}
\label{\detokenize{import_export:export}}
Exporting projects (or just single entries) is possible in three different formats: PDF, XHTML and JSON. The export as PDF can be done from within a project …

\noindent{\hspace*{\fill}\sphinxincludegraphics[width=0.700\linewidth]{{export_of_projects}.png}\hspace*{\fill}}

… or from the project overview (\sphinxstyleemphasis{Manage \textgreater{} Projects}):

\noindent{\hspace*{\fill}\sphinxincludegraphics[width=0.700\linewidth]{{export_of_projects2}.png}\hspace*{\fill}}

The XHTML export can be done via the settings:

\noindent{\hspace*{\fill}\sphinxincludegraphics[width=0.700\linewidth]{{export_xhtml}.png}\hspace*{\fill}}

However, to use this type of export it has to be installed first in the \sphinxstyleemphasis{Manage \textgreater{} Apps} section. By means of the XHTML export all projects that one owns will be exported. A detailled selection of projects or entries to be exported is not possible. As soon as the export process is finished a download link appears in the settings in \sphinxstyleemphasis{Data exports}. The downloadable ZIP file contains all images and files along with an index.html file that contains information about all entries. You could open and view the index.html file in a browser similar to the view in labfolder.

The JSON export is only useable via the API endpoint \sphinxcode{GET /entries}. However, at the moment the response only contains useful information such as dates and tags. The author name is hidden behind the author ID and the entry text content is completely missing.


\chapter{Importing projects from e.g. the ELOGbook to Labfolder at the FHI}
\label{\detokenize{importing_from_elog:importing-projects-from-e-g-the-elogbook-to-labfolder-at-the-fhi}}\label{\detokenize{importing_from_elog::doc}}
The ELOG entries of a certain project need to be exported as \sphinxstyleemphasis{Raw} which looks like this:

\fvset{hllines={, ,}}%
\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYGZdl{}@MID@\PYGZdl{}: 12
Date: Tue, 03 Dec 2013 12:15:14 +0100
Author: Wieland SchÃ\P{}llkopf
Author Email: mailto:wschoell@fhi\PYGZhy{}berlin.mpg.de
Category: Shift summary
Subject: 1st solid\PYGZhy{}state experiment with FHI FEL
Severity: DOCU
Keywords:
Record date: 1386069171
Attachment:
Encoding: HTML
========================================
\PYGZlt{}p\PYGZgt{}Today Alex Paarmann and Marc Herzog are measuring in the wavelength range from 10 to 20 micron with a 0.5 mm thick GGG (Gadolinium Gallium Garnet, \PYGZlt{}a title=\PYGZdq{}Gadolinium\PYGZdq{} href=\PYGZdq{}http://en.wikipedia.org/wiki/Gadolinium\PYGZdq{}\PYGZgt{}Gd\PYGZlt{}/a\PYGZgt{}\PYGZlt{}sub\PYGZgt{}3\PYGZlt{}/sub\PYGZgt{}\PYGZlt{}a title=\PYGZdq{}Gallium\PYGZdq{} href=\PYGZdq{}http://en.wikipedia.org/wiki/Gallium\PYGZdq{}\PYGZgt{}Ga\PYGZlt{}/a\PYGZgt{}\PYGZlt{}sub\PYGZgt{}5\PYGZlt{}/sub\PYGZgt{}\PYGZlt{}a title=\PYGZdq{}Oxygen\PYGZdq{} href=\PYGZdq{}http://en.wikipedia.org/wiki/Oxygen\PYGZdq{}\PYGZgt{}O\PYGZlt{}/a\PYGZgt{}\PYGZlt{}sub\PYGZgt{}12\PYGZlt{}/sub\PYGZgt{}). Electron energy is set to 26 MeV.\PYGZlt{}/p\PYGZgt{}
\end{sphinxVerbatim}

This ASCII export looks like this in the ELOG webinterface:

\noindent{\hspace*{\fill}\sphinxincludegraphics[width=1.000\linewidth]{{elog_entry}.png}\hspace*{\fill}}

What is noticeable is that the ELOG export comes with a “Ã\P{}” instead of an “ö”. Interestingly, if only entries done by Wieland are exported the export file has UTF-8 encoding which can actually print German “Umlaute” (ö, ä, ü). If all entries are exported the encoding changes to an encoding that cannot handle e.g. “ö”.

After importing the above ELOG entry into labfolder this entry appears like that:

\noindent{\hspace*{\fill}\sphinxincludegraphics[width=1.000\linewidth]{{entry_after_import}.png}\hspace*{\fill}}



\renewcommand{\indexname}{Index}
\printindex
\end{document}