Coolify est devenu en 2025-2026 la plateforme self-hosted de référence pour les équipes qui veulent l’expérience Heroku ou Vercel sur leur propre infrastructure, sans payer un abonnement cloud par usage. Pour une PME ouest-africaine qui héberge déjà sa stack web sur un VPS Hetzner ou Contabo, ajouter ClickHouse comme base analytique columnar via Coolify évite la complexité d’un cluster Kubernetes et reste sous les 25 EUR par mois pour une instance utile en production. Ce tutoriel pas-à-pas montre comment déployer ClickHouse 25.x via Coolify, sécuriser l’accès, brancher l’observabilité et tester la première ingestion analytique en moins d’une heure.

Le parcours couvre l’ensemble du chemin opérationnel : prérequis VPS, installation de Coolify si elle n’est pas déjà en place, déploiement du conteneur ClickHouse, exposition sécurisée via Traefik intégré, configuration des sauvegardes, et premier test d’ingestion. Chaque commande est accompagnée d’une explication contextuelle avant et après, avec les sorties attendues et les signaux de réussite ou d’échec à surveiller. À la fin, vous disposez d’une instance ClickHouse exploitée par Coolify, supervisée par les dashboards intégrés, prête à recevoir vos pipelines analytiques.

📍 Guide principal : ClickHouse 2026 : analytics columnar haute performance — pour comprendre l’architecture columnar, les MergeTree et les materialized views avant de plonger dans le déploiement.

Pourquoi déployer ClickHouse via Coolify plutôt qu’en direct

Coolify n’est pas une couche d’abstraction inutile. Trois raisons concrètes justifient son usage face à un docker run manuel ou un docker-compose.yml maintenu à la main. La première est l’expérience d’exploitation : Coolify gère l’envoi de variables d’environnement, la rotation des secrets, les redémarrages, les déploiements bleu-vert, sans toucher de fichiers shell. La deuxième est l’intégration native du reverse proxy : les conteneurs sont automatiquement publiés derrière Traefik (le proxy par défaut, Caddy disponible en option) avec certificat TLS Let’s Encrypt généré à la volée, ce qui évite la friction du provisioning manuel. La troisième est la console graphique partagée avec l’équipe : un développeur qui veut redémarrer un service ou consulter les logs n’a pas besoin de SSH.

Le choix Coolify a aussi ses limites. La plateforme n’orchestre pas un cluster ClickHouse multi-noeuds avec Keeper et ReplicatedMergeTree — pour cette topologie en haute disponibilité, lire le tutoriel cluster ClickHouse + Keeper. Coolify est l’outil idéal pour une instance unique productive ou un environnement de staging. Pour de la haute volumétrie distribuée, on bascule sur du déploiement direct via Ansible ou un manifeste Kubernetes.

Prérequis avant de commencer

Un VPS Linux récent : Debian 12 ou Ubuntu 24.04 LTS, 4 vCPU et 8 Go de RAM minimum. Hetzner CX32 (≈ 6,80 EUR/mois) ou Contabo VPS S font le travail.
Disque NVMe local 80 Go minimum, dont 60 Go libres pour les données ClickHouse.
Un nom de domaine pointant vers l’IP publique du VPS, avec un sous-domaine dédié (par exemple clickhouse.exemple.com). DNS propagé avant l’étape 4.
Coolify v4 déjà installé et accessible via son interface web, ou installation à effectuer en Étape 1 ci-dessous.
Accès SSH avec clé Ed25519 (jamais par mot de passe) — voir le tutoriel SSH Linux si besoin de configurer les clés.
Pare-feu ufw activé avec ports 22 (SSH), 80, 443 ouverts vers Internet ; tous les autres fermés.

Ce tutoriel suppose que vous savez faire un SSH, lire un log avec journalctl, et que vous avez une notion basique de Docker. Aucune expertise ClickHouse n’est requise — l’objectif est précisément de démarrer.

Étape 1 — Installer Coolify si ce n’est pas déjà fait

Si Coolify tourne déjà sur votre VPS, sautez cette étape. Sinon, l’installation officielle est un script unique fourni par l’équipe Coolify. Le script provisionne Docker, télécharge les images Coolify, démarre les services et expose la console sur le port 8000 du serveur.

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

Le script imprime à la fin l’URL d’accès initial, généralement http://<ip-vps>:8000, ainsi qu’un mot de passe initial à conserver. Connectez-vous immédiatement, créez un compte administrateur avec un mot de passe long, puis bloquez le port 8000 derrière un sous-domaine sécurisé (coolify.exemple.com) avec TLS — Coolify le propose nativement dans Settings → General. Vérifiez que la console est accessible en HTTPS avant de continuer.

Étape 2 — Préparer un projet Coolify pour ClickHouse

Coolify regroupe les services par projet et environnement, ce qui facilite l’isolation entre développement, staging et production. Avant de créer le service ClickHouse, créez un projet dédié pour cantonner ses ressources. C’est une bonne pratique qui paie dès qu’on multiplie les services.

