Aller au contenu
Webcosa Développeurs
RessourcesOuvrir le CMS

#Configuration

Cinq réglages seulement — l’adresse du CMS, la clé, le site, le thème, le dossier — mais chacun peut venir de quatre endroits. Cette page dit lequel gagne, et surtout ce qui ne doit jamais aller dans un fichier versionné.

#L’ordre de priorité

De la plus forte à la plus faible :

  1. Les options de la ligne de commande

    --url, --site, --theme, --dossier. Elles gagnent toujours. Il n’y a pas d’option pour la clé, et c’est délibéré.

  2. Les variables d’environnement

    WEBCOSA_URL, WEBCOSA_CLE, WEBCOSA_SITE.

    Elles passent avant le fichier de projet, et cet ordre-là mérite qu’on s’arrête dessus : c’est ce qui rend le CLI utilisable en intégration continue, où il n’y a ni terminal ni fichier écrit par connexion. Un .webcosa.json versionné, qui nomme le CMS de développement, ne doit pas prendre le dessus sur le WEBCOSA_URL du runner.

  3. Le fichier de projet, cherché en remontant les dossiers

    Le dossier courant, puis chacun de ses parents jusqu’à la racine — comme git avec .git. On doit pouvoir taper pousser depuis themes/atelier/sections/ sans que rien ne change ; sans la remontée, la commande marcherait à la racine du thème et échouerait un dossier plus bas, ce qui se lit comme un bug.

  4. Le fichier global de la machine

    Écrit par connexion. Le seul endroit où vit la clé.

  5. Les défauts

    http://localhost:3000 pour l’adresse, themes/<nom-du-thème> pour le dossier.

#Réglage par réglage

Tous les réglages ne lisent pas les quatre sources. Le tableau ci-dessous est celui du code, dans l’ordre où il consulte :

RéglageOptionEnvironnement.webcosa.json~/.webcosa/config.jsonDéfaut
Adresse du CMS--urlWEBCOSA_URLurlurlhttp://localhost:3000
Clé—WEBCOSA_CLE—cle—
Site--siteWEBCOSA_SITEsitesitepremier site accessible
Thème--theme—theme—l’unique thème, sinon refus
Dossier--dossier—dossier—dossier du fichier de projet, sinon themes/<slug>
Attention

La clé n’est jamais lue dans .webcosa.json, même si tu l’y écris. Le champ serait simplement ignoré — et le secret, lui, resterait dans ton dépôt. Sa place est ~/.webcosa/config.json, en 0600, hors de tout dépôt.

Note

Le site de ~/.webcosa/config.json vient après celui du .webcosa.json, et c’est voulu : un .webcosa.json posé dans un dossier de thème décrit ce dossier-là, il doit l’emporter sur une préférence de machine. Le réglage global ne sert donc qu’à qui ne travaille que sur un seul site ; pour tous les autres, un .webcosa.json par thème reste la bonne réponse, et recuperer l’écrit tout seul.

Astuce

--verbeux affiche la configuration effective en une ligne, avant le premier appel. C’est le moyen le plus court de savoir d’où sort une valeur surprenante :

bash
· url=https://cms.webcosa.com site=dubois cle=oui

#.webcosa.json — le fichier de projet

Il est posé automatiquement par recuperer à la racine du dossier du thème, et mis à jour par suivre quand celui-ci duplique un thème publié. Il est versionnable.

.webcosa.jsonjson
{
  "site": "dubois",
  "theme": "11111111-1111-4111-8111-111111111111",
  "url": "https://cms.webcosa.com"
}
siteslug ou uuid

Le site visé. Toujours écrit par recuperer, même quand tu ne l’as pas précisé : le CLI inscrit alors celui que le serveur a résolu. Un fichier de projet qui laisse le site implicite délègue le choix à un ordre de liste, et cet ordre change dès qu’un site s’ajoute au compte — le pousser suivant part alors chez un autre client.

themeuuid

Le thème visé. L’identifiant complet, pas le préfixe court : ce fichier est écrit par une machine, il n’a pas à être abrégé.

urladresse

L’adresse du CMS pour ce projet.

dossierchemin relatif

Facultatif, et jamais écrit par le CLI — à ajouter à la main si la racine du thème n’est pas le dossier du fichier. Il est résolu relativement au fichier de projet, pas au dossier courant : sinon un pousser lancé depuis un sous-dossier viserait un chemin qui n’existe pas, ce que la remontée devait justement couvrir.

Danger

Aucune clé dans ce fichier. Il est fait pour être commité — un fichier de projet qui contiendrait le secret finirait poussé sur GitHub le jour même. Un slug de site et un uuid de thème ne sont pas des secrets ; une clé wc_ en est un, et elle vit ailleurs, en 0600.

