Configuration

Toute la configuration par le webmaster / hébergeur se fait au moyen du fichier config.local.php situé à la racine de l'installation.

Normalement ce fichier est créé automatiquement à l'installation et contient une clé secrète utilisée pour sécuriser les données.

Attention : si cette clé est modifiée ou supprimée, cela déconnectera les membres actuellement connectés.

Les autres directives possible sont décrites dans le fichier config.dist.php également présent à la racine. Il suffit de recopier la directive indiquée vers le fichier config.local.php et de modifier ses valeurs.

Cette configuration requiert une connaissance basique de PHP.

Journal de la base de données SQLite

Si votre hébergement n'utilise pas NFS, il est recommandé d'inscrire cette constante dans le fichier config.local.php pour rendre la base de données plus rapide :

const SQLITE_JOURNAL_MODE = 'WAL';

Par défaut ce réglage n'est pas activé pour éviter les corruptions de base de données qui sont possibles chez certains hébergeurs utilisant NFS (par exemple OVH).

Stockage

Les plugins, la base de données, les sauvegardes et les fichiers de cache sont tous stockés dans un sous-répertoire data par défaut, afin de réunir tous les fichiers modifiés par Paheko dans le même dossier.

Normalement Paheko n'écrit dans un autre répertoire.

Stockage des documents

Par défaut les documents sont stockés dans la base de données, ainsi il suffit de sauvegarder le fichier SQLite de la base de données (association.sqlite) pour tout sauvegarder, simple et rapide !

Mais si vous préférez stocker les documents dans des fichiers séparés, par exemple si vous avez beaucoup de gros fichiers, ou si vous voulez utiliser un autre outil pour synchroniser/sauvegarder les fichiers, c'est aussi possible.

Pour cela il faut positionner les constantes suivantes dans le fichier config.local.php :

const FILE_STORAGE_BACKEND = 'FileSystem';
const FILE_STORAGE_CONFIG = __DIR__ . '/data/files';

Ceci stockera les fichiers dans le répertoire data/files de Paheko.

Quota des documents

Par défaut Paheko autorise les documents à prendre tout l'espace disponible sur le système de fichier.

Pour limiter cela, il faut positionner la constante FILE_STORAGE_QUOTA (en octets).

const FILE_STORAGE_QUOTA = 10*1024*1024*1024; // 10 Go

Désactivation des mises à jour automatiques

Si vous désirez ne pas permettre aux utilisateurs (administrateurs) de procéder à la mise à jour, positionnez la constante ENABLE_UPGRADES à false.

Utilisation du cron

Par défaut le logiciel lance les tâches automatisées (sauvegarde automatique, envoi des rappels de cotisation, etc.) quand un membre se connecte. Si aucun membre ne se connecte pendant un temps, aucune tâche ne sera lancée.

Il est recommandé de plutôt mettre en place une tâche cron pour lancer ces tâches automatisées.

Pour cela dans le fichier config.local.php il faut positionner la constante USE_CRON à true :

const USE_CRON = true;

Et créer un cron système comme suit :

@daily php /var/www/paheko/scripts/cron.php
* * * * * php /var/www/paheko/scripts/emails.php

En modifiant le chemin d'accès à Paheko évidemment :)

E-mails

Si vous avez activé USE_CRON dans la config, n'oubliez pas de configurer un cron pour lancer le script scripts/emails.php toutes les minutes.

Si vous n'avez pas activé USE_CRON, les e-mail seront envoyés tout de suite depuis la page web, ce qui peut être long quand il y a beaucoup de destinataires.

E-mails de retour (bounces)

Pour savoir si une adresse e-mail est invalide, parfois il faut attendre que le serveur SMTP destinataire vous réponde en vous renvoyant un message d'erreur. Paheko sait reconnaître et interpréter automatiquement ces messages d'erreur.

Pour cela il est possible de configurer une adresse Return-Path dans le fichier config.local.php (constante MAIL_RETURN_PATH).

Pour que les messages envoyés à cette adresse soient renvoyés à Paheko il existe trois méthodes différentes, voir ci-dessous pour les détails.

Si Paheko identifie un motif de retour dans le message de bounce reçu, l'adresse e-mail sera notée comme invalide ou en erreur temporaire. Les messages de réponse automatisée (répondeur) sont ignorés par convenance. Sinon, si Paheko ne parvient pas à identifier le type de message, le message est transmis (forwardé) à l'adresse e-mail de l'association.

Avec le webhook

Vous pouvez utiliser un webhook, par exemple si vous avez un fournisseur de mail qui permet de recevoir les bounces sous la forme de webhook. Ou si vous pouvez configurer votre serveur mail pour appeler une URL HTTP en cas de bounce.

