Installation¶

Carbure s'installe entièrement depuis le navigateur : au premier lancement, le portail affiche un assistant qui vérifie la base de données, crée (ou met à jour) ses tables et le compte administrateur. Aucune commande n'est nécessaire.

Docker (recommandé) : tout est inclus (nginx, PHP, woob) et la base de données est préparée par docker/docker-compose.yml.
NAS Synology : voir le tutoriel pas à pas.
Serveur web existant (PHP + MariaDB/MySQL), sans Docker.

Avec Docker (recommandé)¶

git clone https://github.com/ltoinel/Carbure.git && cd Carbure/docker
docker compose up -d

Ouvrez http://<hôte>:8080/ : l'assistant d'installation s'affiche, déjà rempli avec la base de données de docker/docker-compose.yml. Cliquez sur Continuer, choisissez le mot de passe administrateur, puis Installer. C'est tout.

Ajoutez ensuite vos banques depuis l'onglet Comptes du portail (bouton +) : choisissez la banque, saisissez les identifiants demandés, puis les comptes à suivre. Les identifiants sont confiés à woob, qui les conserve sur votre serveur ; Carbure ne les enregistre pas.

Pour choisir vous-même le mot de passe de la base, créez un fichier docker/.env à côté de docker/docker-compose.yml avant le premier démarrage :

DB_PASSWORD=un-mot-de-passe-solide

Variable	Rôle	Défaut
`DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`	Base de données proposée par l'assistant (le mot de passe n'a pas à être ressaisi)	`db`, `3306`, `carbure`, `carbure`
`LANGUAGE`	Langue proposée pour l'administrateur (`fr`, `en`)	`fr`
`SYNC_INTERVAL`	Synchronisation automatique de tous les comptes toutes les N secondes (`86400` = une fois par jour)	désactivée
`CARBURE_WOOB_PATH`	Commande woob écrite dans la configuration par l'assistant ; l'image la définit déjà (`env HOME=/data/woob woob`)	`woob`

Le dossier data/ du projet, monté sur /data dans le conteneur, conserve tout ce qui est propre à votre instance : la configuration écrite par l'assistant (data/conf/prod.ini, avec des secrets aléatoires), la clé APNs (data/conf/certs), les logs (data/logs) et la configuration woob avec vos banques (data/woob). C'est le seul dossier à sauvegarder, avec la base de données. Aucun mot de passe administrateur n'est passé par l'environnement : il est choisi dans l'assistant.

L'image contient nginx (portail, Swagger et API sur le port 80), PHP-FPM et woob. Son HEALTHCHECK interroge GET /api/health toutes les 30 secondes : docker ps affiche healthy quand la base répond.

Accès depuis Internet

Depuis votre réseau local, l'assistant est directement accessible. Si Carbure est appelé depuis une adresse publique avant d'être installé, l'assistant demande un code d'installation, affiché dans les journaux du conteneur (docker compose logs carbure) et écrit dans /data/conf/setup.code.

Derrière un proxy inversé (proxy du NAS, Traefik, Caddy…), les requêtes semblent venir du proxy, donc du réseau local : installez Carbure avant de l'exposer sur Internet, ou imposez le code en créant au préalable /data/conf/setup.code contenant un code de votre choix.

Récupérer l'image¶

L'image est publiée sur Docker Hub à chaque release, pour amd64 et arm64 (NAS Synology Intel comme ARM) :

docker pull ltoinel/carbure:latest

Tag	Contenu
`latest`	Dernière release
`1.2.0`	Une version précise (recommandé en production, pour maîtriser les mises à jour)
`1.2`	Dernière version corrective de la 1.2

