Déployer Hasura GraphQL Engine v2 sur Coolify avec PostgreSQL 17 — tutoriel 2026

📍 Article principal : Hasura DDN + PostgreSQL pour PME. Ce tutoriel installe Hasura GraphQL Engine v2 en production sur Coolify, depuis le VPS vide jusqu’au premier query GraphQL fonctionnel.

Hasura GraphQL Engine v2 reste en 2026 le moyen le plus rapide de transformer une base PostgreSQL en API GraphQL complète. Ce tutoriel guide pas à pas le déploiement : choix du VPS, durcissement, installation Coolify, déploiement Hasura + PostgreSQL via le marketplace, sécurisation par admin secret, configuration JWT, premières migrations versionnées dans Git, premier query GraphQL exécuté depuis un client Apollo. À la fin, la PME dispose d’un backend opérationnel et reproductible, prêt à recevoir les modèles métier.

Prérequis

• VPS Linux Debian 12 fraîchement provisionné (Hetzner CCX13 minimum : 4 vCPU, 16 Go RAM, 80 Go SSD)
• Sous-domaine api.masociete.sn avec DNS A pointé sur l’IP publique
• Accès root SSH durci avec clé Ed25519
• Notions PostgreSQL et GraphQL basiques
• Niveau : intermédiaire
• Temps estimé : 3 à 4 heures

Étape 1 — Préparer le VPS et installer Coolify

Le déploiement d’un backend de production démarre toujours par le durcissement de l’OS. Cette étape évite que les bots automatiques ne compromettent le serveur en quelques heures via brute-force SSH ou exploitation de services exposés. Créer un compte admin non-root, désactiver l’authentification par mot de passe SSH, n’autoriser que les clés Ed25519, ouvrir uniquement les ports nécessaires (22 SSH custom, 80 HTTP pour Let’s Encrypt, 443 HTTPS), activer Fail2ban avec une politique stricte sur SSH.

Une fois l’OS sécurisé, installer Coolify en une commande depuis le compte admin : le script officiel coolify.io configure Docker, Docker Compose, Caddy reverse-proxy avec certificats Let’s Encrypt automatiques, et l’interface web Coolify sur le port 8000. Au bout de cinq minutes, accéder à l’interface web, créer le compte administrateur initial, configurer le domaine principal et l’accès Cloudflare ou Hetzner DNS si on veut automatiser la création d’enregistrements DNS.

Cette base Coolify servira ensuite à déployer plusieurs services indépendants : Hasura, PostgreSQL, Redis, et plus tard Keycloak ou un service custom Node. La force de Coolify réside dans cette gestion unifiée — un seul tableau de bord pour observer l’ensemble, redéployer un service en un clic, restaurer une configuration en cas de problème.

Étape 2 — Déployer PostgreSQL 17 dédié

Hasura a besoin d’une base PostgreSQL accessible. Plutôt que d’utiliser une base partagée, déployer une instance dédiée garantit la stabilité et les performances. Dans Coolify, créer un nouveau service à partir du marketplace PostgreSQL 17. Configurer un mot de passe fort généré aléatoirement, choisir le volume persistant, exposer uniquement le port 5432 sur le réseau interne Docker (pas en public).

services:
  postgres:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: <mdp-fort>
      POSTGRES_DB: hasura_main
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
    deploy:
      resources:
        limits:
          memory: 4G
volumes:
  postgres_data:

L’image alpine reste légère et rapide. La limite mémoire à 4 Go convient pour une charge PME jusqu’à 50 utilisateurs simultanés et plusieurs millions de lignes par table. Au démarrage, Postgres applique automatiquement la création de la base hasura_main. Vérifier la santé du conteneur via docker logs et tester la connexion depuis un client psql local.

Configurer immédiatement la sauvegarde quotidienne via Restic vers Hetzner Storage Box. Un dump nocturne complet plus une rétention 14 jours/8 semaines/12 mois donne un RPO de 24 heures et un historique d’environ deux ans pour 5 €/mois de stockage. Tester la restauration sur un VPS de bac à sable une fois par trimestre — la sauvegarde non testée est une promesse vide.

Étape 3 — Déployer Hasura GraphQL Engine v2

Avec PostgreSQL opérationnel, déployer Hasura. Le marketplace Coolify propose un service Hasura prêt à l’emploi, ou créer un service custom avec ce compose qui pointe vers le PostgreSQL précédemment déployé.

services:
  hasura:
    image: hasura/graphql-engine:v2.45.0-ce
    environment:
      HASURA_GRAPHQL_DATABASE_URL: postgres://postgres:<mdp>@postgres:5432/hasura_main
      HASURA_GRAPHQL_ENABLE_CONSOLE: "true"
      HASURA_GRAPHQL_DEV_MODE: "false"
      HASURA_GRAPHQL_ADMIN_SECRET: <secret-admin-32-chars>
      HASURA_GRAPHQL_JWT_SECRET: '{"type":"HS256","key":"<jwt-key-64-chars>"}'
      HASURA_GRAPHQL_UNAUTHORIZED_ROLE: anonymous
      HASURA_GRAPHQL_LOG_LEVEL: warn
    ports:
      - "8080:8080"
    depends_on:
      postgres:
        condition: service_healthy

