How to install DigiCleaR 4

this guide is still under construction.

In order to function properly, DigiCleaR4 needs 3 things :

• A web server :
  DigiCleaR is a web based software, and thus needs to be served like a website. In this guide we will use NGINX, but any other web server (e.g. Apache) can be used as long as it's properly configured.
• PHP 8.1 or higher :
  Digiclear is made in php and needs do be processed by php-cgi. On most Linux distributions php is natively installed but you might need to enable a few extensions. If you're using Windows you will have to manually install php (and its dependencies).
• A PostgreSQL database server (version > 10) :
  DigiCleaR needs PostgreSQL to store its data. PostgreSQL is a database server like MySQL, you will need to install it and create an user and the database structure for DigiCleaR.
• For simple installation you can use a ubuntu server distribution. Digiclear installation has been tested up to ubuntu server 22.04 (in august 2023)

http://php.net/session.gc-maxlifetime

Install nginx with :

sudo apt install nginx

you will have to configure it.

Download and install nginx for windows.

You can check that NGINXis running by checking if it is currently listening to its default port 80. You can see which process is listening to which port in the network tab of the ressources monitor (can be opened in the performance tab of the task manager), or by typing the command netstat -a -b in an admin cmd.

Install PHP with php-curl and pdo for postgresql.

sudo apt install php8.1-bcmath php8.1-bz2 php8.1-cgi php8.1-cli php8.1-curl php8.1-gd  php8.1-gmagick php8.1-gmp php8.1-http php8.1-ldap php8.1-mbstring php8.1-pgsql php8.1-phpdbg php8.1-readline php8.1-ldap php8.1-ssh2 php8.1-zip php8.1-xml php8.1-xdebug 

sudo service php8.1-fpm restart

Depending on the version of PHP you are installing you have to check the configuration file of NGINX and especially the following line

location ~ .php$ {
                fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;   # HERE you must adjust the version of PHP to the one running on the server
                fastcgi_index index.php;
                include /etc/nginx/fastcgi_params;
                fastcgi_param SCRIPT_FILENAME $document_root/$fastcgi_script_name;
              }

~$ php --version
PHP 8.1.2-1ubuntu2.13 (cli) (built: Jun 28 2023 14:01:49) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.2, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.2-1ubuntu2.13, Copyright (c), by Zend Technologies
    with Xdebug v3.1.2, Copyright (c) 2002-2021, by Derick Rethans

Download PHP for windows.

Note that PHP 7.X for windows require Microsoft Visual C++ 2019

You can check that php is running by checking if php-cgi is currently listening to its default port 9000. You can see which process is listening to which port in the network tab of the ressources monitor (can be opened in the performance tab of the task manager), or by typing the command netstat -a -b in an admin cmd.

In the php.ini there is a line for the maximum lifetime of a session and the default value is 1440s It is wise to use this feature but after feedback from user it seems that this time is not enough depending on the machine they are using.
We have set it up to 14400s

; After this number of seconds, stored data will be seen as 'garbage' and
; cleaned up by the garbage collection process.
; http://php.net/session.gc-maxlifetime
session.gc_maxlifetime = 14400

Change also some parameters to allow big files to be downloaded

post_max_size = 20M
upload_max_filesize = 20M

Install postgresql with :

sudo apt install postgresql

Once postgresql is installed, you should have a standard admin postgres account, switch to it :

sudo -i -u postgres

create an new user for DigiCleaR :

createuser --interactive --pwprompt

give this new user the rights to create databases and the rights to login. (don't put him superuser, it's unnecessary)

Create a new database

sudo -i -u postgres
psql
postgres=# CREATE DATABASE digiclear;

Give access to the database for specific user

configuration of the file /etc/postgresql/12/main/pg_hba.conf

# Database administrative login by Unix domain socket
local   all             postgres                                peer

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     md5
# IPv4 local connections:
host    all             all             127.0.0.1/32            md5
host    all             all             your.IP.Address.remote/32          md5
# IPv6 local connections:
host    all             all             ::1/128                 md5
# Allow replication connections from localhost, by a user with the
# replication privilege.
local   replication     all                                     peer
host    replication     all             127.0.0.1/32            md5
host    replication     all             ::1/128                 md5

and configuration of the /etc/postgresql/12/main/postgresql.conf

listen_addresses = '*'

RESTART the server POSTGRESQL

sudo service postgresql restart