Sans docker compose, avec une base MariaDB/MySQL existante (la base et son utilisateur doivent déjà exister ; l'assistant les demande au premier lancement) :

docker run -d --name carbure --restart unless-stopped -p 8080:80 \
  -e SYNC_INTERVAL=86400 -v carbure-data:/data \
  ltoinel/carbure:latest

Mettre à jour¶

docker compose pull && docker compose up -d

Le volume /data est conservé. À chaque démarrage, le conteneur met la base de données à jour automatiquement (les migrations de la nouvelle version sont appliquées) et s'arrête avec un message explicite si l'une d'elles échoue. Pensez à sauvegarder la base avant une mise à jour.

Notifications iOS (APNs)¶

Copiez la clé .p8 dans le volume, puis complétez la section [apns] de /data/conf/prod.ini :

docker compose cp AuthKey_XXXXXXXXXX.p8 carbure:/data/conf/certs/
docker compose exec carbure vi /data/conf/prod.ini   # apns_key_path=conf/certs/AuthKey_XXXXXXXXXX.p8
docker compose restart carbure

Maintenance¶

docker compose logs -f carbure                                         # journaux nginx, PHP et démarrage
docker compose exec carbure ls /data/logs                              # logs de Carbure
docker compose exec -u www-data carbure php tools/migrate.php --status # version du schéma de la base

Modules woob

woob télécharge ses modules (dont celui de votre banque) dans /data/woob et les met à jour automatiquement. Un correctif de module pas encore publié (par exemple pour la BNP) peut être copié dans /data/woob/.local/share/woob/modules/3.7/woob_modules/ ; curl_cffi, nécessaire au module BNP récent, est déjà installé dans l'image.

Sur un serveur web existant¶

Prérequis¶

PHP 8.2 ou plus avec mysqli, curl, openssl et json ; APCu recommandé (cache des routes).
MariaDB ≥ 10.3 ou MySQL 8, avec une base et un utilisateur pour Carbure.
Un serveur web capable de transmettre /api/ à PHP-FPM, par exemple nginx (exemple ci-dessous). Carbure ne fournit pas de fichier .htaccess : la protection des dossiers sensibles est à configurer dans le serveur.
woob installé pour l'utilisateur du serveur web. Le module BNP récent nécessite curl_cffi (pip install "curl_cffi>=0.7").
Facultatif : une clé APNs .p8 (Apple Developer) pour les notifications iOS.

1. Copier Carbure¶

Copiez l'archive d'une release (carbure-vX.Y.Z.tar.gz : src, portal, swagger, sql, tools/migrate.php, conf/prod.sample.ini et le fichier VERSION affiché dans le pied de page du portail) ou le contenu du dépôt dans le dossier du site, par exemple /var/www/carbure. Le dossier conf/ doit être modifiable par le serveur web : l'assistant y écrit la configuration.

2. Configurer le serveur web¶

Les URL /api/… sont envoyées à src/api.php (le préfixe /api est retiré par l'API).
portal/ est servi en fichiers statiques (par exemple sous /portal/).
swagger/ peut être servi pour consulter la spécification OpenAPI.
data/, conf/, sql/, tests/ et tools/ ne doivent pas être exposés.
Utiliser HTTPS.

Exemple nginx (celui de l'image Docker est dans docker/nginx.conf) :

location = / { return 302 /portal/; }
location /portal/ { root /var/www/carbure; }
location /api/ {
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /var/www/carbure/src/api.php;
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_read_timeout 3600;   # la synchronisation peut être longue
    fastcgi_buffering off;       # flux SSE
}
location ~ ^/(data|conf|sql|tests|tools|docker)/ { deny all; }

3. Lancer l'assistant¶

Ouvrez le portail (https://<votre-serveur>/portal/) : l'assistant demande la base de données, crée ses tables (ou met à jour une base Carbure existante, après confirmation d'une sauvegarde) et le compte administrateur, puis écrit data/conf/prod.ini avec des secrets aléatoires (jwtsecret, sync_token…). La commande woob y est woob : adaptez woob_path si woob est installé ailleurs (voir Configuration).

Depuis une adresse publique, l'assistant demande le code d'installation écrit dans data/conf/setup.code (et dans le journal d'erreurs PHP). Voir Sécurité.

4. Ajouter une banque¶

Depuis l'onglet Comptes du portail (bouton +) : choisissez la banque parmi celles que woob supporte, saisissez les identifiants demandés (confiés à woob, qui les conserve ; Carbure ne les enregistre pas), puis les comptes à suivre. woob doit être installé pour l'utilisateur du serveur web.

5. Planifier la synchronisation¶

La clé sync_token de data/conf/prod.ini permet d'appeler la synchronisation sans compte :

# crontab : tous les jours à 7h
0 7 * * * curl -sN -H "X-Sync-Token: <sync_token>" https://exemple.fr/api/bank/sync > /dev/null

Mettre à jour¶

Remplacez les fichiers de Carbure en gardant le dossier data/ (configuration, logs, banques). Si la nouvelle version modifie la base de données, un bandeau Mise à jour de la base de données s'affiche pour l'administrateur dans le portail : sauvegardez la base, puis cliquez sur Mettre à jour. Les migrations déjà appliquées à la main (phpMyAdmin) sont reconnues.

En ligne de commande, php tools/migrate.php --status affiche la version du schéma et php tools/migrate.php applique les migrations.

Après un déploiement qui modifie les routes, le cache APCu est invalidé automatiquement (signature des fichiers de src/resources/).

En cas d'échec de la synchronisation¶

Dans l'onglet Comptes, chaque étape en échec affiche la cause renvoyée par woob. Les sites des banques changent régulièrement : un module woob peut cesser de fonctionner du jour au lendemain. Avant toute chose, vérifiez si le problème est connu ou en cours de correction dans les tickets woob, en cherchant le nom du module de votre banque (le portail propose directement ce lien) :

https://gitlab.com/search?group_id=11540390&project_id=25520182&scope=work_items&search=<module>&sort=created_desc

Remplacez <module> par le nom du module woob (par exemple bnp, creditmutuel, boursorama). Une fois le correctif publié, woob met à jour ses modules automatiquement (woob_auto_update=true).