Trois variables critiques. HASURA_GRAPHQL_ADMIN_SECRET protège la console et l’API admin — sans ce secret, n’importe qui sur internet peut accéder à toute la base. Générer une chaîne aléatoire de 32 caractères et la stocker dans le coffre Coolify, jamais dans Git. HASURA_GRAPHQL_JWT_SECRET permet à Hasura de valider les JWT émis par le service d’authentification — clé HS256 d’au moins 64 caractères. HASURA_GRAPHQL_DEV_MODE: false désactive l’introspection et les messages d’erreur détaillés en production, mesure de sécurité contre la reconnaissance malveillante du schéma.

Coolify applique le compose, télécharge l’image Hasura, démarre le conteneur, configure Caddy pour exposer le port 8080 sur api.masociete.sn avec certificat Let’s Encrypt automatique. Au bout de quelques minutes, accéder à https://api.masociete.sn/console, saisir l’admin secret, voir la console s’ouvrir avec la base PostgreSQL connectée et reconnue.

Étape 4 — Première migration et premier query

Créer une première table métier pour valider le pipeline complet. Dans la console Hasura, aller dans Data → Create Table, définir une table products avec les colonnes : id (uuid, primary key, default uuid_generate_v4), name (text, not null), price_xof (integer, not null, check > 0), category (text), created_at (timestamptz, default now). Cliquer sur Create. Hasura génère automatiquement la migration SQL et met à jour le schéma GraphQL.

Insérer trois lignes via la console pour avoir des données de test. Aller dans l’onglet API et exécuter le premier query GraphQL :

query ListProducts {
  products(order_by: {created_at: desc}, limit: 10) {
    id
    name
    price_xof
    category
  }
}

La réponse arrive en quelques millisecondes avec les trois produits insérés. Sans avoir écrit une seule ligne de backend, l’API est opérationnelle. Tester ensuite une mutation pour insérer un nouveau produit, une query avec filtre where: {price_xof: {_gte: 5000}}, une agrégation products_aggregate qui retourne le nombre total et le prix moyen. Toutes ces opérations sont disponibles immédiatement.

Étape 5 — Versionner les migrations dans Git

Manipuler la base directement depuis la console est pratique en développement mais inacceptable en production. Les modifications doivent passer par des migrations versionnées dans Git. Installer la CLI Hasura sur la machine de développement, configurer un fichier config.yaml qui pointe vers l’instance et lancer hasura migrate create init_schema pour générer un fichier vide qu’on remplit manuellement.

La CLI propose aussi un mode console qui ouvre la console web localement avec sauvegarde automatique de chaque modification dans des fichiers de migration. C’est le meilleur des deux mondes : on continue à pointer-cliquer pour la productivité tout en versionnant chaque changement. Commiter les migrations dans Git, les revoir en pull request, les déployer via une CI Coolify qui exécute hasura migrate apply à chaque merge sur la branche principale.

Cette discipline élimine les surprises lors des déploiements et permet le rollback en cas de bug — il suffit d’exécuter hasura migrate apply --down 1 pour annuler la dernière migration. Pour les PME qui démarrent avec une équipe technique réduite, c’est l’investissement le plus rentable : trois jours d’apprentissage initial, des années de sérénité opérationnelle.

Étape 6 — Connecter un client frontend

Pour valider le pipeline complet, créer un petit projet Next.js qui consomme l’API GraphQL. Installer @apollo/client ou graphql-request, configurer le endpoint https://api.masociete.sn/v1/graphql, ajouter l’header x-hasura-admin-secret en développement (en production, basculer sur le JWT issu du service d’auth). Quelques lignes de TypeScript suffisent à afficher la liste des produits avec hot reload, mise à jour automatique en cas de mutation, gestion d’erreur structurée.

Cette boucle développement-production est l’argument le plus convaincant pour Hasura. Un développeur peut concevoir un nouvel écran et le brancher sur la base en moins d’une heure, sans toucher au backend. La PME teste rapidement des hypothèses produit, itère, valide ou pivote — agilité qui tranche avec la lenteur des stacks traditionnelles.

Console v2 vs v3 et choix de version

Hasura propose en 2026 deux interfaces de console distinctes. La console v2 historique est embarquée dans le binaire HGE et accessible directement sur l’URL du moteur. Elle convient parfaitement aux PME qui démarrent — interface graphique stable, fonctionnalités matures, communauté familière. La console v3 (issue de DDN) sépare l’interface du moteur et offre une expérience modernisée mais demande plus de configuration. Pour ce tutoriel, la console v2 reste recommandée.

Côté version du moteur, choisir une release LTS plutôt qu’une stable la plus récente. La v2.45 publiée en début 2026 reste maintenue jusqu’à fin 2027 minimum, donne du temps pour planifier la montée en version. Éviter les versions zéro (.0) qui contiennent souvent des régressions — attendre la x.y.1 ou x.y.2 pour la production. Cette discipline évite les surprises et préserve la stabilité du backend critique.

