Merge branch '20250512-doc-install' into kusanagi

# Installation en production/pré-production

Cette documentation présente les étapes à suivre pour installer OSCAR sur une machine de production ou de pré-production.

## Configuration minimale

La première partie va se concentrer sur l'essentiel pour obtenir une instance d'OSCAR aux fonctionnalités minimales. La seconde partie proposera un exemple de configuration correspondant à ce qui est actuellement en usage à l'université de Caen et pouvant servir de base à la configuration métier d'un nouvel OSCAR. Enfin, la troisième partie renverra vers des documentations spécifiques en fonction des modules optionnels que l'on souhaite activer (par exemple LDAP, CAS, PCRU, Signature...).

### Installation du système d'exploitation

Dans cet exemple, le système d'exploitation utilisé est un serveur Debian en version stable 12 Bookworm, architecture x86_64. Toutefois il n'y a pas de contraintes fortes liées à l'utilisation de Debian ou de cette version en particulier ce qui signifie que l'installation devrait fonctionner aussi pour une version légèrement plus ancienne ou plus récente ainsi que pour un autre système Unix, en particulier pour Ubuntu qui est basé sur Debian.

```bash

cat /etc/debian_version

12.10

```

Mise à jour du système

```bash

apt update

apt full-upgrade

```

### Récupération du code source d'OSCAR

```bash

# Création du répertoire /var/OscarApp qui contiendra l'application

mkdir /var/OscarApp

cd /var/OscarApp

# Installation de Git pour récupérer le code source

apt install git

git clone --depth 1 https://git.unicaen.fr/open-source/oscar.git

```

Par défaut le code récupéré correspond à la branche git `master` qui contient la version stable la plus récente. Pour installer une version spécifique, il faut récupérer la branche voulue. Par exemple pour la branche/version kusanagi :

```bash

git clone -b kusanagi --single-branch --depth 1 https://git.unicaen.fr/open-source/oscar.git

```

### Installation de php 8.2

```bash

apt install php8.2-cli

php -v

PHP 8.2.28 (cli) (built: Mar 13 2025 18:21:38) (NTS)

Copyright (c) The PHP Group

Zend Engine v4.2.28, Copyright (c) Zend Technologies

    with Zend OPcache v8.2.28, Copyright (c), by Zend Technologies

```

### Dépendances PHP