Dans la console Coolify, cliquez sur Projects → + New. Nommez-le analytics-prod. Créez ensuite un environnement production à l’intérieur. Coolify supporte plusieurs environnements par projet, ce qui permet d’avoir un staging et un prod côte à côte sur le même VPS si vos ressources le permettent.

Une fois le projet en place, allez dans Servers et vérifiez que votre VPS apparaît avec l’état Connected. Si vous opérez sur un Coolify mono-serveur installé sur la même machine, le serveur localhost est déjà disponible. Pour un Coolify central qui pilote plusieurs VPS distants, ajoutez le serveur cible avec sa clé SSH et attendez la validation Connected avant de continuer.

Étape 3 — Déployer ClickHouse comme service managé Coolify

Coolify v4 inclut ClickHouse dans son catalogue de services managés, ce qui signifie que la création se fait via un formulaire structuré plutôt qu’en collant un docker-compose.yml brut. Cela donne un déploiement propre avec persistence configurée, secrets générés automatiquement et ports correctement exposés.

Dans le projet analytics-prod → production, cliquez + New Resource → Database → ClickHouse. Renseignez le nom de l’instance (par exemple ch-main), gardez la version par défaut proposée par Coolify (24.x ou 25.x LTS selon la mise à jour de la plateforme), et acceptez les volumes persistants par défaut sur /var/lib/clickhouse. Coolify génère automatiquement un mot de passe aléatoire pour le compte default — copiez-le dans votre coffre-fort de secrets immédiatement, vous ne pourrez plus le récupérer en clair après fermeture de la modale.

Cliquez Deploy. Coolify télécharge l’image officielle clickhouse/clickhouse-server depuis Docker Hub, démarre le conteneur, monte les volumes, applique les variables d’environnement et bascule l’état sur Running en deux à trois minutes. Suivez la progression dans l’onglet Deployments. Si le déploiement échoue, vérifiez les logs Docker dans Logs et confirmez que l’image a bien été téléchargée — les pannes les plus fréquentes sont une saturation disque ou une coupure DNS pendant le pull.

Étape 4 — Exposer ClickHouse en HTTPS avec Traefik intégré

Par défaut, Coolify expose le port HTTP 8123 et le port natif 9000 du conteneur ClickHouse uniquement sur le réseau interne du serveur. Pour interroger ClickHouse depuis vos applications sur Internet (ou depuis un client SQL local via tunnel SSH), il faut activer la publication via Traefik avec un sous-domaine et TLS.

Dans la fiche de l’instance ch-main → onglet Network, ajoutez un mapping pour le port 8123 (interface HTTP de ClickHouse, idéale pour les clients REST) avec le domaine clickhouse.exemple.com. Cochez Generate SSL Certificate. Coolify met à jour la configuration Traefik (proxy par défaut) en quelques secondes, génère le certificat Let’s Encrypt automatiquement et publie l’endpoint HTTPS.

curl -u default:<votre-mot-de-passe> \
  --data 'SELECT version()' \
  https://clickhouse.exemple.com/

La requête doit renvoyer la chaîne de version courante, par exemple 24.8.5.115 ou plus récent. Si vous obtenez une erreur 401, vérifiez le mot de passe ; un 502 signale que Traefik n’arrive pas à joindre le conteneur, à débugger via les logs Coolify ; un timeout indique un problème DNS ou pare-feu, à inspecter avec dig clickhouse.exemple.com et sudo ufw status.

Étape 5 — Connexion via clickhouse-client et premier dataset

L’interface HTTP est pratique pour les requêtes ad-hoc et l’intégration applicative, mais le confort d’exploration reste meilleur avec clickhouse-client, le shell interactif officiel. Vous pouvez l’installer localement sur votre poste de travail via le paquet APT ou Homebrew, ou simplement entrer dans le conteneur via Coolify pour l’utiliser depuis le serveur.

Sur la fiche de l’instance, cliquez Terminal dans la barre d’actions Coolify. La console ouvre un shell directement dans le conteneur ClickHouse. Lancez clickhouse-client --password pour entrer en mode interactif. Une fois connecté, créez une base et une table pour valider l’écriture-lecture.

CREATE DATABASE IF NOT EXISTS analytics;