Monitoring Hasura en production

Hasura expose un endpoint /healthz qui répond OK quand le moteur est sain, plus un endpoint /v1/version qui retourne la version courante. Configurer Uptime Kuma pour surveiller ces deux endpoints toutes les minutes : alerte si la santé bascule en KO ou si la latence dépasse 2 secondes. Côté métriques, Hasura expose aussi un endpoint /v1/metrics compatible Prometheus depuis la version 2.40 — scrapper cet endpoint depuis Prometheus + Grafana pour visualiser le débit, le temps de traitement, les erreurs en temps réel.

Trois alertes critiques à configurer. Première : latence p99 supérieure à 2 secondes pendant plus de 5 minutes (signale un problème base, index manquant ou requête malveillante). Deuxième : taux d’erreur supérieur à 5 % (signale un bug applicatif ou un changement de schéma incompatible). Troisième : nombre de connexions PostgreSQL au-delà du pool size (signale un fuite de connexion ou une configuration insuffisante). Ces alertes anticipent les incidents utilisateur et donnent le temps d’agir avant que la PME ne perde de la clientèle.

Performance et tuning PostgreSQL

Hasura traduit les requêtes GraphQL en requêtes SQL optimisées, mais la performance finale dépend du dimensionnement de PostgreSQL. Quatre paramètres clés à ajuster dans postgresql.conf. shared_buffers à 25 % de la RAM dédiée à Postgres, effective_cache_size à 75 %, work_mem à 64 Mo pour les requêtes complexes avec tri ou agrégation, max_connections à 100 minimum (Hasura ouvre un pool de 50 par défaut).

Activer aussi pg_stat_statements qui enregistre les requêtes les plus lentes et leur fréquence. Au bout d’une semaine d’utilisation réelle, identifier les top 10 requêtes consommatrices et ajouter les index manquants. Cette boucle d’optimisation guidée par les données réelles est dix fois plus efficace que de pré-optimiser à l’aveugle. Pour les charges au-delà de 100 utilisateurs simultanés, considérer PgBouncer en transaction pooling devant Postgres pour absorber les pics de connexions sans surdimensionner la base.

Erreurs fréquentes

Adaptation au contexte ouest-africain

Pour les déploiements souverains, déployer Coolify et l’ensemble de la stack sur un VPS local au Sénégal ou en Côte d’Ivoire (Wagaden, Sonatel Cloud, partenaires régionaux). La latence applicative reste excellente puisque tout fonctionne sur la même machine. Pour les utilisateurs distants en zone à connectivité instable, configurer Hasura avec un cache Redis devant la base : les requêtes fréquentes sont servies en cache même quand PostgreSQL est temporairement injoignable, l’application reste utilisable en mode dégradé pendant les courtes coupures réseau.

Stratégie de mise à jour de version

Hasura publie des versions mineures tous les deux à trois mois et des correctifs de sécurité plus fréquents. La procédure de mise à jour en production tient en quelques étapes : lire les release notes pour identifier les éventuels breaking changes, sauvegarder la base PostgreSQL et l’export Hasura metadata, mettre à jour l’image Docker dans Coolify, redéployer, vérifier les migrations appliquées automatiquement par Hasura au démarrage, valider la santé de l’API via les requêtes critiques. La fenêtre de coupure tient en moins de 5 minutes pour une instance mono-nœud.

Tester systématiquement la mise à jour majeure (v2.x vers v2.y) sur un environnement bac à sable identique à la production avant le déploiement final. Quelques modifications subtiles existent entre versions — comportement de cache, format des logs, paramètres de configuration — qu’il vaut mieux découvrir en environnement contrôlé. Documenter chaque mise à jour dans un journal d’opérations qui mentionne version d’origine et cible, problèmes rencontrés et correctifs appliqués. Cette traçabilité simple sauve plusieurs heures de débogage en cas d’incident ultérieur.

Cette discipline opérationnelle quotidienne est ce qui distingue les PME qui scalent durablement de celles qui s’enlisent dans la dette technique au bout de deux ans.

Pour aller plus loin

🔝 Retour à l’article principal : Hasura DDN + PostgreSQL pour PME. La suite logique aborde les permissions row-level pour limiter chaque utilisateur à ses propres données. Documentation Hasura officielle : hasura.io/docs/2.0, image Docker : hub.docker.com/r/hasura/graphql-engine.

Documenter l’installation dans un wiki d’équipe avec captures d’écran et commandes exactes. Ce document devient précieux quand l’équipe grossit ou qu’un nouveau développeur reprend l’instance trois ans plus tard. Inclure la procédure de restauration, les contacts des prestataires, les identifiants des comptes critiques (chiffrés évidemment). Cette traçabilité simple transforme un déploiement individuel en savoir collectif réutilisable, et constitue l’un des actifs les plus précieux d’une PME en phase de scaling rapide.