*Oscar* utilise des librairies PHP tiers (vendor). Les librairies tiers sont gérées via [Composer](https://getcomposer.org/download/).

```bash

apt install composer

# Installation des modules php utilisés par les librairies

apt install php8.2-bcmath php8.2-curl php8.2-gd php8.2-ldap php8.2-xml php8.2-zip

# Installation des librairies dans le répertoire oscar/vendor

cd /var/OscarApp/oscar

COMPOSER_HOME=~/.composer COMPOSER_ALLOW_SUPERUSER=1 composer install --prefer-dist

```

> À cette étape, il devrait être possible de lancer la commande OSCAR qui liste les commandes disponibles.

```bash

php bin/oscar.php

```

### La commande check config

La commande `php bin/oscar.php check:config` permet de vérifier si une installation d'OSCAR est correctement configurée. Au fur et à mesure de ce guide d'installation nous pourrons régulièrement lancer cette commande pour vérifier où nous en sommes. C'est uniquement à la fin de ce guide que cette commande ne retournera plus de message d'erreur.

```bash

# Copie du fichier de configuration locale par défaut à partir du modèle

cp config/autoload/local.php.dist config/autoload/local.php

# Installation du module php client postgreSQL pour permettre à OSCAR de se connecter à la base de données

apt install php8.2-pgsql

```

> La commande check:config nous indique que la base de données n'est pas disponible, c'est la prochaine étape.

```bash

php bin/oscar.php check:config

```

### Installation de la base de données

Si vous souhaitez installer le serveur de base de données postgreSQL sur la même machine qu'OSCAR :

```bash

# Installation de postgresql

apt install postgresql

# Passage à l'utilisateur postgres

su postgres

# Connexion à la base de données

psql

# Affichage de la version installée (ici PostgreSQL 15.12)

postgres=# SELECT VERSION();

                                                       version                                                       

---------------------------------------------------------------------------------------------------------------------

 PostgreSQL 15.12 (Debian 15.12-0+deb12u2) on x86_64-pc-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit

```

Dans tous les cas, même si vous utilisez un serveur postgreSQL déjà existant, il faut créer un utilisateur pour OSCAR ainsi qu'une base de données sur laquelle cet utilisateur aura le droit de créer des tables, de lire, d'écrire et de supprimer des données.

```bash

# Création d'un utilisateur pour la connexion d'oscar (remplacer azerty par le mot de passe souhaité)

CREATE USER oscar WITH PASSWORD 'azerty';

CREATE DATABASE oscar OWNER oscar;

GRANT ALL PRIVILEGES ON DATABASE oscar to oscar;

\q

exit

```

> Il devrait maintenant être possible de se connecter à la base de données oscar avec l'utilisateur oscar.

```bash

psql -h localhost -U oscar -d oscar

Password for user oscar: 

psql (15.12 (Debian 15.12-0+deb12u2))

SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)

Type "help" for help.

oscar=> 

\q

```

Enfin, on peut alors mettre à jour la configuration de connexion à la base de données dans le fichier `config/autoload/local.php` (user, password, dbname etc).

```php

    // Accès BDDa

    'doctrine' => array(

        'connection' => array(

            'orm_default' => array(

                //////////////////////////////////////////////////////// DRIVERS

                // Postgresql

                'driverClass' => '\Doctrine\DBAL\Driver\PDO\PgSQL\Driver',

                ////////////////////////////////////////////////////////////////

                'doctrine_type_mappings' => array(

                    'enum' => 'string'

                ),

                ////////////////////////////////////////////////////// CONNEXION

                // Exemple

                'params' => array(

                    'host'     => 'localhost',

                    'port'     => '5432',

                    'user'     => 'oscar',

                    'password' => 'azerty',

                    'dbname'   => 'oscar',

                    'charset'  => 'utf8'

                ),

            ),

        ),

    ),

```

### Installation des modules php manquants

```bash

php bin/oscar.php check:config

```

La commande check:config nous indique que le module php bz2 est manquant, il faut l'installer.

```bash

apt install php8.2-bz2

```

### Installation du serveur web Apache2

Il ne reste plus qu'à installer un serveur web avec interpréteur PHP pour servir l'application. Dans cet exemple le serveur est Apache2.

```bash

# Installation d'apache2 et libapache2-mod-php8.2 :

apt install php8.2

# Pour voir la version d'Apache installée :

apachectl -V

Server version: Apache/2.4.62 (Debian)

```

### Création du fichier config/autoload/oscar-editable.yml

Ce fichier contiendra des paramètres de configuration qui peuvent être modifiés directement depuis l'interface web d'administration d'oscar. Il doit donc être accessible en modification pour l'utilisateur du serveur web (ici www-data).

```bash

touch config/autoload/oscar-editable.yml

chown www-data:www-data config/autoload/oscar-editable.yml

```

### Création du fichier logs/oscar.log

De même, le fichier de logs et le répertoire des logs doivent être accessibles en écriture pour le serveur web.

```bash

touch logs/oscar.log

chown -R www-data:www-data logs

```

### Création du schéma de la base de données

```bash

# Pour d'abord visualiser les commandes SQL qui seront réalisées :

php vendor/bin/doctrine-module orm:schema-tool:update --dump-sql --complete

# Puis pour créer la structure vide du schéma de la BDD :

php vendor/bin/doctrine-module orm:schema-tool:update --force --complete

```

### Ajout des privilèges

Cette commande permet d'insérer dans la base de données les différents privilèges qui conditionnent l'accès aux différentes fonctionnalités de l'application.

```bash

php bin/oscar.php check:privileges

# Il faut lancer une deuxième fois la commande pour être sûr que tous les privilèges ont bien été insérés

php bin/oscar.php check:privileges

```

### Configuration des emails

Dans le fichier `config/autoload/local.php`, il faut décommenter une configuration de `mailer` et configurer les différentes variables suivant le besoin. La variable `urlAbsolute` doit indiquer le nom de domaine sur lequel l'instance sera joignable, car elle est utilisée pour générer les liens vers OSCAR qui seront intégrés aux différents emails.

### OscarWorker (gearman) : Moteur de tâche 

Pour plus de détails, voir la documentation : [Installation de oscarworker](./configuration/config-gearman.md)

```bash

# Installation de gearman

apt install gearman-job-server

# Installation du module php de gearman

apt install php8.2-gearman

```

```bash

# on copie le gabarit de configuration du service

cp install/oscarworker.dist.service config/oscarworker.service

# On édite le service pour mettre le chemin complet vers bin/oscar-worker.php

# ExecStart = /usr/bin/php /var/OscarApp/oscar/bin/oscar-worker.php

vi config/oscarworker.service

# On va dans le dossier des service

cd /etc/systemd/system

# On ajoute la configuration du service dans SYSTEMD avec un lien symbolique

ln -s /var/OscarApp/oscar/config/oscarworker.service oscarworker.service

# On active le service

systemctl enable oscarworker.service

# On lance le service

service oscarworker start

```

### Configuration du LDAP

```bash

# Copier le fichier d'exemple de configuration

cp config/autoload/unicaen-app.local.php.dist config/autoload/unicaen-app.local.php

# Dans ce fichier, configurer le LDAP et remplacer les configurations d'emails par les bonnes valeur.

vi config/autoload/unicaen-app.local.php

```

### Configuration du serveur web

```bash

# Activation du modrewrite d'apache pour la réécriture des URLs

a2enmod rewrite

# Redémarrage du service apache2

systemctl restart apache2

# Copie de la configuration par défaut pour créer une configuration oscar

cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/oscar.conf

# Désactivation de la configuration apache par défaut

a2dissite 000-default

# Configuration du site oscar

vi /etc/apache2/sites-available/oscar.conf

# Par exemple :

#<VirtualHost *:80>

#        ServerAdmin admin@unicaen.fr

#        DocumentRoot /var/OscarApp/oscar/public

#

#        <Directory /var/OscarApp/oscar/public>

#                DirectoryIndex index.php

#                AllowOverride All

#                Order allow,deny

#                Allow from all

#                Require all granted

#        </Directory>

#

#        LogLevel debug

#        ErrorLog ${APACHE_LOG_DIR}/oscar-error.log

#        CustomLog ${APACHE_LOG_DIR}/oscar-access.log combined

# Activation du site d'oscar

a2ensite oscar

# Rechargement de la configuration d'apache

systemctl reload apache2

```

### Création d'un role application d'Administrateur

```sql

INSERT INTO user_role (id,parent_id,role_id,is_default,ldap_filter,spot,description,principal,accessible_exterieur,displayed) VALUES

	 (1,NULL,'Administrateur',false,NULL,4,NULL,false,true,true);

```

> À partir de cette étape, la page d'acceuil d'OSCAR devrait s'afficher sans erreur

### Création d'un compte local d'administrateur

```bash

# Cette commande permet créer localement en base de données un compte utilisateur. Renseignez le nom, email, login et mot de passe.

php bin/oscar.php auth:add

# Cette commande permet de donner un rôle à un utilisateur. Ajoutez le rôle Administrateur à votre utilisateur.

php bin/oscar.php auth:promote

```

Il faut à présent exécuter un script en base de données qui va donner tous les droits au rôle Administrateur :

```sql

insert into role_privilege

select id, (select ur.id from user_role ur where ur.role_id = 'Administrateur') from privilege;

```

> À cette étape, il devrait être possible de se connecter avec un compte administrateur ayant tous les droits dans OSCAR. On peut alors accéder au menu Administration > Configuration et maintenance > Maintenance > Vérification de la configuration qui affiche des informations concernant la configuration similaires à celles de la commande `php bin/oscar.php check:config`

### Rendre le répertoire data accessible en lecture/écriture au serveur web

```bash

chown -R www-data:www-data data

```

Mais aussi le template de mail :

```bash

chown -R www-data:www-data module/Oscar/view/mail.phtml

```

### Installation d'Elasticsearch en version 7

Suivons la documentation officielle d'Elastic :

https://www.elastic.co/docs/deploy-manage/deploy/self-managed/install-elasticsearch-with-debian-package

```bash

apt install gpg wget apt-transport-https

wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | gpg --dearmor -o /usr/share/keyrings/elasticsearch-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main" | tee /etc/apt/sources.list.d/elastic-7.x.list

apt update

apt install elasticsearch

systemctl daemon-reload

systemctl enable elasticsearch.service

systemctl start elasticsearch.service

```

Si besoin, réduire la mémoire utilisée dans `/etc/elasticsearch/jvm.options` (`-Xms1g -Xmx1g`)

On peut à présent vérifier qu'Elastic répond bien : `curl localhost:9200`

> À partir de cette étape, toutes les vérifications doivent être OK (commande `php bin/oscar.php check:config` et sur l'interface d'administration).

## Configuration spécifique

La première partie de cette documentation a permis de réaliser l'installation minimale de la partie technique d'OSCAR. Il reste à présent à réaliser la configuration métier (création de types d'utilisateurs, attribution des rôles etc). Pour vous faciliter la mise en place, cette partie propose à titre d'exemple la configuration actuellement en usage à l'université de Caen. À vous ensuite d'adapter selon vos besoins en ajoutant/modifiant/retirant certaines valeurs.

### Ajout des devises et des taux de TVA

```sql

INSERT INTO currency (id,status,datecreated,"label",symbol,rate) VALUES

	 (1,1,NOW(),'Euro','€',1.0),

     (2,1,NOW(),'Dollars','$',1.096),

     (3,1,NOW(),'Livre','£',0.7133),

	 (4,1,NOW(),'Yens','¥',132.651);

INSERT INTO tva (id,"label",rate,active,status) VALUES

	 (1,'Exonéré',0.0,true,1),

	 (2,'Taux réduit (5,5%)',5.5,true,1),

	 (3,'Taux normal (19,6%)',19.6,true,1),

	 (4,'Taux DOM-TOM',8.5,true,1),

	 (5,'Taux réduit 7%',7.0,true,1),

	 (6,'Taux normal 20%',20.0,true,1),

	 (7,'Taux réduit 10%',10.0,true,1);

```

### Configuration UNICAEN

Le script `install-prod-2025-05-07.sql` permet de créer :

 - 31 rôles (Responsable scientifique, Chercheur...)

 - les privilèges associés aux différents rôles (par exemple, le Chargé de valorisation a le droit de créer un Activité etc)

 - 161 types d'activité (par exemple ANR, Financement International hors UE...)