Pour cela il faut envoyer une requête HTTP de type POST à l'adresse http://bounce:MOTDEPASSE@.../admin/handle_bounce.php, avec le contenu complet du message de bounce dans le champ message.

Avec curl cela donnerait par exemple :

curl -F 'message=@/tmp/message.eml' https://bounce:abcd@monasso.com/admin/handle_bounce.php

Le mot de passe est définit dans config.local.php dans la constante MAIL_BOUNCE_PASSWORD.

Avec un script en ligne de commande

Il existe le script scripts/handle_bounce.php qui peut recevoir en STDIN le message entier (avec entêtes).

Il faut configurer votre MTA pour qu'il renvoie les messages à ce script. Avec Exim il faut configurer un transport de type pipe. Exemple de configuration Exim pour une adresse returns@monasso.example.tld :

narragoon_script_router:
  driver = accept
  domains = "monasso.example.tld"
  verify_sender = false
  transport = paheko_script_transport
  local_parts = "returns"
…

paheko_script_transport:
  driver = pipe
  command = php /var/www/paheko/scripts/handle_bounce.php
  user = paheko
  group = paheko
  current_directory = /var/www/paheko
  home_directory = /var/www/paheko
  log_fail_output
  log_defer_output
  timeout = 60s

Avec une boîte mail indépendante en POP3 et un script

Si vous ne gérez pas votre propre serveur de mail, c'est la solution la plus simple. Il faut créer une boîte mail de type POP3 chez n'importe quel fournisseur et d'utiliser curl pour lire les messages en POP3 et les transmettre à Paheko.

Exemple de script :

#!/bin/sh

SERVER="pop3s://mail.monasso.lautre.net/"
LOGIN="returns@monasso.lautre.net"
PASSWORD="motdepasse42"

# Récupérer l'ID du dernier mail de la boîte mail
LAST_ID=$(curl -s -u $LOGIN:$PASSWORD ${SERVER} | tail -n1 | awk '{print $1}')

if [ "$LAST_ID" = "" ] then
    echo "Cannot fetch last email ID"
    exit 1
fi

# Récupérer le contenu du mail et le transmettre au script
curl -s -u $LOGIN:$PASSWORD ${SERVER}/${LAST_ID} | php /var/www/paheko/scripts/handle_bounce.php

# Supprimer le dernier mail
curl --request DELE -s -u $LOGIN:$PASSWORD ${SERVER}/${LAST_ID}

Ce script est à placer en cron, par exemple quelques fois par jour.

Création de documents en PDF

Paheko permet de créer des documents en PDF. Pour cela vous devez avoir installé un programme qui permet de convertir du HTML en PDF.

Par défaut, Paheko essaye de détecter si les programmes suivants sont installés (dans l'ordre) :

  • Prince (non libre) qui dispose d'une licence d'utilisation gratuite mais qui ajoutera un petit logo (discret) sur chaque document généré, il y a aussi des licences payantes ;
  • le navigateur web Chromium (sous Debian : apt install chromium) ;
  • wkhtmltopdf ;
  • weasyprint.

Si aucun programme n'est trouvé, Paheko affichera le message d'erreur suivant :

Aucun programme de création de PDF trouvé, merci d'en installer un.

Nous conseillons Prince, qui est le plus léger, le plus rapide, et qui propose le meilleur rendu. Les autres peuvent avoir des problèmes de rendu, dû au fait qu'ils n'ont pas été conçus pour faire du média papier en premier lieu.

La génération de PDF dans Paheko n'est testée au développement que dans Prince et Chromium. Les autres programmes peuvent générer des erreurs de rendu.

Si vous utilisez Prince, un message indiquant son utilisation sera affiché dans les emails contenant des PDF générés, conformément à la licence de Prince.

Si vous n'avez pas la possibilité d'installer un de ces programmes (par exemple si votre hébergeur ne le permet pas), vous pouvez utiliser l'extension DomPDF qui utilise la bibliothèque DomPDF pour générer des PDF. Notez que son rendu est moins fidèle et des bugs de rendu peuvent se produire.

Si vous disposez d'un autre programme de création de PDF, vous pouvez personnaliser la constante PDF_COMMAND dans config.local.php.

C'est aussi conseillé de manière générale si vous faites beaucoup de génération de PDF, car cela évitera l'étape de détection de programme de conversion HTML vers PDF, qui est un peu coûteuse (ouvre jusqu'à 4 process).

Exemple :

const PDF_COMMAND = 'wkhtmltopdf';

Remarque pour windows

La recherche de programmes externes ne fonctionne pas ; il faut donc impérativement positionner la constante PDF_COMMAND comme indiqué ci-dessus ; de plus, il faut ajouter le chemin complet vers cette commande dans la variable path système (et pas celle de l'utilisateur) puis redémarrer le PC.

Utilisation de Paheko avec un système de SSO et LDAP

Voir Configuration SSO et LDAP