Commande app:install:check¶
Référence de la commande Console qui diagnostique une installation de Kirexo. Elle exécute une série de contrôles indépendants et rend, pour chacun, un verdict (✓ / ✗), un détail et, en cas d'échec, une remédiation. Elle s'adresse à une instance installée, pas au poste de développement.
Sources :
- commande :
src/Command/InstallCheckCommand.php; - contrat et verdict :
src/Service/Install/InstallCheckInterface.php,src/Service/Install/InstallCheckResult.php; - contrôles :
src/Service/Install/Check/; - signe de vie du worker :
src/EventSubscriber/WorkerHeartbeatSubscriber.php; - valeurs d'exemple refusées :
infra/install/example-secrets.txt.
Synopsis¶
À lancer dans le conteneur applicatif :
docker compose exec php bin/console app:install:check
docker compose exec php bin/console app:install:check --format=json
Mainteneur seulement : pile de production du dépôt
Ne concerne pas une instance installée depuis le bundle. Sur la pile de production du dépôt, préfixer par les deux fichiers Compose : docker compose -f compose.yaml -f compose.prod.yaml exec php bin/console app:install:check.
| Option | Valeurs | Défaut | Rôle |
|---|---|---|---|
--format |
text, json |
text |
Format de sortie. Toute autre valeur est refusée (code 2). |
Utilisable sur un conteneur bloqué
docker compose exec ne passe pas par l'entrypoint de l'image. La commande reste donc lançable dans un conteneur php que le garde-fou des secrets d'exemple retient unhealthy : FrankenPHP n'y est pas démarré, mais le processus est vivant.
Contrôles¶
Les contrôles sont découverts par le tag de service kirexo.install_check (constante InstallCheckInterface::TAG) et exécutés par priorité décroissante (#[AsTaggedItem(priority: …)]). Un contrôle peut rendre plusieurs verdicts.
| Priorité | Classe | Libellé(s) du verdict |
|---|---|---|
| 60 | SecretsCheck |
Secret APP_SECRET, Mot de passe PostgreSQL, Secret JWT Mercure, Clé de chiffrement de la clé API Claude, Identifiants RabbitMQ |
| 50 | HostsCheck |
Domaine applicatif réservé, TRUSTED_HOSTS compatible |
| 40 | MigrationsCheck |
Migrations Doctrine à jour |
| 30 | AssetsCheck |
Assets compilés |
| 20 | MailerCheck |
SMTP joignable, Adresse d'expéditeur routable |
| 10 | WorkerCheck |
Worker Messenger vivant |
Secrets¶
Une valeur est fautive si elle est absente, vide, ou égale (comparaison exacte, sensible à la casse) à l'une des lignes non commentées de infra/install/example-secrets.txt. Un ✓ porte le détail générique « valeur personnalisée » ; un ✗ porte « absente, vide ou valeur d'exemple ». Aucun fragment de la valeur n'est jamais restitué.
| Verdict | Valeur lue | ✗ si | Remédiation affichée |
|---|---|---|---|
Secret APP_SECRET |
paramètre %kernel.secret% |
fautive | APP_SECRET=$(openssl rand -hex 32) |
Mot de passe PostgreSQL |
mot de passe de DATABASE_URL, décodé (rawurldecode) |
fautive, ou URL sans mot de passe | POSTGRES_PASSWORD=$(openssl rand -hex 32), puis changer aussi le mot de passe du rôle en base (ALTER ROLE) : le volume déjà initialisé garde l'ancien |
Secret JWT Mercure |
MERCURE_PUBLISHER_JWT_KEY et MERCURE_SUBSCRIBER_JWT_KEY |
l'une des deux fautive | CADDY_MERCURE_JWT_SECRET=$(openssl rand -hex 32) |
Clé de chiffrement de la clé API Claude |
CLAUDE_API_KEY_CIPHER_KEY |
fautive, pas du base64 strict, ou longueur décodée différente de 32 octets (SODIUM_CRYPTO_SECRETBOX_KEYBYTES) |
CLAUDE_API_KEY_CIPHER_KEY=$(openssl rand -base64 32), avec l'avertissement qu'une rotation rend illisible la clé API déjà stockée, à ressaisir dans /admin/reglages |
Identifiants RabbitMQ |
mot de passe de MESSENGER_TRANSPORT_DSN, décodé |
fautive (guest compris) |
RABBITMQ_PASSWORD=$(openssl rand -hex 32) |
Le mot de passe étant décodé avant comparaison, %21ChangeMe%21 est reconnu comme !ChangeMe!.
Si infra/install/example-secrets.txt est illisible, le contrôle rend un seul verdict Secrets en échec (« liste des valeurs d'exemple introuvable »), remédiation : utiliser une image publiée par la pipeline d'un tag.
Hôtes¶
Source : src/Service/Install/Check/HostsCheck.php. Deux verdicts, toujours rendus dans cet ordre.
Le domaine applicatif est l'hôte du contexte de routage (RequestContext, alimenté par framework.router.default_uri, donc par DEFAULT_URI), normalisé : espaces retirés, minuscules, port final retiré. Cette normalisation est la même que celle de la résolution Host → Site du plugin web.
Domaine applicatif réservé — compare le domaine applicatif à KIREXO_RESERVED_DOMAINS (paramètre %kirexo.reserved_domains%), chaque entrée normalisée de la même façon.
| Situation | Verdict | Détail | Remédiation |
|---|---|---|---|
kernel.debug inactif et domaine applicatif vide, localhost ou 127.0.0.1 |
✗ | default_uri pointe encore sur localhost : les liens des e-mails seront inutilisables |
Renseigner DEFAULT_URI=https://<domaine applicatif> |
| Domaine applicatif absent de la liste (égalité exacte, jamais de suffixe) | ✗ | <hôte> absent de KIREXO_RESERVED_DOMAINS : 404 sur toute l'application |
Ajouter <hôte> à KIREXO_RESERVED_DOMAINS |
| Sinon | ✓ | <hôte> réservé |
— |
Le cas « localhost » est évalué en premier et ne s'applique pas en mode debug : en développement, localhost passe au second test.
TRUSTED_HOSTS compatible — vérifie que TRUSTED_HOSTS, s'il est défini, laisse passer tous les hôtes que l'instance doit servir.
| Situation | Verdict | Détail | Remédiation |
|---|---|---|---|
TRUSTED_HOSTS non défini (aucun motif enregistré par Symfony) |
✓ | non défini : le filtrage est délégué à la résolution Host → Site (404 sur hôte inconnu) |
— |
| Au moins un hôte candidat rejeté | ✗ | rejetés par TRUSTED_HOSTS (400) : <liste> |
Retirer TRUSTED_HOSTS (recommandé, cf. résolution Host → Site) ou l'élargir à ces hôtes |
| Tous les hôtes candidats acceptés | ✓ | N hôte(s) vérifié(s) : domaine applicatif, php, domaines de site |
— |
Hôtes candidats, dédoublonnés, dans cet ordre :
- le domaine applicatif, s'il n'est pas vide ;
php, hôte sur lequel Caddy appelle l'endpointaskde l'on-demand TLS ;- les hôtes rendus par chaque plugin qui implémente la capability
ServedHostsProviderInterface. Avec le plugin web : tous les domaines de site en base, quel que soit leur état (en attente compris).
Chaque hôte est éprouvé par Request::create('http://<hôte>/')->getHost() : un rejet (SuspiciousOperationException) le classe parmi les hôtes rejetés. Le contrôle applique donc exactement les motifs que Symfony a enregistrés au boot du kernel depuis framework.trusted_hosts, sans réinterpréter la regex.
Exemple : TRUSTED_HOSTS='^app\.example\.org$', domaine applicatif app.example.org, un domaine de site blog.example.net en base.
✓ Domaine applicatif réservé : app.example.org réservé
✗ TRUSTED_HOSTS compatible : rejetés par TRUSTED_HOSTS (400) : php, blog.example.net
↳ Retirer TRUSTED_HOSTS (recommandé, cf. résolution Host → Site) ou l'élargir à ces hôtes
Les hôtes de site sont des données publiques : ils sont cités dans le détail. Une erreur levée par un plugin pendant la collecte (base injoignable, par exemple) n'est pas rattrapée par le contrôle : la commande la rend en contrôle interrompu, sous le libellé Hôtes.
Migrations¶
| Situation | Verdict | Détail | Remédiation |
|---|---|---|---|
| Aucune migration en attente ni inconnue | ✓ | aucune migration en attente |
— |
| La base porte des migrations absentes de l'image | ✗ | la base porte N migration(s) inconnue(s) de cette image : image plus ancienne que la base, retour arrière non supporté |
Restaurer la sauvegarde d'avant la mise à jour ou revenir à la version d'image correspondante |
| Migrations en attente | ✗ | N migration(s) en attente |
RUN_MIGRATIONS=1 puis redémarrer, ou docker compose exec php bin/console doctrine:migrations:migrate |
Base injoignable (Doctrine\DBAL\Exception) |
✗ | base injoignable (<classe courte de l'exception>) |
Vérifier le service database : docker compose ps, docker compose logs database |
Le cas « inconnues » est évalué avant le cas « en attente ». Le contrôle est en lecture seule : il ne crée pas la table de suivi des migrations si elle n'existe pas.
Assets¶
| Situation | Verdict | Détail |
|---|---|---|
kernel.debug actif |
✓ | mode debug : assets servis à la volée par AssetMapper |
public/assets/manifest.json ou public/assets/importmap.json illisible |
✗ | public/assets/<fichier> absent |
manifest.json n'est pas du JSON valide |
✗ | public/assets/manifest.json invalide |
manifest.json vide |
✗ | public/assets/manifest.json vide |
Aucune clé du manifeste en .css |
✗ | manifeste sans .css (aucune feuille de style) |
Aucune clé du manifeste en .js |
✗ | manifeste sans .js (aucun module JavaScript) |
| Sinon | ✓ | N asset(s) au manifeste |
Remédiation commune à tous les ✗ : image incomplète, utiliser une image publiée par la pipeline d'un tag (asset-map:compile et tailwind:build au build).
E-mail¶
SMTP joignable — lit MAILER_DSN.
| Situation | Verdict | Détail |
|---|---|---|
MAILER_DSN absente ou vide |
✗ | MAILER_DSN absente |
DSN non analysable par Symfony\Component\Mailer\Transport\Dsn::fromString() |
✗ | MAILER_DSN mal formée |
Schéma null |
✗ | transport null : aucun e-mail ne part (réinitialisation de mot de passe, invitations) |
Schéma non géré par la fabrique SMTP (sendmail, native, fournisseurs par API…) |
✓ | transport « <schéma> » : non sondé |
| Connexion réelle réussie | ✓ | <hôte>:<port> joignable |
| Échec de connexion, de STARTTLS ou d'authentification | ✗ | <hôte>:<port> injoignable ou authentification refusée (<classe courte de l'exception>) |
Remédiation des trois premiers ✗ : MAILER_DSN=smtp://smtp.example.org:587, identifiants URL-encodés insérés avant l'hôte. Remédiation du dernier : vérifier hôte, port, identifiants et chiffrement du SMTP dans MAILER_DSN.
- La connexion est réelle : ouverture de socket, EHLO, STARTTLS et authentification, puis fermeture. Aucun message n'est envoyé.
- Le délai de socket est ramené à 5 s (au lieu de
default_socket_timeout, 60 s par défaut). - Sans port explicite dans le DSN, le détail affiche
<hôte>:défaut. - Seuls l'hôte et le port sont restitués. En cas d'échec, seul le nom court de la classe de l'exception est affiché, jamais son message : celui du transport SMTP peut citer l'identifiant.
DSN composite : rouge attendu
Un DSN composite failover(…) ou roundrobin(…) n'est pas un DSN unique : Dsn::fromString() le refuse. Le verdict est alors MAILER_DSN mal formée, bien que Symfony Mailer accepte cette forme à l'envoi. Ce rouge ne dit rien de la joignabilité des SMTP listés.
Adresse d'expéditeur routable — lit MAILER_FROM_ADDRESS.
| Situation | Verdict | Détail |
|---|---|---|
| Absente ou vide | ✗ | MAILER_FROM_ADDRESS absente |
Domaine (après le dernier @, en minuscules) égal à localhost ou terminé par .local, .localhost, .test, .example ou .invalid |
✗ | domaine non routable : SPF/DKIM impossibles, e-mails classés en spam |
| Sinon | ✓ | domaine <domaine> |
Remédiation : MAILER_FROM_ADDRESS=noreply@<votre domaine>.
Worker Messenger¶
Le contrôle vérifie qu'un worker a donné signe de vie récemment sur chaque transport consommable.
Transports attendus : les clés du service messenger.receiver_locator, en ne gardant que les alias (clés sans .) et en retirant failed et sync (WorkerCheck::EXCLUDED_TRANSPORTS), triés par ordre alphabétique. Avec le plugin web installé : async, plugin_web, scheduler_default. La liste suit les bundles installés : sans le plugin web, plugin_web n'est plus attendu.
| Situation | Verdict | Détail | Remédiation |
|---|---|---|---|
| Battement de moins de 300 s sur tous les transports attendus | ✓ | signe de vie récent sur : <liste> (le plus ancien il y a N s) |
— |
| Au moins un transport sans battement, ou battement de plus de 300 s | ✗ | aucun signe de vie depuis 300 s sur : <transports en défaut> |
Vérifier le service worker (docker compose ps, docker compose logs worker) : il doit consommer <liste attendue> |
Un transport absent de la liste consommée par le worker (KIREXO_WORKER_TRANSPORTS) reste rouge en permanence.
Contrôle interrompu¶
Si un contrôle lève une exception, la commande rend à sa place un verdict ✗ portant le libellé générique du contrôle (Secrets, Hôtes, Migrations, Assets, E-mail, Worker Messenger), le détail Contrôle interrompu : <classe complète de l'exception> et la remédiation Consulter les logs : docker compose logs. Le message de l'exception n'est pas affiché. Les contrôles suivants sont exécutés normalement.
Sortie texte¶
Diagnostic de l'installation Kirexo
===================================
✓ Secret APP_SECRET : valeur personnalisée
✗ Identifiants RabbitMQ : absente, vide ou valeur d'exemple
↳ RABBITMQ_PASSWORD=$(openssl rand -hex 32)
✓ Migrations Doctrine à jour : aucune migration en attente
…
[ERROR] 1 contrôle(s) en échec.
- Une ligne par verdict : symbole (✓ vert, ✗ rouge), libellé en gras, détail.
- Sous chaque ✗ doté d'une remédiation, une ligne préfixée
↳. - Conclusion :
[OK] Installation opérationnelle.ou[ERROR] N contrôle(s) en échec.
Sortie JSON¶
Avec --format=json, stdout ne contient que le document JSON (ni titre ni conclusion), indenté, sans échappement des caractères Unicode ni des /. Les chaînes sont restituées brutes : un <…> présent dans un détail n'est pas interprété comme balise de formatage de la console.
{
"healthy": false,
"checks": [
{
"label": "Secret APP_SECRET",
"passed": true,
"detail": "valeur personnalisée",
"remedy": null
},
{
"label": "Identifiants RabbitMQ",
"passed": false,
"detail": "absente, vide ou valeur d'exemple",
"remedy": "RABBITMQ_PASSWORD=$(openssl rand -hex 32)"
}
]
}
| Clé | Type | Contenu |
|---|---|---|
healthy |
bool |
true si tous les verdicts sont ✓. |
checks |
list |
Verdicts, dans l'ordre d'exécution. |
checks[].label |
string |
Libellé du verdict. |
checks[].passed |
bool |
Verdict. |
checks[].detail |
string |
Constat. |
checks[].remedy |
string ou null |
Remédiation ; null sur un ✓. |
Invariant de InstallCheckResult : detail et remedy ne contiennent jamais la valeur d'un secret ni un DSN complet. La sortie peut être collée dans un ticket.
Codes de sortie¶
| Code | Constante | Situation |
|---|---|---|
0 |
Command::SUCCESS |
Tous les verdicts sont ✓. |
1 |
Command::FAILURE |
Au moins un verdict ✗ (contrôle interrompu compris). |
2 |
Command::INVALID |
--format hors text / json. Aucun contrôle n'est exécuté. |
Rouges attendus en développement¶
La commande vise les installations. Elle ne dépend pas de APP_ENV, et sur la stack de développement plusieurs verdicts sont rouges par construction :
| Verdict | Pourquoi |
|---|---|
Secret APP_SECRET, Mot de passe PostgreSQL, Secret JWT Mercure |
Valeurs d'exemple de .env et compose.yaml (!ChangeMe!, !ChangeThisMercureHubJWTSecretKey!). |
Identifiants RabbitMQ |
Mot de passe guest. |
TRUSTED_HOSTS compatible |
TRUSTED_HOSTS y est surchargée par ^(.+\.)?localhost$\|^127\.0\.0\.1$, qui ne couvre pas php : php figure toujours parmi les hôtes rejetés, avec tout domaine de site en base hors *.localhost. |
Adresse d'expéditeur routable |
noreply@kirexo.local, domaine en .local. |
Worker Messenger vivant |
Rouge si le worker supervisé est arrêté, ou s'il ne consomme pas l'un des transports attendus. |
Assets compilés est vert en développement (mode debug). SMTP joignable y sonde Mailpit (mailer-int:1025).
Signe de vie du worker¶
Messenger n'expose pas d'état « worker vivant ». Le subscriber App\EventSubscriber\WorkerHeartbeatSubscriber en écrit un dans le cache applicatif, lu par WorkerCheck.
| Propriété | Valeur |
|---|---|
| Pool | cache.app (Redis, partagé par le serveur et les workers) |
| Clé | kirexo_worker_heartbeat.<transport> (WorkerHeartbeatSubscriber::cacheKey()), une par transport consommé par le worker |
| Valeur | Horodatage Unix (int) du battement |
| Écriture | À WorkerStartedEvent (immédiatement au démarrage de messenger:consume), puis à WorkerRunningEvent, au plus une fois toutes les 30 s par processus (HEARTBEAT_INTERVAL_SECONDS) |
| Expiration | 300 s (HEARTBEAT_TTL_SECONDS) ; c'est aussi l'âge maximal accepté par WorkerCheck |
| Arrêt du worker | Aucune suppression : la clé expire d'elle-même |
Conséquences observables :
- un worker vient de démarrer : le contrôle est vert aussitôt ;
- plusieurs instances : il suffit que l'une d'elles batte sur un transport ;
- un message qui dure plus de 300 s n'émet aucun événement pendant son traitement : le contrôle peut passer rouge le temps de ce message ;
bin/console cache:pool:clear cache.appefface les battements : rouge jusqu'au battement suivant, au plus 30 s plus tard ;- en développement,
cache.appest isolé par worktree (REDIS_DB_INDEX) : le contrôle ne voit que le worker de sa propre stack.
Voir aussi¶
- Garde-fou des secrets d'exemple — refus de démarrer au niveau de l'entrypoint, commandes de génération.
- Le conteneur reste
unhealthy: secret d'exemple refusé — procédure de correction. - Pourquoi refuser de démarrer plutôt qu'avertir, et diagnostiquer par contrôles indépendants — les choix derrière ces deux dispositifs.
- Worker Messenger — transports consommés et nombre d'instances.
- Pourquoi
TRUSTED_HOSTSnon défini est nominal — le choix derrière le contrôle des hôtes.