D DOKUBASIS
Blog Dev

Développement à distance : Code-Server, Coolify et Hetzner - les pires pièges d'architecture

En tant que développeur logiciel indépendant et consultant IT, la flexibilité est essentielle. Que je travaille sur des backends Java Spring Boot complexes, que je construise des frontends JavaScript ou que je réalise des visualisations Three.js, mon environnement de développement doit être fluide, reproductible et accessible de partout.

J’ai donc abandonné l’hébergement classique et déplacé mon infrastructure sur mon propre serveur Hetzner, entièrement orchestré par Coolify. Au cœur du système se trouve une instance distante de VS Code (Code-Server).

En théorie, c’est une configuration de rêve. En pratique, je suis tombé dans des pièges d’architecture qui ont failli me rendre fou. Voici les principaux obstacles et comment les éviter proprement.

Piège 1 : l’illusion du proxy de port (ou l’écran noir de la mort)

VS Code dans le navigateur propose une fonction apparemment géniale : la redirection de ports intégrée. Lorsque vous démarrez un serveur de test local, par exemple sur le port 4096, l’IDE crée automatiquement un tunnel vers une URL telle que https://votre-ide.fr/proxy/4096/.

Pour du développement backend pur, comme une API REST Spring Boot qui ne renvoie que du JSON, c’est fantastique. Aucune règle de pare-feu et un accès direct.

Mais dès que vous lancez un frontend moderne avec Vue, React ou Vite, ou un outil doté d’une interface graphique, vous vous retrouvez face à un écran noir et à une série interminable d’erreurs 404 dans la console.

La raison : Les frameworks modernes compilent avec des chemins absolus, par exemple <script src="/main.js">. Le navigateur ignore complètement le sous-dossier /proxy/4096/, cherche les fichiers à la racine du serveur et échoue.

La solution : Traefik et les sous-domaines

La seule architecture propre consiste à ignorer complètement le tunnel intégré de VS Code. Utilisez plutôt le reverse proxy Traefik de Coolify :

  1. Créez chez votre fournisseur de domaine une entrée DNS générique (*.votredomaine.fr) pointant vers votre serveur Hetzner.
  2. Dans Coolify, ajoutez aux domaines du conteneur un nouveau sous-domaine avec le port interne : https://dev.votredomaine.fr:4096.
  3. Traefik gère automatiquement le certificat SSL et achemine l’URL publique propre, sans suffixe de port, directement vers le conteneur. Le frontend se charge correctement.

Piège 2 : l’erreur localhost (502 Bad Gateway)

Vous avez configuré le sous-domaine dans Coolify et attendez avec impatience l’aperçu en direct, mais vous obtenez un glacial 502 Bad Gateway. Traefik fonctionne, mais le conteneur bloque la connexion.

Cela se produit lorsque votre serveur interne, par exemple Five Server ou votre propre outil, écoute par défaut sur 127.0.0.1. Dans le monde Docker, cela signifie que le service communique uniquement avec lui-même à l’intérieur du conteneur. Lorsque le proxy Traefik frappe depuis l’extérieur, la porte reste fermée.

La correction : Forcez votre serveur de test à écouter sur toutes les interfaces réseau. Si vous le lancez depuis le terminal, utilisez --hostname=0.0.0.0 ou définissez la variable d’environnement HOST="0.0.0.0". Si vous utilisez une extension VS Code comme Five Server, adaptez settings.json :

{
  "fiveServer.host": "0.0.0.0",
  "fiveServer.port": 5500
}

Piège 3 : l’amnésie de Docker (« Restart » aujourd’hui, disparu demain)

Vous configurez soigneusement votre .bashrc avec des alias pratiques, générez une clé SSH pour GitHub, arrêtez le conteneur via Coolify et cliquez sur « Deploy » le lendemain. Soudain, tout a disparu. Vos alias sont supprimés et Git redemande les mots de passe.

Ce n’est pas un bug, mais une fonctionnalité. Un conteneur arrêté apparaît brièvement avec une option « Restart ». Pendant la nuit, le ramasse-miettes de Coolify nettoie le serveur et supprime entièrement le conteneur inactif. Un clic sur « Deploy » reconstruit un conteneur neuf depuis l’image de base : tout ce qui n’était pas persistant est perdu.

La structure propre

Ne comptez jamais sur le stockage éphémère du conteneur. Utilisez impérativement des montages liés ou des volumes Docker pour tout ce qui doit rester.

volumes:
  - type: bind
    source: /opt/appdata/workspace # Votre code
    target: /workspace
  - type: bind
    source: /opt/appdata/config    # Paramètres VS Code, clés SSH et .bashrc
    target: /config

Piège 4 : la configuration CORS derrière le reverse proxy

Le dernier piège apparaît souvent pendant le développement full-stack. Votre frontend est disponible sur https://dev.votredomaine.fr et envoie des requêtes à votre backend Spring. Par habitude, vous ajoutez le port dans votre CorsConfiguration :

// FAUX lorsqu'un reverse proxy se trouve devant !
configuration.setAllowedOriginPatterns(
    Arrays.asList("https://dev.votredomaine.fr:5500")
);

Le backend bloque encore la requête. Pourquoi ? Le port 5500 n’est qu’une instruction de routage interne dans Coolify. À l’extérieur, votre navigateur communique de manière transparente avec le proxy Traefik via le port HTTPS standard 443. Il définit donc simplement l’en-tête Origin sur https://dev.votredomaine.fr.

Supprimez le port de la configuration du backend et les erreurs CORS disparaissent.

Conclusion : Héberger sa propre configuration Coolify et Code-Server sur Hetzner demande au départ un peu de patience et une bonne compréhension de Docker. Mais une fois le routage propre, les volumes montés et les ports corrects, vous disposez d’un IDE cloud privé très performant qui n’a rien à envier aux solutions SaaS classiques.