ekyc

Electronic KYC process with uploading ID document using OAuth 2.1 (experimental)
Log | Files | Refs | README | LICENSE

appendix-user-manual.tex (6064B)

      1 \chapter{User Manual}
      2 
      3 \section{Requirement}\label{software-requirement}
      4 
      5 The following software is required for the deployment of KYCID:
      6 \begin{table}[H]
      7     \centering
      8     \setupBfhTabular
      9     \begin{tabular}{lll}
     10     \rowcolor{BFH-tablehead}
     11     \textbf{Dependencies}&\textbf{Version}&\textbf{Comment}\\\hline
     12     Deno&>= 1.43&KYCID Runtime environement\\\hline
     13     Postgres&compatible with 15&database\\\hline
     14     Tesseract&compatible with 5.3&OCR Engine for Card or Passport Scanning\\\hline
     15     Nix&any with flake feature&Environement manager, optional\\\hline 
     16     Mailcatcher&any&fake SMTP server with webUI, only for dev\\\hline
     17     TexLive&with BFH template&only for compiling documentation
     18     \end{tabular}
     19     \caption{KYCID Software Dependencies}
     20 \end{table}
     21 
     22 It is possible to install these dependencies independently, in accordance with the usual installation procedure. In this case, it is not necessary to install Nix. Alternatively, the guide below provides instructions on how to install Nix and use it to set up the environment.
     23 
     24 \section{Nix setup}
     25 
     26 Nix is a packet manager \cite{NIX}, which allows the user to create immutable and reproducible builds.
     27 \begin{bfhWarnBox}
     28 It is important to note that Nix, as a packet manager, is distinct from NixOS, a Linux distribution that employs Nix as a general packet manager.
     29 \end{bfhWarnBox}
     30 
     31 To install nix you can just run install with following command:
     32 \captionof{lstlisting}{Multi-user nix install on Linux}
     33 \setupLinuxPrompt{student}
     34 \begin{ubuntu}
     35 sh <(curl -L https://nixos.org/nix/install) --daemon
     36 \end{ubuntu}
     37 
     38 The installer will run interactively and pose a series of questions. Once the installation process is complete, it is necessary to restart the terminal.
     39 If the user is using a Mac, the following command should be executed:
     40 \captionof{lstlisting}{Nix install on MacOS}
     41 \setupOSXPrompt{student}
     42 \begin{macos}
     43 sh <(curl -L https://nixos.org/nix/install)
     44 \end{macos}
     45 
     46 In addition, should you wish to avoid installing the Nix system for all users, you may opt to install it in single user mode via the following command:
     47 \captionof{lstlisting}{Single-user nix install on Linux}
     48 \setupLinuxPrompt{student}
     49 \begin{ubuntu}
     50 sh <(curl -L https://nixos.org/nix/install) --no-daemon
     51 \end{ubuntu}
     52 
     53 It should be noted that, in order to utilise the Flake feature, which has been designated as experimental, it is necessary to perform the requisite activation procedure.
     54 \begin{bfhNoteBox}
     55 Despite the note on the flake functionality as experimental, this is not the case. It is a significant change, and the features are named as such for the sake of Nix retro-compatibility. The functionality is widely stable and used.
     56 \end{bfhNoteBox}
     57 
     58 Run the following command to enabled NIX Flake feature (the same on Linux and MacOS):
     59 \captionof{lstlisting}{Enabled Nix Flake feature}
     60 \setupOSXPrompt{student}
     61 \begin{macos}
     62 mkdir -p ~/.config/nix # to be sure that folder exists
     63 echo 'experimental-features = nix-command flakes' > ~/.config/nix/nix.conf
     64 \end{macos}
     65 
     66 \section{Environment setup}
     67 
     68 
     69 
     70 To set up the environment for execution, simply install the various dependencies listed in the software requirement section.
     71 With NIX, the following command will suffice:
     72 \captionof{lstlisting}{Disposable dev environment shell}
     73 \setupOSXPrompt{student}
     74 \begin{macos}
     75 cd /path/to/projet
     76 nix develop
     77 
     78 # without TexLive
     79 nix shell .#deno .#tesseract .#postgresql .#mailcatcher
     80 \end{macos}
     81 
     82 This command will start a shell in which the dependencies will be available. This will ensure that they do not conflict with the rest of the system. Once the shell is closed, the applications will still be stored in the Nix cache, but they will not be accessible in the PATH.
     83 
     84 \begin{bfhWarnBox}
     85 Please note that this shell will have ALL the dependencies, including those used only in development such as TexLive (> 4GB), Mailcatcher or Postgres (as long as you already have a Postgres server elsewhere).
     86 \end{bfhWarnBox}
     87 
     88 \begin{bfhNoteBox}
     89 Please be aware that only the binaries and the library are installed, and no configuration file will be generated on your system or any daemon started.
     90 \end{bfhNoteBox}
     91 
     92 In order to install only the dependencies in production, the following commands must be executed:
     93 \setupOSXPrompt{student}
     94 \begin{macos}
     95 cd /path/to/projet
     96 ## Global install on system
     97 nix profile install ".#deno" ".#tesseract" ".#postgresql"
     98 ## Local install on current shell
     99 nix shell ".#deno" ".#tesseract" ".#postgresql"
    100 \end{macos}
    101 \captionof{lstlisting}{Production environment install}
    102 
    103 \section{Configuration}\label{configuration}
    104 
    105 The configuration of all elements takes place via environment variables. It is possible to log these variables in a file with the extension \texttt{.env}.
    106 \lstinputlisting[
    107     language=bash,
    108     caption={All Environment Variable and \texttt{.env.sample}}
    109 ]{../../.env.sample}
    110 
    111 \section{Postgres}
    112 
    113 \setupOSXPrompt{student}
    114 \begin{macos}
    115 initdb -D pgdata # pgdata is path to a folder that hold server files
    116 postgres -D $PWD/pgdata --listen_addresses='127.0.0.1' &
    117 export PGHOST=127.0.0.1
    118 export PGUSER=<your user>
    119 export PGDATABASE=<database name>
    120 export PGAPPNAME=kycid
    121 createdb $PGDATABASE
    122 cd /path/to/project
    123 deno task nessie migrate # to run migration
    124 \end{macos}
    125 \captionof{lstlisting}{Setup local postgres server} 
    126 
    127 \section{SMTP}
    128 
    129 \setupOSXPrompt{student}
    130 \begin{macos}
    131 mailcatcher --ip 127.0.0.1 --smtp-port 1025 --http-port 1080 --foreground
    132 \end{macos}
    133 \captionof{lstlisting}{Fake SMTP Server for developpment} 
    134 
    135 \begin{bfhNoteBox}
    136 Access to the email messages sent via this fake SMTP server is available via a web interface at the following address: \texttt{http://127.0.0.1:1080}.
    137 \end{bfhNoteBox}
    138 
    139 \section{Usage}
    140 
    141 \setupOSXPrompt{student}
    142 \begin{macos}
    143 # MIGRATE POSTGRES SCHEMA
    144 deno task nessie migrate
    145 
    146 # RUN DEV SERVER (AUTO RELOAD ON FILE CHANGE)
    147 deno task dev
    148 
    149 # RUN PRODUCTION SERVER
    150 deno run --allow-all src/http/main.ts
    151 
    152 # COMPILE LaTeX thesis (only on dev env)
    153 cd docs
    154 bfhlatex thesis
    155 \end{macos}
    156 \captionof{lstlisting}{Usage command cheatsheet}