Prise en main de Dalibi, de A à Z

Dalibi est un logiciel libre et open-source(GPL v3) de gestion d'établissement scolaire, pensé pour le Togo et l'Afrique (primaire, collège, lycée). Il couvre toute la vie de l'école : élèves, notes, examens, présences, finances, personnel et documents.

Techniquement, c'est une application Laravel 12 (PHP 8.3+) avec une interface React 19 + TypeScript reliée par Inertia.js (SPA sans API séparée), sur PostgreSQL. En auto-hébergement, vos données restent chez vous.

Sur votre machine (ou serveur), installez :

• PHP 8.3+ avec les extensions usuelles (pdo_pgsql, mbstring, zip, gd, intl).
• Composer (gestionnaire de dépendances PHP).
• PostgreSQL 12+ (recommandé). SQLite convient pour un test rapide.
• Node.js 20+ et npm (build de l'interface).
• Git.

Pour un déploiement reproductible, une image et une configuration Docker sont fournies dans le dépôt (services app, worker, scheduler, PostgreSQL). Le schéma type :

$ cp .env.example .env        # renseigner APP_KEY, DB_*, MAIL_*
$ docker compose up -d --build
$ docker compose exec app php artisan migrate --seed
$ docker compose exec app php artisan storage:link

Les variables essentielles à renseigner dans .env :

APP_NAME=Dalibi
APP_URL=http://localhost:8000
 
# Base de données (PostgreSQL)
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=dalibi
DB_USERNAME=postgres
DB_PASSWORD=secret
 
# Files d'attente (recommandé : database)
QUEUE_CONNECTION=database
 
# E-mails (pour notifications, ex. échec de sauvegarde)
MAIL_MAILER=smtp
MAIL_HOST=...
MAIL_USERNAME=...
MAIL_PASSWORD=...
 
# Génération des matricules
MATRICULE_COUNTRY_CODE=TG

Le stockage des fichiers(local ou S3/R2) se configure ensuite depuis l'interface (Paramètres → Fichiers & Stockage), pas seulement via .env. Voir aussi la référence complète du .env.

Dalibi envoie des e-mails (notifications, alerte d'échec de sauvegarde, accès portail…). La messagerie se configure via les variables MAIL_* de Laravel. En développement, la valeur par défaut MAIL_MAILER=log écrit les mails dans les logs (aucun envoi réel).

MAIL_MAILER=smtp
MAIL_HOST=smtp.votre-fournisseur.com
MAIL_PORT=587
MAIL_USERNAME=...
MAIL_PASSWORD=...
MAIL_FROM_ADDRESS=no-reply@votre-domaine.tg   # sur un domaine que vous contrôlez
MAIL_FROM_NAME="${APP_NAME}"

Rappel : les e-mails et les sauvegardes manuelles passent par la file d'attente — un worker doit tourner (voir Installation et Mise en production).

Le seeding pré-remplit la base. C'est aussi par là que naît le premier utilisateur: l'inscription publique est désactivée, aucun compte ne peut s'auto-créer. Quatre points d'entrée existent, du plus minimal au plus complet :

admin@dalibi.tg        →  Administrateur
directeur@dalibi.tg    →  Directeur
enseignant@dalibi.tg   →  Enseignant
comptable@dalibi.tg    →  Comptable
secretaire@dalibi.tg   →  Secrétaire
# Mot de passe commun : password

# 1. socle : école, année, classes, matières, comptes de démo
$ php artisan migrate --seed
 
# 2. jeu de démonstration complet (une année scolaire vivante)
$ php artisan db:seed --class=DemoSeeder

$ php artisan migrate --force
$ php artisan db:seed --class=ReferenceDataSeeder --force

$u = App\Models\User::create([
    'firstname' => 'Admin',
    'lastname'  => 'École',
    'email'     => 'admin@monecole.tg',
    'gender'    => 'male',
    'password'  => 'un-mot-de-passe-fort', // haché automatiquement
]);
$u->assignRole(App\Constants\Roles::ADMINISTRATOR); // le matricule est généré automatiquement

Passer d'un lancement local à une instance de production demande quelques réglages de robustesse et de sécurité.

APP_ENV=production
APP_DEBUG=false
APP_URL=https://ecole.votre-domaine.tg
# APP_KEY doit être défini (php artisan key:generate) et gardé secret

$ composer install --no-dev --optimize-autoloader
$ npm ci && npm run build
$ php artisan optimize        # config:cache + route:cache + view:cache
$ php artisan storage:link

$ php artisan queue:work --tries=3

* * * * * cd /chemin/app && php artisan schedule:run >> /dev/null 2>&1

Une image et une configuration Docker (services app / worker / scheduler / PostgreSQL) sont fournies — voir le guide de déploiement.

Dalibi est un monolithe modulaire : une seule application Laravel qui rend directement des pages React via Inertia.js. Il n'y a donc pas d'API REST séparée pour l'interface — le contrôleur renvoie une page et ses données en une fois. Une API REST distincte existe uniquement pour le portail parents/élèves (voir la section API). La logique métier est regroupée dans des services, et l'accès est filtré par permission à chaque route.

Navigateur  (Link Inertia)
   │
   ▼
Route  routes/web.php   ──►  middleware  can:view_students
   │
   ▼
Contrôleur  StudentController@index
   │
   ▼
Service métier  ──►  Modèles Eloquent  ──►  PostgreSQL
   │
   ▼
Inertia::render('Eleves/Index', props)
   │
   ▼
Page React  resources/js/pages/Eleves/Index.tsx

app/
├── Http/Controllers/   ← 1 contrôleur par écran / ressource
├── Models/             ← entités Eloquent (UUID)
├── Services/           ← logique métier réutilisable et testable
├── Jobs/               ← tâches en file d'attente (sauvegardes, e-mails)
├── Notifications/      ← e-mails (ex. échec de sauvegarde)
└── Constants/          ← Roles, Permissions
resources/js/
├── pages/              ← pages React (Inertia)
├── components/         ← design-system + composants partagés
└── types/menu.ts       ← navigation (source des modules)
routes/web.php          ← routes + gardes  can:*
database/
├── migrations/         ← schéma
└── seeders/            ← données de référence & démo

Dalibi s'organise en modules accessibles depuis le menu latéral. Chacun regroupe des fonctions cohérentes, filtrées par vos permissions. Voici ce que couvre chaque module.

L'accès est piloté par les permissions ({capacité}_{module}, ex. view_students, create_marks, delete_backups) — environ 145au total. Un rôle est simplement un ensemble de permissions ; il n'existe pas de super-rôle magique.

• Administrateur — accès complet, configuration, gestion des comptes.
• Directeur — école, années, classes, suivi, rapports.
• Enseignant — ses classes, notes, présences.
• Comptable — finances, rapports, exports.
• Secrétaire — élèves & inscriptions, utilisateurs.
• Parent / Élève — portail de consultation.

Vous pouvez créer un rôle personnalisé depuis Administration → Rôles & permissions : il fonctionne aussitôt (menus, routes, cartes). Détails : guide rôles & permissions.

Deux disques applicatifs séparent les usages :

• media — fichiers publics (logos, filigranes, exports) servis via /storage.
• secure — fichiers sensibles(photos d'élèves, pièces des dossiers), stockés hors du dossier public et servis uniquement via des routes authentifiées.

Les deux suivent la même configuration centralisée : local par défaut, ou S3 / Cloudflare R2 activé depuis Paramètres → Fichiers & Stockage.

Depuis Paramètres → Sauvegardes, aux formats JSON et SQL. Conçu pour tenir sur plusieurs années : écriture en flux, compression gzip, et pg_dump natif sur PostgreSQL (repli portable sinon).

• Médias au choix : archive .zip regroupant la base + les fichiers uploadés.
• Archives par année scolaire : instantané verrouillé, exclu de la rétention (manuel ou à la clôture d'année).
• Intégrité : empreinte SHA-256 vérifiable + alerte e-mail en cas d'échec.
• Restauration : .json, .sql, .gz, .dump, .zip — avec sauvegarde de sécurité automatique préalable, et restauration sélective par table.
• Planification : quotidienne/hebdomadaire + rétention (les archives verrouillées ne sont jamais purgées).

$ php artisan backup:run --formats=json,sql

Le portail expose une API REST (/api/v1) authentifiée par token Laravel Sanctum : notes, bulletins PDF, présences, scolarité et calendrier. La spécification OpenAPI 3.1 est fournie dans le dépôt.

Côté parent/élève: une fois son accès activé (Administration → Accès portail), la personne reçoit ses identifiants, se connecte au portail et consulte — pour chacun de ses enfants — ses notes, bulletins, présences, la scolarité et le calendrier. Aucune saisie : c'est une vue en lecture seule alimentée par l'API.

• Les comptes de démonstration sont bloqués en production et imposent un changement de mot de passe à la première connexion — ne contournez pas ce garde-fou.
• APP_DEBUG=false en production, et ne commitez jamais l'APP_KEY ni le .env.
• Servez toujours en HTTPS ; forcez la redirection HTTP → HTTPS.
• Activez la double authentification (2FA) sur les comptes à privilèges (administrateur, direction).
• Appliquez le moindre privilège : donnez à chaque rôle uniquement les permissions nécessaires.
• Écritures financières protégées : encaissements et cycles de paie sont validés sous verrou — un double-clic ne peut pas encaisser ni décaisser deux fois.
• La preuve d'un encaissement est indestructible : une inscription portant des paiements ne peut pas être supprimée.
• Sauvegardez régulièrement et hors-site (règle 3-2-1) ; testez la restauration et l'intégrité (SHA-256).
• Les pièces sensibles (photos, justificatifs) sont déjà sur un disque privé (secure), hors du dossier public.
• Le journal d'audit trace les actions : consultez-le en cas d'incident.

Dalibi gère un ou plusieurs établissements (table schools) ; certains paramètres (modèles de bulletin et de documents, en-tête, calcul des moyennes, examens officiels, emploi du temps) sont définis par école.

Année académique

Le cycle scolaire (ex. 2024-2025). Une seule est active à la fois.

Période

Découpage de l'année : trimestre ou semestre, selon le type de classe.

Type de classe

Catégorie (maternelle, primaire, collège…) qui pilote les règles de moyennes.

Structure / catégorie de frais

Le barème d'écolage et sa ventilation, par classe.

Écolage

Les frais de scolarité facturés et encaissés.

Bulletin

Le relevé de notes périodique, généré en PDF depuis un modèle.

Matricule

L'identifiant unique d'un utilisateur ou d'un élève (préfixe par rôle).

Rôle / Permission

Un rôle est un ensemble de permissions ; l'accès est piloté par permissions.

Caisse

Un compte de trésorerie (espèces, Mobile Money…) pour encaissements et dépenses.

Rubrique de paie

Un élément de bulletin de salaire (gain ou retenue).

Portail

L'espace de consultation des parents/élèves, alimenté par l'API.

Dalibi est ouvert aux contributions. Le workflow : branches de fonctionnalité vers develop, PR, puis main. Les tests se lancent avec php artisan test.