Aller au contenu

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

bin/console app:install:check [--format=text]
bin/console app:install:check --format=json

À 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 :

  1. le domaine applicatif, s'il n'est pas vide ;
  2. php, hôte sur lequel Caddy appelle l'endpoint ask de l'on-demand TLS ;
  3. 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.app efface les battements : rouge jusqu'au battement suivant, au plus 30 s plus tard ;
  • en développement, cache.app est isolé par worktree (REDIS_DB_INDEX) : le contrôle ne voit que le worker de sa propre stack.

Voir aussi