CREATE TABLE analytics.events
(
    event_time   DateTime,
    user_id      UInt64,
    event_type   LowCardinality(String),
    properties   String
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(event_time)
ORDER BY (event_type, event_time, user_id);

INSERT INTO analytics.events VALUES
(now(), 1001, 'login', '{"ip":"196.10.1.42"}'),
(now(), 1002, 'add_to_cart', '{"product":"sku-42"}'),
(now(), 1003, 'purchase', '{"amount":12500,"currency":"XOF"}');

SELECT event_type, count() FROM analytics.events GROUP BY event_type;

La dernière requête doit renvoyer trois lignes, une par event_type, avec count = 1 chacun. Si l’agrégation est instantanée, c’est attendu — ClickHouse est optimisé pour ce pattern. Vous tenez maintenant une instance opérationnelle, capable d’ingérer plusieurs millions de lignes par seconde dès que les pipelines amont sont branchés.

Étape 6 — Configurer les sauvegardes Coolify

La persistence Coolify repose sur des volumes Docker locaux. Sans sauvegarde externe, la perte du VPS équivaut à la perte de toutes les données. Coolify intègre une fonction de backup automatique vers S3 ou stockage compatible (Backblaze B2, Hetzner Storage Box avec rclone) — activez-la dès que l’instance contient des données utiles.

Dans la fiche ch-main → onglet Backups, ajoutez une destination de stockage (S3 endpoint + bucket + clés d’accès). Configurez la fréquence : un backup quotidien à 03h00 (heure UTC) avec rétention 30 jours est un bon point de départ. Coolify exécute alors un BACKUP DATABASE natif côté ClickHouse plus une copie des fichiers de configuration vers le stockage cible.

Testez la procédure de restauration deux fois par an minimum sur un VPS jetable — c’est le seul moyen de savoir que vos sauvegardes fonctionnent. Une équipe qui n’a jamais restauré ne sait pas. Documentez la procédure exacte dans un runbook accessible à toute l’équipe d’astreinte.

Étape 7 — Brancher l’observabilité Prometheus

Coolify expose des métriques basiques sur les conteneurs (CPU, mémoire, IO) mais pas les métriques applicatives ClickHouse. Pour piloter sérieusement l’instance en production, activez l’endpoint Prometheus natif de ClickHouse et faites scraper par votre stack monitoring existante ou par les dashboards Grafana intégrés à Coolify.

Dans la fiche ch-main → Configuration, ajoutez un fragment de configuration personnalisée qui sera monté dans /etc/clickhouse-server/config.d/prometheus.xml :

<clickhouse>
  <prometheus>
    <endpoint>/metrics</endpoint>
    <port>9363</port>
    <metrics>true</metrics>
    <events>true</events>
    <asynchronous_metrics>true</asynchronous_metrics>
  </prometheus>
</clickhouse>

Redémarrez l’instance via Coolify pour appliquer le fragment, puis exposez le port 9363 dans le réseau interne uniquement (pas en publication HTTPS). Configurez votre Prometheus existant pour scraper http://<conteneur-ip>:9363/metrics. Le dashboard Grafana de référence « ClickHouse internal exporter metrics » (ID 14192, publié par Grafana Labs) charge sans modification une fois la datasource Prometheus connectée.

Erreurs fréquentes en déploiement Coolify + ClickHouse

Symptôme	Cause probable	Correctif
Conteneur en boucle Restarting	Volume permission denied ou disque saturé	`df -h` + ajuster les permissions du volume Docker
Erreur Too many parts à l’INSERT	Inserts unitaires fréquents	Batcher en lots ≥ 10 000 lignes
HTTPS 502 Bad Gateway	Traefik ne joint pas le conteneur	Vérifier le réseau Docker et le port 8123 exposé
Mot de passe default oublié	Pas copié à la création	Réinitialiser via Coolify → Reset Password (perte des sessions actives)
Version de ClickHouse trop ancienne	Image Coolify pas à jour	Forcer le pull avec un tag explicit dans la config avancée

Adaptation au contexte ouest-africain

Pour une équipe à Dakar, Abidjan ou Bamako qui pilote un VPS Hetzner Falkenstein, la latence réseau de 50 à 80 ms reste acceptable pour des pipelines d’ingestion analytique en mode batch ou near-real-time. Pour des pipelines OLTP synchronisés où la latence importe, regarder les datacenters africains émergents comme Raxio Côte d’Ivoire (CIV1, ouvert en septembre 2024 à Abidjan) ou Africa Data Centres via Liquid Intelligent Technologies. Coolify s’installe sur n’importe quel VPS Linux, peu importe le datacenter cible.

Côté coût, un Hetzner CX32 à 4 500 FCFA par mois suffit pour démarrer une instance ClickHouse Coolify utile. Quand le hot data dépasse 100 Go ou la charge analytique devient soutenue, monter sur Hetzner CCX23 (vCPU dédié, 8 Go de RAM, ≈ 25 000 FCFA/mois) reste très compétitif face aux datawarehouses cloud. Pour comparer les options OLTP/OLAP/cloud, voir le comparatif ClickHouse vs PostgreSQL vs BigQuery.

Pour approfondir

Cette installation Coolify mono-instance couvre 80 % des besoins d’une PME ou d’une startup data-driven en démarrage. Quand la criticité monte (SLA, multi-replicas, lectures distribuées), le passage à un cluster trois noeuds avec ClickHouse Keeper devient justifié — voir le tutoriel cluster ClickHouse + Keeper. Pour les pipelines analytiques complets avec versionning et tests, le guide stack data 2026 détaille les alternatives selon les volumétries.

Mots-clés associés : Coolify v4, ClickHouse 25, Hetzner Falkenstein, Traefik TLS, MergeTree, monitoring Prometheus, sauvegarde S3, self-hosting analytics, OHADA conformité données.