Once the database is created you have to setup the rights for the administrator of the database, use the postgres user to set it up:

sudo@server~$ sudo su -i -u postgres
postgres@server:~$ psql

CREATE USER digiclear WITH PASSWORD 'your-DigiCleaR-password';

CREATE DATABASE digiclear_db;

ALTER DATABASE digiclear_db OWNER TO digiclear;

GRANT ALL PRIVILEGES ON DATABASE digiclear_db TO digiclear;

Install the PostgreSQL server for windows.

You can check that postgresql is running by checking if it is currently listening to its default port 5432. You can see which process is listening to which port in the network tab of the ressources monitor (can be opened in the performance tab of the task manager), or by typing the command netstat -a -b in an admin cmd.

Once PostgreSQL is installed, you will have to create both an user and a database for DigiCleaR. You can either do this from a database tool like pgAdmin4 or DBeaver, or use psql as described below from a cmd terminal or powershell.

Open psql with psql -U postgres -d postgres. This will open the default database postgres with the default admin user postgres. You will have to enter the password for the postgres user, which is also postgres by default unless you were asked to set it in the installation setup.

Once you are in the psql query prompt, enter the following lines :

CREATE USER digiclear WITH PASSWORD 'your-DigiCleaR-password' ;

CREATE DATABASE digiclear_db;

ALTER DATABASE digiclear_db OWNER TO digiclear;

GRANT ALL PRIVILEGES ON DATABASE digiclear_db TO digiclear;

This will create a new user named digiclear and a new database named digiclear_db. You will have to enter the user name, the user password and the database name in the config.ini file of your DigiCleaR installation.

Currently DigiCleaR is able to instantiate the database structure by itself, but if you want to, you can “restore” a backup of a clean DigiCleaR database.

the -h option is to specify the host of the database (here is digiclear aka digiclear.c2n.u-psud.fr).

psql -h digiclear -f [path to the DUMP file] [Database name] -U [username(= digiclear)]

This step is necessary if you're cloning directly from the git. If you have a copy of DigiCleaR, you should already have the php dependencies.

Install Composer if you don't have it.

To install from the git, you use the clone method

sudo git clone https://gitlab.com/stephane.guilet/digiclear4.git

Move to the new directory and then run the composer script to install all the required libraries.

sudo composer install

Open config.ini in /config/, and modify the fields according to your preferences. You must set pgsql username and password to the postgresql user you created.

This is the default config.ini :

;*********************************************************************
;This file is part of the DigiCleaR project
;Copyright (c) 2020-2023, CNRS - C2N
;
;Authors :
;Léandre Elmestour
;Stéphane Guilet
;
;License :
;GNU GPL version 3 or any later version
;
;This program is free software: you can redistribute it and/or modify
;it under the terms of the GNU General Public License as published by
;the Free Software Foundation, either version 3 of the License, or
;(at your option) any later version.
;
;This program is distributed in the hope that it will be useful,
;but WITHOUT ANY WARRANTY; without even the implied warranty of
;MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;GNU General Public License for more details.
;
;You should have received a copy of the GNU General Public License
;along with this program. If not, see <https://www.gnu.org/licenses/>.
;*********************************************************************

[Settings]
;Path of the DigiCleaR installation folder, leave empty or null to resolve it automatically.
path = null

;Display php errors on screen :
;It's recommended to switch this off in production, as errors can contain confidential data and informations that could help potential attackers
display_errors = true ;false

;Log php errors : 
log_errors = true

;Authentication method.
;CAS : DigiCleaR will use the specified CAS service to authenticate its users
;LDAP : DigiCleaR will use the specified LDAP server to authenticate its users
;demo : DigiCleaR will always connect as the specified user. This is for demonstration/testing purposes only.
authentication = demo

;Login used for the first admin created during the installation :
;If you use a CAS you must make sure this will match your CAS login (or you will have to manually change it in the database)
first_admin = "admin"

;File storage method :
;nextcloud : use a nextcloud server to store the files (and share them with the users if they have the same login)
;local : store the files locally (in /files/local) NOT IMPLEMENTED
;none : no file upload (parameters will be hidden)
store = nextcloud

;messaging method :
;email : use the email address of users to send messages, from one user to another or from digiclear's systems like the booking
;none : no messaging
messaging = email


;Upload packet size (use a value under the maximum request size configured in nginx/apache/etc) :
upload_chunk_size = 10485760 ;default 10485760 (10MB)

