« Installation sur Linux - v4 » et « Usage des scripts - v4 » : différence entre les pages

De Documentation e-comBox
(Différence entre les pages)
 
 
Ligne 1 : Ligne 1 :
{{note|De nombreux scripts pour gérer l'application sont fournis dans les '''versions 4.1 et 4.2'''. Une brève description pour chacun d'entre eux est donné ci-dessous.|reminder}}


{{note | La '''version 4.1''' est sortie avec [https://gitlab.com/e-combox/e-combox_webapp/-/blob/4.1.0/CHANGELOG.md lot de nouveauté]. C'est celle-ci qu'il faut installer et n'hésitez pas à migrer si vous utilisez une version plus ancienne. | reminder}}
{{Note/fr|type=warn|Il est rappelé qu'à partir de la version des scripts 4.1.1 (20/04/2023), tous les "B" majuscule dans les noms de dossier basculent en "b" minuscule, ainsi le dossier d'installation /opt/e-comBox devient /opt/e-combox. C'est ce dernier chemin qui est utilisé ici. Si vous avez une version plus ancienne, le dossier d'installation est /opt/e-comBox.}}


== Préalables ==
== Gestion des certificats : manage_certificats.sh ==


Les scripts utilisés sont disponibles sur gitlab : [https://gitlab.com/e-combox/e-comBox_scriptsLinux/-/tree/4.1 https://gitlab.com/e-combox/e-comBox_scriptsLinux].
{{note | Ce script permet la création et la mise à jour du certificat pour l'accès à l'interface de l'e-comBox et l'ajout de certificats pour Portainer. Des options doivent être passées en ligne de commande (voir Usage ci-après).}}                                                                                   
<pre>
Usage: bash /opt/e-combox/manage_certificats.sh -c|u [-m "valeur"] [-a] [-h]
  -c Création et mise en place d'un certificat Lets'encrypt
  -u Mise à jour du certificat à partir des paramètres du fichier param.conf
  -m Adresse de courriel  [-m "adresse courriel"], non obligatoire
  -a Installation de la mise à jour automatique du certificat lorsque celui-ci est expiré. Cette option n'a d'utilité qu'une seule fois
  -p    Ajout d'un certificat au format PEM dans Portainer
  -h Détail des options
</pre>
'''L'option "-c"''' automatise la création et l'installation d'un certificat Let's Encrypt directement utilisable pour l'application.


{{note | Les scripts ont été testés sur les versions Linux (obligatoirement 64 bits) suivantes :
{{note|Votre instance doit être joignable sur le port 80.  Attention, vous n'avez pas à installer de serveur Web, le script se charge de tout. L'instance doit juste être en mesure de répondre à une requête de type http://votre_nom_de_domaine (où le nom de domaine est la valeur renseigné dans la paramètre DOMAINE de param.conf). Une redirection peut donc être nécessaire.|warn}}
* Ubuntu (à partir la version 18.04) ;
* Debian 9 ;
* Debian 10 ;
* Debian 11 (actuellement stable). | reminder}}


{{Note | Vous pouvez installer une ou plusieurs instances de l'e-comBox derrière un Reverse Proxy externe. Pour configurer ce dernier, consultez le "[https://gitlab.com/e-combox/e-comBox_scriptsLinux/-/blob/v4/README.md readme]" sur Gitlab.|warn}}
'''Le script :'''
* crée le certificat en utilisant le paramètre "DOMAINE" du param.conf et de manière optionnelle le paramètre MAIL (qui peut être soit renseigné dans param.conf soit directement ajouté via l'option "-m" de la ligne de commande) ;
* copie les fichiers dans /opt/e-combox/letsencrypt/live/<domaine> ;
* renseigne les paramètres correspondants de param.conf :
** CHEMIN_CERT="/opt/e-combox/letsencrypt/live/<domaine>/fullchain.pem"
** CHEMIN_KEY="/opt/e-combox/letsencrypt/live/<domaine>/privkey.pem"
** MAIL (si un mail est passé en ligne de commande) ;
* installe le certificat au niveau de l'application.


{{Note | L'exécution des scripts doivent se faire en '''administrateur''' qui est "root" sur Linux (ou en utilisant la commande sudo).|error}}
'''L'option "-a"''' (que l'on peut activer ultérieurement) met en place une tâche automatique qui vérifie quotidiennement si le certificat a expiré et le met à jour le cas échéant.


{| class="wikitable"
'''L'option "-u"''' :
|-
! '''Préalable, en cas de proxy pour curl et git'''
|-
|Définition des variables d'environnement nécessaires à l'exécution de commandes curl via un proxy :
* <span class="c2">export http_proxy="&lt;IPproxy&gt;:&lt;port&gt;"</span>
* <span class="c2">export https_proxy=$http_proxy</span>
|}


À noter également que si l'installation de Docker ne le fait pas le script de configuration crée le dossier "$USER/.docker" et le fichier /$USER/.docker/config.json".
* met à jour le certificat de l'e-comBox si des valeurs à CHEMIN_CERT et à CHEMIN_KEY sont modifiées, ajoutées ou supprimées ;
* met à jour le certificat de l'e-comBox (si ce type de certificat auto-signé est utilisé) mais aussi d'autres certificats nécessaires qui s'appuient sur les variables CODE_PAYS, NOM_PAYS, NOM_REGION, NOM_ORGANISATION. Ainsi, si au moins une de ces 4 paramètres sont modifiés, il est nécessaire de mettre à jour les certificats.


== Installation de la version 4.1 ==
'''L'option "-p"''' ajoute, si besoin, un certificat (donné en option) sur Portainer.


=== Principe de fonctionnement ===
== Réinitialisation de l'application : reinitialise_application.sh ==
Il s'agit d'une installation automatique. Le script installe l'e-comBox à partir du fichier  /opt/e-comBox/param.conf (qui a été enrichi de nouveaux paramètres) sans interaction avec l'utilisateur.
{{note|Ce script permet de réinitialiser l'application.  Des options doivent être passées en ligne de commande (voir Usage ci-après).|}}{{Note/fr|type=error|Attention, tous les sites seront perdus.}}<pre>
Usage: bash /opt/e-combox/reinitialise_application.sh -a -f [-n] [-v "valeur"] [-i "valeur"] [-d "valeur"] [-r "valeur"] [-c "valeur"] [-p "valeur"] [-h]
  -a Suppression de tous les conteneurs, volumes, réseaux et images.
  -f    Force la suppression même si l'accès à Portainer n'est plus possible.
  -n Réinstallation de l'application.
  -v Version de l'application à installer si vous voulez changer de version [-v "version"].
  -i Adresse IP privée nom de domaine correspondant à une adresse IP privée  [-i "@IP_PRIVEE" | -i "nom_domaine"].
  -d Adresse IP publique nom de domaine correspondant à une adresse IP publique  [-d "@IP_PUBLIQUE" | -d "nom_domaine"].
        Pour supprimer une valeur existante -d "".
  -r Passage par un Reverse-Proxy externe ou non  [-r "O" | -r "N"].
  -c Chemin en cas de Reverse-Proxy externe [-c "chemin"].
        Pour supprimer un chemin existant -c "".
  -p Mot de passe de Portainer [-p "mot_de_passe"].
        Les caractères suivants " $ ` \ & | ! [space] ne peuvent pas être utilisés en ligne de commande
  -h Détail des options.
</pre>


Le fichier /opt/e-comBox/param.conf sera automatiquement rempli avec les éléments passés en ligne de commande ou avec un fichier /opt/e-comBox/param.conf existant (éventuellement issu d'une ancienne version). Si ce dernier n'existe pas déjà il sera créé.
'''L'option "-a"''' est obligatoire, elle force la suppression des conteneurs, volumes, réseaux et images.
'''L'option "-f"''' peut être utilisée si l'accès à Portainer n'est plus possible.


{{note|Les scripts install_linux_e-combox.sh et configure_application.sh peuvent être exécutés en mettant en paramètre un fichier contenant les paramètres que l'on veut modifier ou passer directement (avec des options) les paramètres sur le ligne de commande.<br>
L'ajout de '''l'option "-n"''' permet de réinstaller l'application en changeant éventuellement la version via l'option "-v".


Cela peut également être très utile pour configurer chaque instance avec un outil de déploiement tel qu'Ansible (des exemples de playbook sont fournis).|reminder}}
Sans l'option "-n", l'application n'est pas réinstallée mais est prête à l'être, l'ancien fichier param.conf sera sauvegardé en param.sauv.conf et un fichier param.conf contenant les valeurs pas défaut sera téléchargé.


{{note | En ce qui concerne les certificats, si l’on passe par un reverse-proxy externe, les certificats de ce dernier sont propagés et il n’est pas besoin de les installer sur les instances (vous pouvez donc laisser le certificat se créer automatiquement comme proposé dans le script).<br>
Dans le cadre d'une réinstallation, '''l'option "-p"''' est obligatoire si un mot de passe pour Portainer n'a pas été renseigné dans le param.conf car, lors de la réinitialisation, les anciens identifiants de Portainer ont également été réinitialisés.
{{note | Le mot de passe ne peut pas contenir les caractères " et $.| warn}}
Les '''autres options''' servent à la réinstallation de l'application pour alimenter le fichier param.conf, options identiques à celles utilisables lors de la configuration de l'application via le script configure_application.sh.


Si vous ne passez pas par un reverse-proxy externe et que vous n'avez pas de certificat, il sera créé un certificat auto-signé mais il est aussi possible d'utiliser le script ''manage_certificat.sh'' pour générer un certificat Let's Encrypt pour votre domaine".}}
== Suppression de l'application : delete_application.sh ==
 
{{note | Ce script permet de supprimer l'application e-comBox. Une option -e ou -a doit obligatoirement être passée en ligne de commande (voir Usage ci-après).}}
=== Le nouveau fichier param.conf ===
<pre>
<pre>
#!/bin/bash
Usage: bash /opt/e-combox/delete_application.sh -e | -a -f [-h]
  -e Suppression de l'application uniquement
  -a Suppression de l'application, docker et docker-compose
  -f    Force la suppression même si l'accès à Portainer n'est plus possible
  -h Détail des options
</pre>


# Définition des paramètres utiles à l'application.
'''L'option "-e"''' supprime uniquement l'application.
{{note | Attention, le dossier /opt/e-comBox sera supprimé ainsi que les logs.|warn}}


# Version du fichier paramètre (ne pas changer la valeur).
VERSION_PARAM="4.1.0"


# Validation (ou non) de la licence.
'''L'option "-a"''' supprime également Docker et Docker Compose.
# Si cette variable n'a pas la valeur "true", l'application ne pourra pas être installée.
# La licence est consultable ici : https://gitlab.com/e-combox/e-comBox_scriptsLinux/-/raw/v4/LICENCE.
# Les conditions plus générales de la licence CeCILL sont définies sur le site : http://www.cecill.info.
VALIDATION_LICENCE="true"


# Mot de passe pour la connexion en admin à e-comBox et Portainer.
== Mise à jour de l'application : update_ecb.sh ==
# Le mot de passe doit contenir au moins de 12 caractères sans espace.
{{Note/fr|Lorsqu'une nouvelle image de l'e-comBox est disponible, ce script met à jour l'application sans que l'on soit obligé de dérouler le script configure_application.sh.}}
# Le mot de passe ne doit pas contenir les caractères spéciaux suivants : \ " `
Il est exécutable sans option.
# Il ne peut pas être égal à "portnairAdmin" qui est connu de tous
# Le système met le mot de passe à jour avec celui saisi si les deux conditions suivantes sont réunies
# 1 - À l'installation ou à la réinitialisation de l'application
# 2 - Si le mot de passe renseigné a été au préalable modifié sur Portainer
# Ce mot de passe en clair sera chiffré, puis supprimé à l'installation, à la réinitialisation ou à la reconfiguration de l'application
# C'est donc normal qu'une fois l'application installée, réinitialisée ou mise à jour, ce paramètre apparaisse vide.
MDP_PORTAINER=""


# Adresse IP privée ou nom de domaine correspondant à une adresse IP privée.
== Gestion des images : manage_images.sh ==
# Si vous saisissez un nom de domaine, celui-ci doit pouvoir être résolu.
{{note|Ce script permet de télécharger, supprimer et mettre à jour les images de l'e-comBox sans être obligé de reconfigurer l'application. Des options doivent être renseignées en ligne de commande (voir Usage ci-après).}}
# Si aucun domaine n'est configuré, les sites seront accessibles à partir du réseau local via cette adresse IP privée.
# L'adresse IP privée doit obligatoirement être configurée même si le paramètre suivant est renseigné.
ADRESSE_IP_PRIVEE=""


# Adresse IP publique ou nom de domaine correspondant à une adresse IP publique.
<pre>
# Si vous saisissez un nom de domaine, celui-ci doit pouvoir être résolu.
Usage: bash /opt/e-combox/manage_images.sh -d|u|t [-a] [-p] [-w] [-b] [-m] [-s] [-o] [-k] [-r] [-i \"nom_image\"] [-f \"nom_image\" | -f \"type_image\"] [- h]"
# Il s'agit du nom de domaine ou de l'adresse IP qui sera utilisée pour la connexion à l'interface, à Portainer et aux sites à la place de l'adresse IP privée.
  -d Suppression des images non associées à un site en cours d'exécution [-d]
# Aucune valeur ne doit donc être saisie ici si vous ne voulez pas cela, notamment si le serveur ne doit pas être accessible de l'extérieur.
  -u Mise à jour des images. Les sites doivent être redémarrés pour la mise à jour soit effective [-u]
DOMAINE=""
  -a L'action porte sur toutes les images existantes.
  -p Suppression ou mise à jour des images Prestashop [-p]
  -w Suppression ou mise à jour des images WooCommerce [-w]
  -b Suppression ou mise à jour des images Blog [-b]
  -m Suppression ou mise à jour des images Mautic [-m]
  -s Suppression ou mise à jour des images Suite CRM [-s]
  -o Suppression ou mise à jour des images Odoo [-o]
  -k Suppression ou mise à jour des images Kanboard [-k]
  -r Suppression ou mise à jour des images HumHub [-r]
  -i Suppression ou mise à jour d'une image spécifique [-i "nom_image"]
  -f Mise à jour d'une image utilitaire [-f "nom_image" | -f "type_image"]
  -t    Téléchargement de toutes les images des sites (utile pour accélérer la création du premier site correspondant aux images) [-t]"
  -h Détail des options
</pre>'''L'opération de suppression d'images''' peut être utile '''si vous devez gagner de la place'''. Certaines images prennent de la place sur le disque dur sans être utilisées. C'est une opération qui peut être salutaire et qui est sans risque, il n'est pas possible de supprimer des images associées à des sites en cours d'exécution. '''Le seul inconvénient est que le démarrage des sites seront peu plus lents car il faudra télécharger de nouveau les images correspondantes.'''


# Utilisation d'un Reverse-Proxy externe configuré par vos soins - O/N (N par défaut).
'''À contrario, si vous n'avez pas besoin de gain de place,''' il peut être intéressant de télécharger toutes les images (option "-t") avant la première utilisation de l'instance, cela accélérera le lancement du premier site d'un même type.
# Si vous passez par un reverse proxy externe, mettre "O".
# Les minuscules sont également acceptées.
RP_EXT="N"


# Chemin d'accès éventuel (en cas d'utilisation d'un Reverse-Proxy externe).
'''La mise à jour de l'image''' peut s'avérer nécessaire si celle-ci a été modifiée suite à un bug ou à une faille de sécurité.
# Ne pas mettre de "/" dans le chemin.
CHEMIN=""


# Dossier en chemin absolu contenant la clé secrète qui chiffre le mot de passe de Portainer.
== Configuration ou re-configuration de l'intégralité de l'application : configure_application.sh ==
# Par défaut /opt/e-comBox, il est conseillé de le modifier.
{{note|Ce script doit être utilisé pour :
# En cas de modification après installation, ne pas oublier de déplacer le fichier contenant la clé secrète.
* installer l'application ;
DOSSIER_MDP_KEY="/opt/e-comBox"
* re-configurer l'application si des éléments importants de l'environnement ont changé (adresse IP, domaine, passage par un Reverse Proxy externe, passage par un proxy).
 
Il peut être utilisé avec des options facultatives qui remplacent les valeurs du fichier param.conf.
# Dossier en chemin absolu contenant le mot de passe chiffré.
La valeur des principaux paramètres peut être passée directement en ligne de commande (voir Usage ci-après).}}
# Par défaut /opt/e-comBox, il est conseillé de le modifier.
<pre>
# En cas de modification après installation, ne pas oublier de déplacer le fichier contenant le mot de passe chiffré.
Usage: bash /opt/e-combox/configure_application.sh [-f "valeur"] [-i "valeur"] [-d "valeur"] [-r "valeur"] [-c "valeur"] [-p "valeur"] [-h]
DOSSIER_MDP_CHIFFRE="/opt/e-comBox"
  -f Chemin vers le fichier de paramètres [-f "/chemin/nom_fichier"]
 
  -i Adresse IP privée ou nom de domaine correspondant à une adresse IP privée  [-i "@IP_PRIVEE" | -i "nom_domaine"]
# Port utilisé pour un accès direct à Portainer (8880 par défaut).
  -d Adresse IP publique ou nom de domaine correspondant à une adresse IP publique  [-d @IP_PUBLIQUE | -d nom_domaine]. Pour supprimer une adresse IP publique ou un domaine existant -d ""
# Ce port n'a vocation à n'être utilisé qu'en cas de dépannage si l'accès via le reverse-proxy est impossible.
  -r Passage par un Reverse-Proxy externe ou non  [-r "O" | -r "N"]
PORT_PORTAINER="8880"
  -c Chemin en cas de Reverse-Proxy externe [-c "chemin"]. Pour supprimer un chemin existant -c ""
 
  -p Mot de passe de Portainer  [-p "mot_de_passe"]
# Port utilisé pour l'accès à Portainer, à l'interface et aux sites (8800 par défaut).
        Les caractères suivants " $ ` \ & | ! [space] ne passent pas en ligne de commande
# Il s'agit du seul port exposé.
  -s Met la variable de suppression des images à "true" le temps d'exécution du script [-s]
# Si aucun service Web n'écoute sur le port 443 de votre serveur, ce dernier peut être utilisé.
  -b Met la variable de suppression des images à "false" le temps d'exécution du script [-n]
PORT_RP="8800"
  -h Détail des options
 
# Port utilisé pour le registry (5443 par défaut).
PORT_REGISTRY="5443"
 
# Adresse du Proxy.
# Saisissez ip-proxy:port.
ADRESSE_PROXY=""
 
# Hôtes à ignorer par le proxy.
# Ce paramètre n'est à renseigner que si une adresse de Proxy a été saisie.
# Saisissez le ou les hôtes séparés par une virgule sans espace.
NO_PROXY=""
 
# Adresse du réseau interne à Docker.
# Si ce n'est pas votre première installation de l'application, le réseau a déjà été crée et affecté aux sites existants.
# Si vous modifiez les paramètres de ce réseau, TOUS LES SITES EXISTANTS SERONT SUPPRIMÉS.
NET_ECB="192.168.97.0/24"
 
# Suppression des images non associées à un site en cours d'exécution (true par défaut)
# Cela permet de gagner de l'espace mais aussi de supprimer des images qui ne seront plus jamais utilisées
# Le premier démarrage des sites sera un peu plus long car les images correspondantes devront être de nouveau téléchargées.
# Définir le paramètre à "false" si vous voulez ne voulez pas supprimer ces images (non conseillé lors d'une migration).
DEL_IMAGES="true"
 
# Les 2 variables qui suivent sont utiles pour donner le chemin vers les éléments pour mettre en place un certificat existant.
# Vous pouvez les laisser vides dans trois cas.
# Cas 1 : si vous passez par un reverse proxy externe, les certificats configurés dans ce dernier sont propagés.
# Cas 2 : l'accès à l'e-comBox ne va se faire que via le réseau local.
# Cas 3  vous ne disposez pas de certificat pour votre nom de domaine.
# À noter que le script manage_certificat.sh crée un certificat Let's Encrypt et permet de mettre à jour l'application
# si une des 6 variables qui suivent ont été modifiées
# Un certificat auto-signé se créera alors automatiquement via les 4 variables qui suivent.
 
# Fichier certificat existant avec le chemin complet /chemin/fichier.crt ou /chemin/fichier.pem.
CHEMIN_CERT=""
 
# Fichier de la clé privée existante correspondante au certificat avec le chemin complet /chemin/fichier.key.
CHEMIN_KEY=""
 
# Uniquement si utilisation de manage_certificat.sh pour créer un certificat Let's Encrypt
# Adresse de courriel non obligatoire pour créer le certificat (mais recommandé par Lets'encrypt)
MAIL=""
 
# Les 4 variables suivantes sont utiles pour créer un certificat auto signé.
# Elles sont utilisés pour le certificat du registry local.
# Elles sont également utilisées pour le reverse proxy (Nginx) si CHEMIN_CERT et CHEMIN_KEY sont vides.
# Même si vous avez un certificat existant, elles doivent obligatoirement être renseignées.
# Vous pouvez les modifier comme il vous convient.
 
# Code Pays sur 2 lettres.
CODE_PAYS="FR"
 
# Nom Pays.
NOM_PAYS="France"
 
# Nom région.
NOM_REGION="Corse"
 
# Nom organisation.
NOM_ORGANISATION="ReseauCerta"
</pre>
</pre>


=== Installation de l'e-comBox 4.1 ===
{{note | lors d'une reconfiguration, si le fichier param.conf est correctement renseigné et que vous n'avez pas changé le mot de passe de Portainer, le script configure_application.sh peut être lancé sans option. | reminder }}
À noter qu'à partir de la version 4.1, il suffit de télécharger et d'exécuter le script configure_application.sh. Ce dernier installera Docker et Docker Compose s'ils sont inexistants sur le serveur.
<br>
 
'''1. Téléchargement du script configure_application.sh'''
 
Le téléchargement du script peut se faire à partir de la commande :
<pre>wget https://gitlab.com/e-combox/e-comBox_scriptsLinux/raw/4.1/configure_application.sh --output-document configure_application.sh</pre>


Voir également la partie sur [[Installation_sur_Linux_-_v4#Installation_de_l'e-comBox_4.1|l'installation de l'application]].


'''2. Exécution du script configure_application.sh'''
== Configuration de l'authentification openID Connect : configure_oauth.sh (version 4.2) ==
 
{{Note|Ce script permet de configurer l'authentification OpenId Connect ou de revenir à une authentification interne. Des options doivent être passées en ligne de commande (voir Usage ci-après). Un serveur d'authentification SSO compatible (comme keycloak) doit être installé au préalable.
{{note | L'exécution du script doit se faire en '''administrateur''' qui est "root" sur Linux (ou en utilisant la commande sudo).}}
À noter que l'authentification peut directement être configurer à l'installation ou à la reconfiguration de l'application.}}
<pre>
<pre>
Usage: bash configure_application.sh [-f "valeur"] [-i "valeur"] [-d "valeur"] [-r "valeur"] [-c "valeur"] [-p "valeur"] [s | b] [-h]
  -f  Chemin vers le fichier de paramètre  [-f "/chemin/nom_fichier"]
  -i  Adresse IP privée ou nom de domaine correspondant à une adresse IP privée
        [-i "@IP_PRIVEE" | -i "nom_domaine"]
  -d  Adresse IP publique ou nom de domaine correspondant à une adresse IP publique 
        [-d @IP_PUBLIQUE | -d nom_domaine].
        Pour supprimer une adresse IP publique ou un domaine existant -d ""
  -r  Passage par un Reverse-Proxy externe ou non  [-r "O" | -r "N"]
  -c  Chemin en cas de Reverse-Proxy externe [-c "chemin"]. Pour supprimer un chemin existant -c ""
  -p  Mot de passe de Portainer [-p "mot_de_passe"]
        Les caractères suivants " $ ` \ & | ! [space] ne peuvent pas être utilisés en ligne de commande
  -s  Met la variable de suppression des images à "true"  le temps d'exécution du script [-s]
  -b  Met la variable de suppression des images à "false" le temps d'exécution du script [-n] 
  -h  Détail des options
</pre>


'''Exemple d'exécution du script :'''
Usage: bash /opt/e-combox/configure_oauth.sh -f [-h]-a|i [-h] [-s] [-j \"CLIENT_ID\"] [-k \"CLIENT_SECRET\"] [-l \"AUTHORIZATION_URL=\"] [-m \"ACCESS_TOKEN_URL=\"] [-n \"RESOURCE_URL=\"] [-o \"LOGOUT_URLL=\"] [-p \"USER_IDENTIFIER=\"] [-q \"SCOPES\"] [-r \"/CHEMIN/CERT_OAUTH\"]
<pre>
    -a      Activation de l'authentification 0Auth. Dans ce cas les autres paramètres doivent être renseignés soit dans param.conf, soit passés en option à l'exécution du script."
bash /opt/e-comBox/configure_application.sh -i "192.168.10.1" -d "ecb.nom.domaine" -c "instance1" -r "O" -p "mdp_portainer"
    -i      Activation de l'authentification Interne"
    -s      Activation du SS0"
    -j      Identifiant public de l'application OAuth [-j \"CLIENT_ID\"]"
    -k      Client secret  [-k \"CLIENT_SECRET\"]"
    -l      URL pour s'authentifier auprès du fournisseur OAuth [-l \"AUTHORIZATION_URL=\"]"
    -m      URL pour récupérer le token d'accès [-m \"ACCESS_TOKEN_URL=\"]"
    -n      URL pour récupérer des informations sur l'utilisateur authentifié [-n \"RESOURCE_URL=\"]"
    -o      URL pour rediriger l'utilisateur vers le fournisseur OAuth afin de déconnecter l'utilisateur de la session [-o \"LOGOUT_URL=\"]"
    -p      Identifiant qui sera utilisé par Portainer pour créer un compte pour l'utilisateur authentifié [-p \"USER_IDENTIFIER=\"]"
    -q      Étendues requises par le fournisseur OAuth pour récupérer des informations sur l'utilisateur authentifié [-q \"SCOPES\"]"
    -r      Fichier certificat du fournisseur 0Auth (en cas de besoin)  [-r \"/CHEMIN/CERT_OAUTH\"]"
    -h Détail des options
</pre>
</pre>


Les valeurs des paramètres peuvent également être renseignées directement dans /opt/e-comBox/param.conf ou être passées (avec l'option "-f") via un fichier :
'''L'option -a''' active l'authentification "OAuth". Elle a pour effet de mettre le paramètre OAUTH_ENABLE à "true". '''À ce moment là, les paramètres qui suivent dans le param.conf sont pris en compte''' (sinon, ils ne le sont pas). Si les paramètres sont absents de param.conf, il est nécessaire de les passer en ligne de commande.
<pre>
bash /opt/e-comBox/configure_application.sh -f "chemin_vers_fichier"
</pre>


'''Exemple de fichier :'''
'''L'interface de connexion de l'e-comBox''' est modifiée pour prendre en compte la nouvelle authentification :
[[Fichier:Interface-ecombox-oauth.png|centré|750x750px]]
{{Note/fr|inline=1|type=warn|Seul l'utilisateur "admin" peut maintenant se connecter en interne.}}
'''Un exemple avec les éléments correspondants dans le fichier param.conf est fourni ci-dessous :'''
<pre>
<pre>
ADRESSE_IP_PRIVEE="172.31.40.109"
# Ajout du mode d'authentification pour les comptes non-admin basé sur le protocole OAuth (false par défaut).
DOMAINE="ecb.nom.domaine"
# Si false, il n'est pas tenu compte des paramètres qui suivent.
RP_EXT="O"
# Si true, vous devez fournir la valeur des paramètres qui suivent.
CHEMIN="rne"
# Veuillez-vous référer à votre fournisseur OAuth pour déterminer les bonnes valeurs.
MDP_PORTAINER="mdp_portainer"
OAUTH_ENABLE="true"
DOSSIER_MDP_KEY="/etc/ssl/certs/ecombox"
DOSSIER_MDP_CHIFFRE="/etc/ssl/certs/ecombox"
</pre>


{{note | tous les paramètres peuvent être modifiés via ce fichier. Dans l'exemple ci-dessus, les paramètres DOSSIER_MDP_KEY et DOSSIER_MDP_CHIFFRE seront également modifiés.}}
# true ou false
# Lors de l'utilisation de SSO (variable à "true"), le fournisseur OAuth n'est pas obligé de demander des informations d'identification.
SSO_ENABLE="true"


{{note | En ce qui concerne le mot de passe de Portainer, <nowiki>Les caractères suivants " $ ` \ & | ! [space] ne peuvent pas être utilisés en ligne de commande. Si vous saisissez votre mot de passe dans le fichier param.conf, seuls les caractères spéciaux \ " et ` sont interdits</nowiki>.| warn}}
# Identifiant public de l'application OAuth.
CLIENT_ID="portainerar"


== Installation de la version 4.0 ==
# Client Secret
CLIENT_SECRET="vlaOB3mFrBz6yWgbw5w3NIjNmrBiPbxm"


=== Principes de fonctionnement ===
# URL utilisée pour s'authentifier auprès du fournisseur OAuth.
# L'utilisateur sera redirigé vers la page d'authentification du fournisseur d'identité.
AUTHORIZATION_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/auth"


'''Le script principal ''install_linux_ecomBox.sh'' installe l'outil "curl" et appelle 2 autres scripts :
# URL utilisée par Portainer pour échanger un code d'authentification OAuth valide contre un token d'accès.
* ''install_docker_docker-compose.sh'' : installe docker et docker-compose ;
ACCESS_TOKEN_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/token"
* ''configure_application.sh'' : configure l'application e-combox.


Vous pouvez :
# URL utilisée par Portainer pour récupérer des informations sur l'utilisateur authentifié.
* soit exécuter le script principal ;
RESOURCE_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/userinfo"
* soit récupérer et exécuter consécutivement les deux scripts.


Le script de configuration de l'application est interactif, il demande des informations et utilise un fichier de paramètres ''/opt/e-comBox/param.conf qui contient :
# URL utilisée par Portainer pour rediriger l'utilisateur vers le fournisseur OAuth afin de déconnecter l'utilisateur de la session du fournisseur d'identité.
* l'adresse IP privée du serveur (par défaut 127.0.0.1) ;
LOGOUT_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/logout"
* l'adresse IP publique ou le nom de domaine (si l'application doit être accessible de l'extérieur) ;
* le chemin d'accès (en cas de passage par un Reverse Proxy externe) ;
* le numéro des quatre ports que l'application doit obligatoirement utiliser :
** Port utilisé pour l'interface de l'e-comBox, par défaut PORT_ECB=8888,
** Port utilisé pour Portainer, par défaut PORT_PORTAINER=8880,
** Port utilisé pour l'accès  aux sites, par défaut PORT_RP=8800 (c'est le seul port "utile", voir note ci-dessous)
** Port pour le registry, par défaut PORT_REGISTRY=5443 (ce port est interne et n'est pas exposé) ;
* l'adresse du proxy et hôtes à ignorer (si un proxy est nécessaire pour l'accès Internet);
* les variables nécessaires au certificat (à ne remplir qu'en cas de non utilisation de Reverse Proxy externe).


{{note | Le port du Reverse Proxy (PORT_RP) est le seul port non transparent pour les utilisateurs : c'est ce port qui est utilisé dans l'URL si on ne passe pas par le Reverse Proxy externe ou c'est vers ce port qu'il faudra rediriger dans la [https://gitlab.com/e-combox/e-comBox_scriptsLinux/-/blob/v4/README.md configuration du Reverse Proxy externe].}}
# Identifiant qui sera utilisé par Portainer pour créer un compte pour l'utilisateur authentifié.
# Extrait du serveur de ressources spécifié via le champ URL de la ressource.
USER_IDENTIFIER="email"


L'adresse IP et les configurations du proxy peuvent être modifiés interactivement via le script. Les ports doivent être modifiés dans le fichier "param.conf" avant de lancer le script.
# Étendues requises par le fournisseur OAuth pour récupérer des informations sur l'utilisateur authentifié.
SCOPES="openid email"


{{note | Il est aussi possible de modifier l'adresse du réseau à utiliser pour les sites si celle par défaut ne convient pas au moment où cela est demandé. '''Cette dernière doit être différente de l'adresse réseau utilisée par l'établissement'''.| reminder}}
# Fichier certificat du fournisseur 0Auth avec le chemin complet /chemin/fichier.pem.
# Ce denier doit être intégré à Portainer
CERT_OAUTH="/etc/ssl/letsencrypt/keycloak.cub.corsica.pem"
</pre>{{Note/fr|type=reminder|Le dernier paramètre (CERT_OAUTH) permet d'ajouter le certificat du fournisseur OAuth à Portainer. Il n'est pas forcément indispensable. Cela dépend de la configuration de votre serveur.}}


=== Installation de l'e-comBox 4.0 ===


'''1. Téléchargement du script principal'''
Ce qui donne la '''configuration de Portainer''' ci-dessous :
[[Fichier:Conf1 portainer-oauth.png|centré|900x900px]]


Le téléchargement du script principal peut se faire à partir de la commande :
'''Automatic user provisioning'''  et '''Default team''' sont des paramètres mis par défaut de manière à ce que les utilisateurs qui se connectent soient automatiquement ajoutés sur Portainer dans le groupe "Profs".
<pre>wget https://gitlab.com/e-combox/e-comBox_scriptsLinux/raw/v4/install_linux_e-comBox.sh --output-document install_linux_e-comBox.sh</pre>
{{Note | Si vous avez déjà des utilisateurs internes et que vous voulez que les nouveaux utilisateurs ne viennent pas s'ajouter mais les remplacent (de manière à ne pas avoir de manipulations complémentaires à faire sur les propriétés des sites), il suffit que les premiers aient les mêmes identifiants (à modifier donc éventuellement au préalable). | warn}}


'''2. Exécution du script principal'''
[[Fichier:Conf2 portainer-oauth.png|centré|vignette|900x900px]]


{{note | L'exécution du script doit se faire en '''administrateur''' qui est "root" sur Linux (ou en utilisant la commande sudo).}}
== Nettoyage des volumes : nettoyage_volumes.sh (version 4.2) ==
<pre>bash install_linux_e-comBox.sh</pre>
{{note|Ce script supprime les volumes qui ne sont associés à aucun site.}}Il arrive que des volumes "orphelins" soient créés. Par exemple, si un site en cours de création n'aboutit pas pour une raison ou une autre. En dehors du fait que les volumes prennent de la place inutilement, cela peut à terme causer un dysfonctionnement lors, par exemple, de la création d'un site du même nom que le site qui n'a pas aboutit.


Pour exécuter le script en tant qu'administrateur :
{{note|type=reminder|Ce script est automatiquement lancé à la reconfiguration de l'application.}}.
- '''''sudo bash install_linux_e-comBox.sh''''' et vous saisissez votre mot de passe ;
- ou bien '''''sudo su''''' puis vous saisissez votre mot de passe et vous exécutez ensuite le script : '''''bash install_linux_e-comBox.sh'''''.


Si l'installation ne le fait pas le script de configuration crée le dossier "$USER/.docker" et le fichier /$USER/.docker/config.json".
== Réinitialisation du mot de passe de Portainer : reset_pass_portainer.sh ==
{{Note|Ce script permet de réinitialiser, en cas de perte, le mot de passe de Portainer. L'option "-f" doit obligatoirement être passée en ligne de commande (voir Usage ci-après).}}
<pre>
Usage: /opt/e-combox/reset_pass_portainer.sh -f [-h]
-f Réinitialisation du mot de passe de Portainer
-h Détail des options
</pre>


{{note | Les fichiers nécessaires à l'application, les scripts de reconfiguration de l'application ainsi que le fichier contenant les identifiants d'accès aux applications (''e-comBox_identifiants_acces_applications.pdf'') sont installés dans "/opt/e-comBox".|warn}}
{{Note | Vous devez ensuite vous connecter sur Portainer pour modifier le mot de passe fourni afin que ce dernier soit compatible avec l'application. <nowiki>Les caractères suivants " $ ` \ & | ! [space] ne peuvent pas être utilisés en ligne de commande. Si vous saisissez votre mot de passe dans le fichier param.conf, seuls les caractères spéciaux \ " et ` sont interdits</nowiki>. | warn}}


Le script ''install_linux_ecomBox.sh'' lance automatiquement le script ''configure_application.sh''</span><span class="c2"> qui configure l'application dans l'environnement voulu (gestion de l'adresse IP ou nom de domaine, du proxy, etc.) ;
== Sauvegarde et Restauration ==
=== sauv_sites.sh (modifié dans la version 4.2) ===
{{note|Ce script permet de sauvegarder l'intégralité des sites dans une archive '''".tar.gz"'''. Des options peuvent être renseignées en ligne de commande (voir Usage ci-après). Si aucune option n'est passée, une boite de dialogue permet de préciser l'espace de stockage et le nom de l'archive.}}


{{note | Si le serveur passe par un proxy, il faut être vigilant sur la configuration du "noproxy" : il est, en effet, nécessaire d'exclure dans la configuration du proxy "localhost" et le réseau dans lequel se trouve le serveur d'ecomBox ainsi que  le réseau dans lequel se trouve le proxy (si celui-ci est différent). Par exemple, si votre réseau local est 192.168.20.0/24, il faut ajouter dans les éléments d'exclusion 192.168.20.*. Il faut séparer les valeurs saisies par une virgule.|error}}
'''Fonctionnalités apportées par la version 4.2 :'''
* possibilité de dérouler le script sans interaction ;
* la sauvegarde effectuée permet la restauration de l'intégralité des sites mais également d'un seul site.


{{note | Dans cette version, au cours du script, il sera nécessaire de modifier le mot de passe '''admin''' de Portainer mais il n'y a plus de nécessité de le synchroniser avec l'application e-comBox. Un script permettant de réinitialiser ce mot de passe en cas de perte est disponible dans le dossier /opt/e-comBox.}}
<pre>
Usage: Usage: bash /opt/e-combox/sauv_sites.sh [-a \"nom_archive.tar.gz\"] [-h].
  -a   Chemin vers l'archive de sauvegarde [-a \"nom_archive.tar.gz\"].
  -h Détail des options
</pre>'''


{{note | Le nom de l'archive de sauvegarde doit forcément se terminer en .tar.gz.| warn}}


== Lancement de l'e-comBox et utilisation de base ==
La sauvegarde est composée de l'archive de sauvegarde à laquelle est associé un dossier du nom de l'archive sans le ".tar.gz" qui contient lui-même des fichiers ".json" dans lesquels figurent des informations sur chaque site. Ces fichiers sont nécessaires dans le cadre de la restauration d'un seul site.


'''En cas de Reverse Proxy externe :'''
=== restaure_sites.sh (modifié dans la version 4.2) ===
* L'interface de l'e-comBox sera accessible via l'URL : https://<nom_domaine>/<chemin>/app/
{{note|Ce script permet de restaurer, à partir d'une archive '''".tar.gz"''' et des dossiers associés, l'intégralité des sites ou un seul site. Des options peuvent être renseignées en ligne de commande (voir Usage ci-après). Si l'option -r n'est pas passée, c'est l'intégralité des sites qui sont restaurés et une boite de dialogue permet de préciser l'espace de stockage et le nom de l'archive (au cas où l'option -a ne le précise pas).}}
* L'interface de Portainer sera accessible via l'URL : https://<nom_domaine>/<chemin>/portainer/
* Les sites seront accessibles via un URL sous la forme : https://<nom_domaine>/<chemin>/nom_du_site/


'''S'il n'y a pas de Reverse Proxy externe :'''
* L'interface de l'e-comBox sera accessible via l'URL : https://<adresse_IP ou nom_domaine>:PORT_RP/app/
* L'interface de Portainer sera accessible via l'URL : https://<adresse_IP ou nom_domaine>:PORT_RP/portainer/
* Les sites seront accessibles via un URL sous la forme : https://<adresse_IP ou nom_domaine>:PORT_RP/nom_du_site/


{{note|Si le nom de domaine est renseigné, c'est ce dernier qui est utilisé.}}
'''Fonctionnalités apportées par la version 4.2 :'''
* possibilité de dérouler le script sans interaction ;
* possibilité de ne restaurer qu'un seul site.


{{note|Si vous mettez le numéro de port 443 (il faut, bien sûr, qu'il soit libre) au niveau de la variable PORT_RP dans le fichier de configuration param.conf, l'interface de l'e-comBox sera accessible via HTTPS sans qu'il soit besoin de préciser le PORT_RP dans l'URL|reminder}}
<pre>
 
Usage: Usage: bash /opt/e-combox/restaure_sites.sh -f|r \"nom du site\" [-h] [-s] [-a \"chemin_complet_archive_sauvegarde.tar.gz\"]"
 
  -f    Restauration de l'intégralité des sites.
Il faut donc lancer l'application en saisissant :
  -r    Restauration d'un seul site [-r \"nom du site\"].
*l'URL '''https://<nom_domaine>/<chemin>/app/''' en cas de passage par un Reverse proxy externe ;
  -a    Chemin vers l'archive de sauvegarde [-a \"chemin_complet_archive_sauvegarde.tar.gz\"]". Si le chemin est fourni le script se déroulera sans interactivité.  
*l'URL '''https://<adresse_IP ou nom_domaine>:PORT_RP/app/''' en cas de non passage par un Reverse Proxy externe.
  -h Détail des options
 
</pre>'''
{{note|L'authentification peut se faire avec le compte "admin" de Portainer ou avec un compte "professeur" préalablement créé dans Portainer. '''La gestion des utilisateurs est décrite [[Gestion_Utilisateurs|ici]].'''}}
 
La connexion à l'interface de l'application nécessite obligatoirement une authentification.
[[Fichier:EcranAuthentificationEcomBox.png|centré|500x500px]]
{{note|Dans cette version, plusieurs comptes "professeurs" peuvent être créés et chaque professeur ne voit et ne peut agir que sur ses propres sites. Si vous ne disposez pas d'identifiants, il est nécessaire de contacter l'administrateur de votre instance.Par ailleurs, vous pouvez modifier votre mot de passe via l'interface.|reminder}}.
 
Lorsqu'on se connecte (après s'être authentifié), un tableau de bord simplifié permet d'avoir une vue d'ensemble :
[[Fichier:Interface ecb v4.1.png|centré|900x900px]]
<span class="c6">Un clic, dans le menu de gauche (par exemple sur Odoo) conduit à un écran similaire à ci-dessous :</span>
[[Fichier:Sites Odoo.png|centré|900x900px]]
<br clear=all>
La prise en main de cette interface avec sa gestion de base (créer, démarrer, arrêter ou supprimer un site) ainsi que la gestion avancée est décrite plus précisément [[Premiers_pas_-_v4|ici]].
 
{{Note/fr|type=reminder|Depuis la version 4.1, les identifiants de connexion aux sites sont disponibles à partir de l'interface.}}
 
'''En cas de problème''' consultez la [[FAQ_-_v4 | FAQ]].{{note | En cas de modification de l'environnement, comme un changement d'adresse IP ou l'ajout (voire la désactivation) d'un proxy, il est nécessaire de réinitialiser l'environnement en exécutant de nouveau le script ''configure_application.sh'' avec de nouvelles options si nécessaire :
<pre>bash /opt/e-comBox/configure_application.sh [options] </pre> | error}}
 
== La gestion des ressources pour Docker ==


Sur Linux, le professeur sera juste limité par la capacité de son poste (capacité du disque, capacité du processeur et capacité de la mémoire) sachant que le processeur et la mémoire ne sont affectés que lorsque les sites sont lancés.
=== restaure_v3.sh ===
{{note|Ce script permet de restaurer, à partir d'une archive '''".tar.gz"''' la version v3 de l'e-comBox ainsi que les sites qui y étaient ratachés.}}


Par exemple, une instance de Prestashop sur Docker nécessite aux alentours de 200 MB de RAM.
Le script ne prend aucun paramètre en ligne de commande.


Le tableau de bord fournit des statistiques d'utilisation en temps réel.
== Utilisation d'Ansible (en cours de rédaction...) ==

Version du 31 juillet 2023 à 23:07

De nombreux scripts pour gérer l'application sont fournis dans les versions 4.1 et 4.2. Une brève description pour chacun d'entre eux est donné ci-dessous.
Il est rappelé qu'à partir de la version des scripts 4.1.1 (20/04/2023), tous les "B" majuscule dans les noms de dossier basculent en "b" minuscule, ainsi le dossier d'installation /opt/e-comBox devient /opt/e-combox. C'est ce dernier chemin qui est utilisé ici. Si vous avez une version plus ancienne, le dossier d'installation est /opt/e-comBox.

Gestion des certificats : manage_certificats.sh

Ce script permet la création et la mise à jour du certificat pour l'accès à l'interface de l'e-comBox et l'ajout de certificats pour Portainer. Des options doivent être passées en ligne de commande (voir Usage ci-après).
Usage: bash /opt/e-combox/manage_certificats.sh -c|u [-m "valeur"] [-a] [-h]
  -c	Création et mise en place d'un certificat Lets'encrypt
  -u	Mise à jour du certificat à partir des paramètres du fichier param.conf
  -m	Adresse de courriel  [-m "adresse courriel"], non obligatoire
  -a	Installation de la mise à jour automatique du certificat lorsque celui-ci est expiré. Cette option n'a d'utilité qu'une seule fois
  -p    Ajout d'un certificat au format PEM dans Portainer
  -h	Détail des options

L'option "-c" automatise la création et l'installation d'un certificat Let's Encrypt directement utilisable pour l'application.

Votre instance doit être joignable sur le port 80. Attention, vous n'avez pas à installer de serveur Web, le script se charge de tout. L'instance doit juste être en mesure de répondre à une requête de type http://votre_nom_de_domaine (où le nom de domaine est la valeur renseigné dans la paramètre DOMAINE de param.conf). Une redirection peut donc être nécessaire.

Le script :

  • crée le certificat en utilisant le paramètre "DOMAINE" du param.conf et de manière optionnelle le paramètre MAIL (qui peut être soit renseigné dans param.conf soit directement ajouté via l'option "-m" de la ligne de commande) ;
  • copie les fichiers dans /opt/e-combox/letsencrypt/live/<domaine> ;
  • renseigne les paramètres correspondants de param.conf :
    • CHEMIN_CERT="/opt/e-combox/letsencrypt/live/<domaine>/fullchain.pem"
    • CHEMIN_KEY="/opt/e-combox/letsencrypt/live/<domaine>/privkey.pem"
    • MAIL (si un mail est passé en ligne de commande) ;
  • installe le certificat au niveau de l'application.

L'option "-a" (que l'on peut activer ultérieurement) met en place une tâche automatique qui vérifie quotidiennement si le certificat a expiré et le met à jour le cas échéant.

L'option "-u" :

  • met à jour le certificat de l'e-comBox si des valeurs à CHEMIN_CERT et à CHEMIN_KEY sont modifiées, ajoutées ou supprimées ;
  • met à jour le certificat de l'e-comBox (si ce type de certificat auto-signé est utilisé) mais aussi d'autres certificats nécessaires qui s'appuient sur les variables CODE_PAYS, NOM_PAYS, NOM_REGION, NOM_ORGANISATION. Ainsi, si au moins une de ces 4 paramètres sont modifiés, il est nécessaire de mettre à jour les certificats.

L'option "-p" ajoute, si besoin, un certificat (donné en option) sur Portainer.

Réinitialisation de l'application : reinitialise_application.sh

Ce script permet de réinitialiser l'application. Des options doivent être passées en ligne de commande (voir Usage ci-après).
Attention, tous les sites seront perdus.
Usage: bash /opt/e-combox/reinitialise_application.sh -a -f [-n] [-v "valeur"] [-i "valeur"] [-d "valeur"] [-r "valeur"] [-c "valeur"] [-p "valeur"] [-h]
  -a	Suppression de tous les conteneurs, volumes, réseaux et images.
  -f    Force la suppression même si l'accès à Portainer n'est plus possible.
  -n	Réinstallation de l'application.
  -v	Version de l'application à installer si vous voulez changer de version [-v "version"].
  -i	Adresse IP privée nom de domaine correspondant à une adresse IP privée  [-i "@IP_PRIVEE" | -i "nom_domaine"].
  -d	Adresse IP publique nom de domaine correspondant à une adresse IP publique  [-d "@IP_PUBLIQUE" | -d "nom_domaine"]. 
        Pour supprimer une valeur existante -d "".
  -r	Passage par un Reverse-Proxy externe ou non  [-r "O" | -r "N"].
  -c	Chemin en cas de Reverse-Proxy externe [-c "chemin"]. 
        Pour supprimer un chemin existant -c "".
  -p	Mot de passe de Portainer [-p "mot_de_passe"].
        Les caractères suivants " $ ` \ & | ! [space] ne peuvent pas être utilisés en ligne de commande
  -h	Détail des options.

L'option "-a" est obligatoire, elle force la suppression des conteneurs, volumes, réseaux et images. L'option "-f" peut être utilisée si l'accès à Portainer n'est plus possible.

L'ajout de l'option "-n" permet de réinstaller l'application en changeant éventuellement la version via l'option "-v".

Sans l'option "-n", l'application n'est pas réinstallée mais est prête à l'être, l'ancien fichier param.conf sera sauvegardé en param.sauv.conf et un fichier param.conf contenant les valeurs pas défaut sera téléchargé.

Dans le cadre d'une réinstallation, l'option "-p" est obligatoire si un mot de passe pour Portainer n'a pas été renseigné dans le param.conf car, lors de la réinitialisation, les anciens identifiants de Portainer ont également été réinitialisés.

Le mot de passe ne peut pas contenir les caractères " et $.

Les autres options servent à la réinstallation de l'application pour alimenter le fichier param.conf, options identiques à celles utilisables lors de la configuration de l'application via le script configure_application.sh.

Suppression de l'application : delete_application.sh

Ce script permet de supprimer l'application e-comBox. Une option -e ou -a doit obligatoirement être passée en ligne de commande (voir Usage ci-après).
Usage: bash /opt/e-combox/delete_application.sh -e | -a -f [-h]
  -e	Suppression de l'application uniquement
  -a	Suppression de l'application, docker et docker-compose
  -f    Force la suppression même si l'accès à Portainer n'est plus possible
  -h	Détail des options

L'option "-e" supprime uniquement l'application.

Attention, le dossier /opt/e-comBox sera supprimé ainsi que les logs.


L'option "-a" supprime également Docker et Docker Compose.

Mise à jour de l'application : update_ecb.sh

Lorsqu'une nouvelle image de l'e-comBox est disponible, ce script met à jour l'application sans que l'on soit obligé de dérouler le script configure_application.sh.

Il est exécutable sans option.

Gestion des images : manage_images.sh

Ce script permet de télécharger, supprimer et mettre à jour les images de l'e-comBox sans être obligé de reconfigurer l'application. Des options doivent être renseignées en ligne de commande (voir Usage ci-après).
Usage: bash /opt/e-combox/manage_images.sh -d|u|t [-a] [-p] [-w] [-b] [-m] [-s] [-o] [-k] [-r] [-i \"nom_image\"] [-f \"nom_image\" | -f \"type_image\"] [- h]"
  -d	Suppression des images non associées à un site en cours d'exécution [-d]
  -u	Mise à jour des images. Les sites doivent être redémarrés pour la mise à jour soit effective [-u]
  -a	L'action porte sur toutes les images existantes.
  -p	Suppression ou mise à jour des images Prestashop [-p]
  -w	Suppression ou mise à jour des images WooCommerce [-w]
  -b	Suppression ou mise à jour des images Blog [-b]
  -m	Suppression ou mise à jour des images Mautic [-m]
  -s	Suppression ou mise à jour des images Suite CRM [-s]
  -o	Suppression ou mise à jour des images Odoo [-o]
  -k	Suppression ou mise à jour des images Kanboard [-k]
  -r	Suppression ou mise à jour des images HumHub [-r]
  -i	Suppression ou mise à jour d'une image spécifique [-i "nom_image"]
  -f	Mise à jour d'une image utilitaire [-f "nom_image" | -f "type_image"]
  -t    Téléchargement de toutes les images des sites (utile pour accélérer la création du premier site correspondant aux images) [-t]"
  -h	Détail des options

L'opération de suppression d'images peut être utile si vous devez gagner de la place. Certaines images prennent de la place sur le disque dur sans être utilisées. C'est une opération qui peut être salutaire et qui est sans risque, il n'est pas possible de supprimer des images associées à des sites en cours d'exécution. Le seul inconvénient est que le démarrage des sites seront peu plus lents car il faudra télécharger de nouveau les images correspondantes.

À contrario, si vous n'avez pas besoin de gain de place, il peut être intéressant de télécharger toutes les images (option "-t") avant la première utilisation de l'instance, cela accélérera le lancement du premier site d'un même type.

La mise à jour de l'image peut s'avérer nécessaire si celle-ci a été modifiée suite à un bug ou à une faille de sécurité.

Configuration ou re-configuration de l'intégralité de l'application : configure_application.sh

Ce script doit être utilisé pour :
  • installer l'application ;
  • re-configurer l'application si des éléments importants de l'environnement ont changé (adresse IP, domaine, passage par un Reverse Proxy externe, passage par un proxy).

Il peut être utilisé avec des options facultatives qui remplacent les valeurs du fichier param.conf.

La valeur des principaux paramètres peut être passée directement en ligne de commande (voir Usage ci-après).
Usage: bash /opt/e-combox/configure_application.sh [-f "valeur"] [-i "valeur"] [-d "valeur"] [-r "valeur"] [-c "valeur"] [-p "valeur"] [-h]
  -f	Chemin vers le fichier de paramètres  [-f "/chemin/nom_fichier"]
  -i	Adresse IP privée ou nom de domaine correspondant à une adresse IP privée  [-i "@IP_PRIVEE" | -i "nom_domaine"]
  -d	Adresse IP publique ou nom de domaine correspondant à une adresse IP publique  [-d @IP_PUBLIQUE | -d nom_domaine]. Pour supprimer une adresse IP publique ou un domaine existant -d ""
  -r	Passage par un Reverse-Proxy externe ou non  [-r "O" | -r "N"]
  -c	Chemin en cas de Reverse-Proxy externe [-c "chemin"]. Pour supprimer un chemin existant -c ""
  -p	Mot de passe de Portainer  [-p "mot_de_passe"]
        Les caractères suivants " $ ` \ & | ! [space] ne passent pas en ligne de commande
  -s	Met la variable de suppression des images à "true" le temps d'exécution du script [-s]
  -b	Met la variable de suppression des images à "false" le temps d'exécution du script [-n]
  -h	Détail des options
lors d'une reconfiguration, si le fichier param.conf est correctement renseigné et que vous n'avez pas changé le mot de passe de Portainer, le script configure_application.sh peut être lancé sans option.

Voir également la partie sur l'installation de l'application.

Configuration de l'authentification openID Connect : configure_oauth.sh (version 4.2)

Ce script permet de configurer l'authentification OpenId Connect ou de revenir à une authentification interne. Des options doivent être passées en ligne de commande (voir Usage ci-après). Un serveur d'authentification SSO compatible (comme keycloak) doit être installé au préalable. À noter que l'authentification peut directement être configurer à l'installation ou à la reconfiguration de l'application.

Usage: bash /opt/e-combox/configure_oauth.sh -f [-h]-a|i [-h] [-s] [-j \"CLIENT_ID\"] [-k \"CLIENT_SECRET\"] [-l \"AUTHORIZATION_URL=\"] [-m \"ACCESS_TOKEN_URL=\"] [-n \"RESOURCE_URL=\"] [-o \"LOGOUT_URLL=\"] [-p \"USER_IDENTIFIER=\"] [-q \"SCOPES\"] [-r \"/CHEMIN/CERT_OAUTH\"]
    -a      Activation de l'authentification 0Auth. Dans ce cas les autres paramètres doivent être renseignés soit dans param.conf, soit passés en option à l'exécution du script."
    -i      Activation de l'authentification Interne"
    -s      Activation du SS0"
    -j      Identifiant public de l'application OAuth [-j \"CLIENT_ID\"]"
    -k      Client secret  [-k \"CLIENT_SECRET\"]"
    -l      URL pour s'authentifier auprès du fournisseur OAuth [-l \"AUTHORIZATION_URL=\"]"
    -m      URL pour récupérer le token d'accès [-m \"ACCESS_TOKEN_URL=\"]"
    -n      URL pour récupérer des informations sur l'utilisateur authentifié [-n \"RESOURCE_URL=\"]"
    -o      URL pour rediriger l'utilisateur vers le fournisseur OAuth afin de déconnecter l'utilisateur de la session [-o \"LOGOUT_URL=\"]"
    -p      Identifiant qui sera utilisé par Portainer pour créer un compte pour l'utilisateur authentifié [-p \"USER_IDENTIFIER=\"]"
    -q      Étendues requises par le fournisseur OAuth pour récupérer des informations sur l'utilisateur authentifié [-q \"SCOPES\"]"
    -r      Fichier certificat du fournisseur 0Auth (en cas de besoin)  [-r \"/CHEMIN/CERT_OAUTH\"]"
    -h		Détail des options

L'option -a active l'authentification "OAuth". Elle a pour effet de mettre le paramètre OAUTH_ENABLE à "true". À ce moment là, les paramètres qui suivent dans le param.conf sont pris en compte (sinon, ils ne le sont pas). Si les paramètres sont absents de param.conf, il est nécessaire de les passer en ligne de commande.

L'interface de connexion de l'e-comBox est modifiée pour prendre en compte la nouvelle authentification :

Interface-ecombox-oauth.png
Seul l'utilisateur "admin" peut maintenant se connecter en interne.

Un exemple avec les éléments correspondants dans le fichier param.conf est fourni ci-dessous :

# Ajout du mode d'authentification pour les comptes non-admin basé sur le protocole OAuth (false par défaut).
# Si false, il n'est pas tenu compte des paramètres qui suivent.
# Si true, vous devez fournir la valeur des paramètres qui suivent.
# Veuillez-vous référer à votre fournisseur OAuth pour déterminer les bonnes valeurs.
OAUTH_ENABLE="true"

# true ou false
# Lors de l'utilisation de SSO (variable à "true"), le fournisseur OAuth n'est pas obligé de demander des informations d'identification.
SSO_ENABLE="true"

# Identifiant public de l'application OAuth.
CLIENT_ID="portainerar"

# Client Secret
CLIENT_SECRET="vlaOB3mFrBz6yWgbw5w3NIjNmrBiPbxm"

# URL utilisée pour s'authentifier auprès du fournisseur OAuth.
# L'utilisateur sera redirigé vers la page d'authentification du fournisseur d'identité.
AUTHORIZATION_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/auth"

# URL utilisée par Portainer pour échanger un code d'authentification OAuth valide contre un token d'accès.
ACCESS_TOKEN_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/token"

# URL utilisée par Portainer pour récupérer des informations sur l'utilisateur authentifié.
RESOURCE_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/userinfo"

# URL utilisée par Portainer pour rediriger l'utilisateur vers le fournisseur OAuth afin de déconnecter l'utilisateur de la session du fournisseur d'identité.
LOGOUT_URL="https://keycloak.cub.corsica:8443/realms/cub/protocol/openid-connect/logout"

# Identifiant qui sera utilisé par Portainer pour créer un compte pour l'utilisateur authentifié. 
# Extrait du serveur de ressources spécifié via le champ URL de la ressource.
USER_IDENTIFIER="email"

# Étendues requises par le fournisseur OAuth pour récupérer des informations sur l'utilisateur authentifié.
SCOPES="openid email"

# Fichier certificat du fournisseur 0Auth avec le chemin complet /chemin/fichier.pem.
# Ce denier doit être intégré à Portainer
CERT_OAUTH="/etc/ssl/letsencrypt/keycloak.cub.corsica.pem"
Le dernier paramètre (CERT_OAUTH) permet d'ajouter le certificat du fournisseur OAuth à Portainer. Il n'est pas forcément indispensable. Cela dépend de la configuration de votre serveur.


Ce qui donne la configuration de Portainer ci-dessous :

Conf1 portainer-oauth.png

Automatic user provisioning et Default team sont des paramètres mis par défaut de manière à ce que les utilisateurs qui se connectent soient automatiquement ajoutés sur Portainer dans le groupe "Profs".

Si vous avez déjà des utilisateurs internes et que vous voulez que les nouveaux utilisateurs ne viennent pas s'ajouter mais les remplacent (de manière à ne pas avoir de manipulations complémentaires à faire sur les propriétés des sites), il suffit que les premiers aient les mêmes identifiants (à modifier donc éventuellement au préalable).
Conf2 portainer-oauth.png

Nettoyage des volumes : nettoyage_volumes.sh (version 4.2)

Ce script supprime les volumes qui ne sont associés à aucun site.

Il arrive que des volumes "orphelins" soient créés. Par exemple, si un site en cours de création n'aboutit pas pour une raison ou une autre. En dehors du fait que les volumes prennent de la place inutilement, cela peut à terme causer un dysfonctionnement lors, par exemple, de la création d'un site du même nom que le site qui n'a pas aboutit.

Ce script est automatiquement lancé à la reconfiguration de l'application.

.

Réinitialisation du mot de passe de Portainer : reset_pass_portainer.sh

Ce script permet de réinitialiser, en cas de perte, le mot de passe de Portainer. L'option "-f" doit obligatoirement être passée en ligne de commande (voir Usage ci-après).
Usage: /opt/e-combox/reset_pass_portainer.sh -f [-h]
	-f		Réinitialisation du mot de passe de Portainer
	-h		Détail des options
Vous devez ensuite vous connecter sur Portainer pour modifier le mot de passe fourni afin que ce dernier soit compatible avec l'application. Les caractères suivants " $ ` \ & | ! [space] ne peuvent pas être utilisés en ligne de commande. Si vous saisissez votre mot de passe dans le fichier param.conf, seuls les caractères spéciaux \ " et ` sont interdits.

Sauvegarde et Restauration

sauv_sites.sh (modifié dans la version 4.2)

Ce script permet de sauvegarder l'intégralité des sites dans une archive ".tar.gz". Des options peuvent être renseignées en ligne de commande (voir Usage ci-après). Si aucune option n'est passée, une boite de dialogue permet de préciser l'espace de stockage et le nom de l'archive.

Fonctionnalités apportées par la version 4.2 :

  • possibilité de dérouler le script sans interaction ;
  • la sauvegarde effectuée permet la restauration de l'intégralité des sites mais également d'un seul site.
Usage: Usage: bash /opt/e-combox/sauv_sites.sh [-a \"nom_archive.tar.gz\"] [-h].
  -a    Chemin vers l'archive de sauvegarde [-a \"nom_archive.tar.gz\"].
  -h	Détail des options

Le nom de l'archive de sauvegarde doit forcément se terminer en .tar.gz.

La sauvegarde est composée de l'archive de sauvegarde à laquelle est associé un dossier du nom de l'archive sans le ".tar.gz" qui contient lui-même des fichiers ".json" dans lesquels figurent des informations sur chaque site. Ces fichiers sont nécessaires dans le cadre de la restauration d'un seul site.

restaure_sites.sh (modifié dans la version 4.2)

Ce script permet de restaurer, à partir d'une archive ".tar.gz" et des dossiers associés, l'intégralité des sites ou un seul site. Des options peuvent être renseignées en ligne de commande (voir Usage ci-après). Si l'option -r n'est pas passée, c'est l'intégralité des sites qui sont restaurés et une boite de dialogue permet de préciser l'espace de stockage et le nom de l'archive (au cas où l'option -a ne le précise pas).


Fonctionnalités apportées par la version 4.2 :

  • possibilité de dérouler le script sans interaction ;
  • possibilité de ne restaurer qu'un seul site.
Usage: Usage: bash /opt/e-combox/restaure_sites.sh -f|r \"nom du site\" [-h] [-s] [-a \"chemin_complet_archive_sauvegarde.tar.gz\"]"
  -f    Restauration de l'intégralité des sites.
  -r    Restauration d'un seul site [-r \"nom du site\"].
  -a    Chemin vers l'archive de sauvegarde [-a \"chemin_complet_archive_sauvegarde.tar.gz\"]". Si le chemin est fourni le script se déroulera sans interactivité.   
  -h	Détail des options

restaure_v3.sh

Ce script permet de restaurer, à partir d'une archive ".tar.gz" la version v3 de l'e-comBox ainsi que les sites qui y étaient ratachés.

Le script ne prend aucun paramètre en ligne de commande.

Utilisation d'Ansible (en cours de rédaction...)