🏃Démarrage rapide

Cette page mène d’un hôte installé à un serveur que vous contrôlez : une configuration sur disque, une compilation validée, un serveur que vous démarrez, arrêtez et surveillez, et une vérification qui prouve que le serveur de fichiers a répondu. Elle suppose l’installation déjà faite.

🧾 Avant de commencer

L’installateur a laissé un service en écoute sur le port 80, et ce service garde la configuration de /etc/Pingclair/Pingclairfile. Arrêtez-le le temps de vos essais, pour libérer les ports :

sudo pc service stop

mkdir -p ~/demo/public
cd ~/demo
echo '<h1>hello from ~/demo/public</h1>' > public/index.html

1. ✍️ Écrire une configuration

Créez ~/demo/Pingclairfile :

{
    admin 127.0.0.1:2019
}

http://localhost:8080 {
    file_server ./public
}

Trois choses méritent d’être nommées. Le bloc sans nom en tête contient les options globales, et admin est ce qui permet à pingclair start, stop et reload de parler au serveur en cours d’exécution. L’adresse du site porte le schéma, et http:// force le texte en clair ; sans lui, Pingclair traite localhost comme un nom et sert HTTPS depuis sa propre autorité de certification, ce qu’un client HTTP simple voit comme une réponse vide (HTTPS). La racine de file_server est relative au répertoire courant.

2. ✅ Valider avant d’exécuter

pingclair validate

✅ Configuration 'Pingclairfile' is valid!

validate lit ./Pingclairfile par défaut et détecte aussi ./Caddyfile. Il compile la configuration et applique des contrôles sémantiques, comme l’existence des chemins de certificats. La validation n’est pas consultative : une configuration en échec ne s’exécute pas, et la dernière ligne en donne la raison.

3. 🧭 Voir ce que la configuration devient

pingclair adapt --pretty

{
  "debug": false,
  "servers": [
    {
      "name": "localhost",
      "names": [
        "localhost"
      ],
      "listen": [
        "[::]:8080"
      ],

Le JSON compilé est la forme que le serveur exécute réellement. Quand une directive ne se comporte pas comme la documentation l’annonce, c’est le premier endroit où regarder. Pour voir plutôt ce que pingclair fmt changerait dans le fichier :

pingclair fmt --diff

-    file_server ./public
+  file_server ./public

fmt imprime la forme canonique, qui indente de deux espaces.

4. 🚀 L’exécuter

Au premier plan, où le journal reste attaché à votre terminal :

pingclair run Pingclairfile

🚀 Starting Pingclair with config: Pingclairfile
🚀 Starting Pingclair v0.2.0-rc.3
📄 Loaded configuration from: Pingclairfile
🔧 Configured 1 server(s)
🔐 Auto HTTPS: enabled

Ajoutez --watch pour recharger la configuration à chaque enregistrement, ce qui donne la boucle de développement :

pingclair run --watch Pingclairfile

♻️ Configuration reloaded successfully
✅ Configuration reloaded completed successfully in 2.478622ms

Ou exécutez-le en arrière-plan, où il survit à votre shell :

pingclair start -c Pingclairfile

✅ Pingclair started in the background (pid 4432)

pingclair start, stop et reload joignent le serveur en cours d’exécution par l’Admin API, ce qui explique l’option admin ci-dessus. pingclair run n’en a pas besoin.

5. 🔍 Vérifier

curl -i http://localhost:8080/

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 34
Last-Modified: Tue, 22 Sep 2026 03:26:39 GMT
ETag: "22-6ab1f56f"
Vary: Accept-Encoding
Accept-Ranges: bytes
server: Pingclair

ETag et Last-Modified signifient que le serveur de fichiers a lu le fichier sur le disque. Le corps est public/index.html. Pour arrêter un serveur en arrière-plan :

pingclair stop

✅ Pingclair stopped

⚡ Des serveurs en une commande

Trois sous-commandes servent sans fichier de configuration, ce qui est pratique pour un essai ou un hôte jetable :

pingclair file-server --listen :8081 --root ./public
pingclair reverse-proxy --from :8082 --to 127.0.0.1:8081
pingclair respond --listen :8083 -s 200 -b "hello from respond"

Chacune annonce son écouteur au démarrage :

🚀 Starting file server on :8081 serving ./public (browse: false)
🚀 Starting reverse proxy: :8082 -> ["127.0.0.1:8081"]
Server address: [::]:8083

Chaque requête vers :8082 est transmise au serveur de fichiers sur :8081, et :8083 répond avec le corps que vous avez fourni. respond est réservé au développement.

🔁 Le confier au service

Le service exécute /etc/Pingclair/Pingclairfile : c’est donc y placer votre configuration qui la fait survivre à un redémarrage :

sudo cp Pingclairfile /etc/Pingclair/Pingclairfile
sudo pingclair validate /etc/Pingclair/Pingclairfile
sudo pc service reload
curl -i http://localhost/

pc service reload demande au serveur en cours de relire le fichier, ce que l’unité fait en envoyant SIGUSR1. pingclair reload atteint le même code par l’Admin API et rapporte en plus ce que le serveur a pensé du fichier, ce qui exige l’option admin du bloc des options globales ; et sudo kill -USR1 "$(systemctl show -p MainPID --value pingclair)" y arrive sans l’un ni l’autre.

Validez d’abord dans tous les cas, puis lisez la réponse : systemctl reload signale seulement que le signal a été délivré, donc le verdict du serveur — appliqué, ou refusé avec une raison — se trouve sur la ligne d’état de l’unité et dans le journal. Un rechargement refusé laisse la configuration précédente en service, ce qui est précisément le but du refus. Exécution comme service est la version longue.

⚠️ Quand cela ne marche pas

• Address already in use. Le service de l’installateur occupe encore :80, ou un autre processus occupe votre port. sudo ss -ltnp | grep :80 nomme le propriétaire, et sudo pc service stop libère celui par défaut.
• Empty reply from server sur http://localhost:8080. Vous parlez en clair à un écouteur TLS. Ajoutez le schéma http:// à l’adresse du site, ou adressez-vous à lui en https:// en faisant confiance au certificat interne.
• Cannot reach admin API at 127.0.0.1:2019. La configuration n’a pas d’option admin : rien n’écoute pour pingclair stop et pingclair reload. Ajoutez-la au bloc des options globales, ou arrêtez le processus au premier plan avec Ctrl-C.
• curl se bloque sur une adresse de boucle locale. Un proxy système intercepte la requête. Rejouez-la avec curl --noproxy '*'.
• La validation échoue avec Unsupported feature. La directive est reconnue mais non implémentée, et le message nomme l’alternative, comme pour encode br : Brotli n’est pas implémenté pour les réponses proxifiées, le message renvoie donc vers encode zstd gzip.

🧭 Étapes suivantes

• HTTPS : des certificats pour un nom public, depuis Let’s Encrypt ou depuis l’autorité interne.
• Exécution comme service : l’unité, sa sémantique de rechargement et ses journaux.
• Pingclairfile : le langage lui-même, avec les matchers, les fragments et les imports.