Installer ClickHouse sur Ubuntu/Debian : Guide pas à pas par quelqu'un qui s'est brûlé avec les mauvaises permissions
Trois erreurs que j'ai commises lors de ma première installation
La première fois que j'ai installé ClickHouse en production, je me suis dit : "Qu'est-ce qu'il y a de si difficile ? Juste apt install." Résultat : les ports étaient fermés, les logs ne s'écrivaient pas, et après 15 minutes le serveur a planté parce que j'avais oublié de configurer max_server_memory_usage. Deuxième tentative : j'ai confondu le dépôt officiel avec un PPA douteux. Troisième : je n'ai pas défini ulimit -n, et ClickHouse n'a tout simplement pas pu ouvrir assez de descripteurs de fichiers.
Donc ci-dessous n'est pas juste une copie de la documentation, mais un guide où je souligne tous les pièges. Toutes les commandes ont été testées sur un Ubuntu 22.04 LTS et Debian 12 propres.
Étape 1. Ajouter le dépôt officiel (ne cherchez pas de scripts prêts à l'emploi)
La documentation officielle propose un script curl https://clickhouse.com/ | sh. Je ne recommande pas de l'utiliser sur un serveur si vous ne comprenez pas parfaitement ce qu'il fait. Mieux vaut faire une installation manuelle via apt avec vérification de la clé. C'est un cas où la sécurité est plus importante que la rapidité.
# Ajouter la clé GPG de ClickHouse (signature des paquets)
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL 'https://packages.clickhouse.com/rpm/latest/repodata/repomd.xml.key' | sudo gpg --dearmor -o /usr/share/keyrings/clickhouse-keyring.gpg
# Ajouter le dépôt aux sources apt
echo "deb [signed-by=/usr/share/keyrings/clickhouse-keyring.gpg] https://packages.clickhouse.com/deb stable main" | sudo tee /etc/apt/sources.list.d/clickhouse.list
# Mettre à jour la liste des paquets
sudo apt-get updatePourquoi tant de complications ? Parce que sans vérification de signature, vous risquez d'installer un paquet depuis un dépôt non officiel. En production, nous avons eu un cas où un développeur a exécuté curl | sh et a obtenu une ancienne version avec une vulnérabilité. Ne reproduisez pas cela.
Étape 2. Installer le serveur et le client
# Installer les paquets
sudo apt-get install -y clickhouse-server clickhouse-client
# Si vous voulez les utilitaires de benchmark
sudo apt-get install -y clickhouse-common-staticPendant l'installation, il vous sera demandé un mot de passe pour l'utilisateur default. Note importante : Si vous le laissez vide, aucun mot de passe ne sera défini. En production, c'est une catastrophe. Même pour un environnement de développement, définissez un mot de passe simple comme clickhouse_dev — ce sera plus facile à retenir plus tard.
Après l'installation, vous verrez :
ClickHouse server has been installed.
Configuration file: /etc/clickhouse-server/config.xml
Logs directory: /var/log/clickhouse-server/
Data directory: /var/lib/clickhouse/Étape 3. Vérifier la version — une astuce que la documentation ne mentionne pas
clickhouse-server --versionSortie attendue (au moment de la rédaction) :
ClickHouse server version 24.8.2.3 (official build).Expérience personnelle : Après une mise à jour de la version de ClickHouse, le format de stockage des données sur disque change parfois. Si vous aviez une ancienne version et que vous avez exécuté apt upgrade, le système pourrait ne pas démarrer avec l'erreur Unknown data type. Exécutez toujours clickhouse-server --version avant de mettre à jour et lisez le changelog.
Étape 4. Démarrer via systemd — et vérifiez que vous n'avez rien oublié
# Activer le démarrage automatique au boot
sudo systemctl enable clickhouse-server
# Démarrer le serveur maintenant
sudo systemctl start clickhouse-server
# Vérifier le statut
sudo systemctl status clickhouse-serverSi tout va bien, vous verrez :
● clickhouse-server.service - ClickHouse Server (analytic DBMS)
Loaded: loaded (/etc/systemd/system/clickhouse-server.service; enabled)
Active: active (running) since ... Erreur courante : Le serveur ne démarre pas à cause d'un nombre insuffisant de descripteurs de fichiers. Vérifiez :
# Voir la limite actuelle pour le service
cat /proc/$(pidof clickhouse-server)/limits | grep "open files"
# Si moins de 262144, ajoutez dans /etc/systemd/system/clickhouse-server.service.d/override.conf
[Service]
LimitNOFILE=262144
LimitNPROC=32768Après modifications, n'oubliez pas :
sudo systemctl daemon-reload
sudo systemctl restart clickhouse-serverÉtape 5. Première connexion via clickhouse-client — et mon test préféré
clickhouse-client --password
# Entrez le mot de passe défini à l'étape 2Si vous n'avez pas défini de mot de passe, faites simplement :
clickhouse-clientLa première requête est toujours une vérification de version :
SELECT version();Sortie :
┌─version()─┐
│ 24.8.2.3 │
└───────────┘Maintenant, vous pouvez être fier — ClickHouse fonctionne.
Test de performance bonus : Exécutez cette requête — elle montrera à quelle vitesse votre machine peut générer et traiter des données :
SELECT sum(number) FROM numbers(100000000);Sur un serveur décent (4 cœurs ou plus), elle s'exécutera en 0,3 à 0,5 seconde. Sur une machine virtuelle faible — jusqu'à 2 secondes. Si c'est plus de 5 secondes, vous avez des problèmes de CPU ou de limitation.
Étape 6. Où se trouvent les fichiers importants — mémorisez ces chemins
| Fichier/Répertoire | Objectif | Ce que j'ai modifié le plus souvent |
|---|---|---|
/etc/clickhouse-server/config.xml |
Configuration principale | listen_host (pour écouter sur plus que localhost), max_server_memory_usage, http_port |
/etc/clickhouse-server/users.xml |
Paramètres utilisateur | password pour default, readonly, quota |
/var/log/clickhouse-server/clickhouse-server.log |
Log principal | Quand il ne démarre pas, vérifiez ici d'abord |
/var/log/clickhouse-server/clickhouse-server.err.log |
Log d'erreurs | J'y attrape les erreurs mémoire et disque |
/var/lib/clickhouse/ |
Données des tables | Vérifiez si le disque est plein |
/var/lib/clickhouse/status |
PID et statut | Pour les scripts de surveillance |
Moment réel : Une fois, ClickHouse a cessé d'accepter les requêtes. Tout tournait, mais la console se bloquait. Il s'est avéré que le fichier de log avait atteint 80 Go et rempli la partition racine. Ajoutez une rotation dans la configuration :
<logger>
<size>1000M</size>
<count>10</count>
</logger>Étape 7. Configuration minimale pour le développement
Pour une machine locale ou un serveur de développement, j'utilise ce config.xml (je ne modifie que ce qui est critique) :
<!-- /etc/clickhouse-server/config.d/dev-override.xml -->
<clickhouse>
<!-- Écouter sur toutes les interfaces, pas seulement localhost -->
<listen_host>0.0.0.0</listen_host>
<!-- Limiter la mémoire pour éviter de tuer le portable -->
<max_server_memory_usage>0.75</max_server_memory_usage> <!-- 75% de la RAM totale -->
<max_memory_usage_for_all_queries>0</max_memory_usage_for_all_queries>
<!-- Timeouts pour l'environnement de développement -->
<keep_alive_timeout>3</keep_alive_timeout>
<!-- Éviter de créer trop de partitions sur le disque -->
<merge_tree>
<max_parts_in_total>1000</max_parts_in_total>
</merge_tree>
</clickhouse>Appliquer :
sudo systemctl restart clickhouse-serverPourquoi un fichier séparé plutôt que de modifier config.xml ? Lors de la mise à jour du paquet, config.xml peut être écrasé. Placez toutes les modifications personnalisées dans /etc/clickhouse-server/config.d/. J'ai appris cela après une rétrogradation suite à une mise à jour échouée — j'ai perdu une semaine de réglages.
Étape 8. Ouvrir les ports pour les connexions externes
ClickHouse écoute sur trois ports :
- 8123 — HTTP (pour l'API REST, Grafana, intuitif)
- 9000 — Protocole TCP natif (pour clickhouse-client et les pilotes)
- 9009 — Communication inter-serveur (pour les clusters, ne touchez pas inutilement)
Sur une machine de développement, j'ouvre au moins le 8123 pour me connecter depuis TablePlus ou DBeaver :
# Vérifier si le processus écoute
sudo netstat -tulpn | grep clickhouse
# Sinon, autoriser dans UFW
sudo ufw allow 8123/tcp
sudo ufw allow 9000/tcpErreur courante : Sur Ubuntu 22.04, le pare-feu peut bloquer par défaut même si ClickHouse écoute sur 0.0.0.0. Vérifiez toujours avec telnet localhost 8123 et telnet $(hostname -I) 8123.
Problèmes d'installation typiques et comment je les ai résolus
Problème 1 : Code: 210. DB::NetException: Connection refused
Cause : Le serveur n'a pas démarré ou écoute uniquement sur 127.0.0.1.
Solution :
# Vérifier le statut
systemctl status clickhouse-server
# Voir le log
tail -n 50 /var/log/clickhouse-server/clickhouse-server.log
# Modifier la configuration
sudo nano /etc/clickhouse-server/config.xml
# Trouver <listen_host>0.0.0.0</listen_host> et décommenterProblème 2 : cannot create directory '/var/lib/clickhouse/' Permission denied
Cause : Les permissions sur le répertoire de données ont été modifiées après une intervention manuelle.
Solution :
sudo chown -R clickhouse:clickhouse /var/lib/clickhouse
sudo chmod 755 /var/lib/clickhouseProblème 3 : Le serveur démarre mais plante après 30 secondes avec Out of memory
Cause : ClickHouse par défaut veut utiliser presque toute la RAM.
Solution : Dans un environnement de développement, limitez strictement la mémoire :
# Dans /etc/clickhouse-server/config.xml ajouter
<max_server_memory_usage>2147483648</max_server_memory_usage> # 2 GoOu via une limite système :
sudo systemctl edit clickhouse-server
# Ajouter :
[Service]
MemoryMax=2GProblème 4 : L'installation échoue à cause d'un conflit avec clickhouse-common-static
Cause : Restes d'une version précédente ou cache apt corrompu.
Solution :
sudo apt-get remove --purge clickhouse-*
sudo rm -rf /etc/clickhouse-server /var/lib/clickhouse
sudo apt-get clean
# Répéter l'installation depuis le débutVérification de santé — ma checklist personnelle
Après l'installation, j'exécute toujours trois tests :
Connexion locale
clickhouse-client -q "SELECT 1" # Devrait retourner 1Connexion HTTP distante (depuis une autre machine)
curl "http://VOTRE_IP_SERVEUR:8123/?query=SELECT+version()"Écriture de données
CREATE DATABASE test; CREATE TABLE test.t (id UInt64) ENGINE = MergeTree ORDER BY id; INSERT INTO test.t SELECT number FROM numbers(1000); SELECT count() FROM test.t;
Si tout passe, l'installation est réussie.
Et ensuite ?
Maintenant vous avez un ClickHouse fonctionnel sur Ubuntu/Debian. La prochaine étape est d'apprendre à l'encapsuler dans Docker et à configurer un cluster à trois nœuds avec réplication.
➡️ Article suivant : [Installer ClickHouse via Docker : Cluster de production en 10 minutes] (lien à venir)
⬅️ Article précédent : [Qu'est-ce que ClickHouse : Pourquoi les bases de données columnaires déchirent l'analyse] (lien à venir)
Bonne chance avec l'installation. Si vous bloquez, vérifiez d'abord /var/log/clickhouse-server/clickhouse-server.err.log. Cette erreur m'a sauvé plus de fois que le café le lundi matin.
← Précédente: ClickHouse : pourquoi les SGBD columnaires déchirent l'analyse de données
→ Suivante: ClickHouse dans Docker : comment j'ai arrêté de m'inquiéter et lancé l'analyse en 2 minutes
— Editorial Team
Aucun commentaire pour le moment.