Si tu ranges tes thèmes dans un dépôt, ajoute quand même à ton .gitignore :

.webcosa/
*.key

#Les variables d’environnement

WEBCOSA_URLadresse

L’adresse du CMS. Prioritaire sur .webcosa.json.

WEBCOSA_CLEsecret

La clé d’API. La seule façon de fournir une clé sans écrire de fichier. Sa présence rend connexion inutile, et neutralise l’avertissement de désaccord d’adresse entre la clé enregistrée et l’appel en cours.

WEBCOSA_SITEslug ou uuid

Le site visé, sur le fil X-Webcosa-Site-Cible. Prioritaire sur le .webcosa.json, ce qui permet à un même dépôt de thème de servir plusieurs sites depuis un même runner.

NO_COLORtoute valeur

Désactive les couleurs. Le CLI les retire déjà quand sa sortie n’est pas un terminal — sans cette garde, une sortie redirigée dans un fichier ou lue par un runner se remplit de ESC[32m, et le premier réflexe est de croire que l’outil a planté.

Il n’existe pas de WEBCOSA_THEME ni de WEBCOSA_DOSSIER : le thème et le dossier viennent de la ligne de commande ou du fichier de projet.

#Le site, et pourquoi il faut le nommer

Un compte peut avoir plusieurs sites. --site=<slug|uuid> désigne celui qu’on vise ; il ne l’autorise pas. Le serveur revalide toujours contre les sites accessibles au porteur de la clé, et refuse en site_interdit — jamais un repli silencieux sur le premier site venu, qui ferait écrire dans le mauvais site sans que personne ne s’en aperçoive avant longtemps.

Sur le fil, cela devient l’en-tête X-Webcosa-Site-Cible, à connaître si tu appelles l’API sans passer par le CLI.

Note

Le suffixe -Cible n’est pas décoratif. Le contrat disait d’abord X-Webcosa-Site — or le proxy purge cet en-tête de toute requête entrante, sans condition, et le repose lui-même : c’est la cicatrice d’une faille où une route croyait lire un champ posé par nous alors qu’il venait de l’appelant.

Envoyé sous ce nom, l’en-tête n’atteignait jamais la route : elle lisait null, retombait sur le premier site du porteur, et une écriture de thème réussissait sur le mauvais site, en silence. -Cible sépare « je demande ce site » de « ce site est le mien » — la seconde affirmation n’appartenant qu’au proxy.

#En intégration continue

Trois variables, aucun fichier, aucun terminal.

.github/workflows/theme.yml
- run: node scripts/theme.mjs pousser --supprimer --force
  env:
    WEBCOSA_URL: https://cms.webcosa.com
    WEBCOSA_CLE: ${{ secrets.WEBCOSA_CLE }}
    WEBCOSA_SITE: dubois

Quatre points, tous appris à la dure :

--forceobligatoire avec --supprimer

Sans terminal, la confirmation ne peut pas être donnée : la commande s’arrêterait sur Suppression annulée. Les fichiers déjà poussés, eux, resteraient bien enregistrés — l’échec est partiel, ce qui est pire qu’un échec franc.

WEBCOSA_CLEclé dédiée, portée themes, avec expiration

Une clé de CI est celle qui traîne le plus longtemps dans le plus d’endroits. Donne-lui un nom qui dit où elle vit, et une durée de vie.

WEBCOSA_SITEtoujours explicite

Ne laisse jamais un runner viser « le premier site accessible ». C’est la seule erreur de cette page qui écrit chez quelqu’un d’autre sans lever la moindre alerte.

publierreste manuel

La commande demande une confirmation qu’aucun drapeau ne contourne. Le déploiement d’un thème peut être automatique ; sa mise en ligne reste une décision.

Astuce

Pour un déploiement en deux temps — pousser à chaque commit, publier à la demande — pousse sur un thème brouillon dédié et garde le publié intact. Le brouillon et le publié coexistent sur le site, et un retour arrière consiste simplement à ne rien publier. Voir Publier.

#Plusieurs sites, plusieurs thèmes

Le fichier de projet suffit dans la plupart des cas : un dossier de thème, un .webcosa.json, aucune option à taper. Pour les situations moins simples :

Un dossier par site, chacun avec son .webcosa.json. La remontée dans les dossiers parents fait le reste — depuis clients/dubois/theme/sections/, le CLI retrouve le bon fichier tout seul.

clients/
├── dubois/theme/.webcosa.json     → site "dubois"
└── moreau/theme/.webcosa.json     → site "moreau"