;Switch to true to use Vite's dev mode. You can start it with npm run dev (Node.js must be installed on your machine)
dev_mode = false

;Vite dev server url (only needed when using dev mode)
dev_host = "http://localhost:5133"

[Renatech API]
;url of the project import api
renatech_project_url = "https://repotech-api.iemn.fr/project_c2n"

;url of the project by user api
renatech_project_by_user_url = "https://repotech-api.iemn.fr/projets_by_utilisateur_c2n"

;authentication token
renatech_token = "**********************************************************************************"

;Absolute path to the certificate file (iemn-fr-chain.pem) if using https (recommended).
renatech_certificate = "/where/is/the/certificate/certif.pem"

;set to true to disable certificate validation (NOT RECOMMENDED FOR PRODUCTION)
renatech_ignore_certificate = false

[PostGreSQL]
;Address of the pgSQL server :
host = "localhost"

;Port used :
port = 5432

;Name of the database :
database = "digiclear_c2n"; "digiclear_booking_dev"; 

;Name of the pgSQL user :
db_user = "digiclear"

;password of the pgSQL user :
db_password = "**********"

[Auth CAS]
;CAS version
cas_version = "3.0"

;Full Hostname of your CAS Server
cas_host = "sso.u-psud.fr"

;Context of the CAS Server
cas_context = "/cas"

;Port of your CAS server. Normally for a https server it's 443
cas_port = 443

;ldap attribute containing the full name of the user (if left empty the login will be used instead)
full_name_attribute = 'cn'

;ldap attribute containing the mail adress of the user (can be left empty)
mail_attribute = 'mail'

[Auth LDAP]
;LDAP URI: url and port of the ldap server "ldap://ldap.example.com:389"
ldap_uri = "ldap://ldap.forumsys.com:389"

;LDAP DN, 'username' will be replaced with the user's login.
;If you don't know the users dn pattern, leave this empty and use the two fields below (main_dn, main_password) to let digiclear search for it
ldap_dn = "uid=username,dc=example,dc=com"

;These should be the dn and password of a user capable of reading the ldap.
;If ldap_dn is empty this will be used to search the dn of the user trying to login
main_dn = "cn=read-only-admin,dc=example,dc=com"
main_password = "**********"

;dn used to search the user. This will be combined with login_attribute to match the user
search_dn = "dc=example,dc=com"

;field used to search the user. This corresponds to what the users will type in the login form.
login_attribute = "uid"

;ldap attribute containing the full name of the user (if left empty the login will be used instead)
full_name_attribute = 'cn'

;ldap attribute containing the mail adress of the user (can be left empty)
mail_attribute = 'mail'



[Auth demo]
;ID of the user that will be logged in
user_id = 163

[Store nextcloud]
;Name of the cloud used in the menu tabs. Leave empty to remove the link from the tabs
nextcloud_name = "ClearCloud"

;URL of the nextcloud (it is strongly advised to use https, or the passwords will be sent in clear over the network)
nextcloud_url = "https://129.175.134.84";"http://clearcloud"

;Absolute path to the certificate file of the cloud if using https (recommended).
nextcloud_certificate = "/mnt/d/Documents/DigiCleaR/clearwiki-c2n-u-psud-fr.pem"

;set to true to disable certificate validation (NOT RECOMMENDED FOR PRODUCTION)
nextcloud_ignore_certificate = true

;Account used by DigiCleaR. Should be a standard user specifically made for this software. Beware of the size limit.
nextcloud_user = "DigiCleaR"

;Password of the account
nextcloud_password ="**********"

;URL of the webdav endpoints
nextcloud_dav = "/remote.php/webdav/"

;URL of the ocs endpoints
nextcloud_ocs = "/ocs/v2.php/apps/files_sharing/api/v1/"

;Folder where all the operation associated files will be stored
nextcloud_folder = "operation_files"

;Folder shared with the users
nextcloud_user_folder = "Digiclear Machines"

[Email Messaging]
;SMTP server address
email_host = "172.28.144.1"

;SMTP server port
email_port = 1025

;SMTP encryption method
;---
;---
;none or empty : unencrypted
email_encryption =

;SMTP server username
email_username =

;SMTP server password
email_password = 

;email address used by DigiCleaR
email_address = 'DigiCleaR@example.com'

;name used by DigiCleaR
email_name = 'DigiCleaR'