Instalación de ClickHouse en Ubuntu 22.04 y Debian 12: guía

Instalación de ClickHouse en Ubuntu/Debian: Guía paso a paso de alguien que se quemó con permisos incorrectos

La primera vez que instalé ClickHouse en producción, pensé: "¿Qué tiene de difícil? Solo apt install". Resultado: los puertos estaban cerrados, los logs no se escribían y después de 15 minutos el servidor se cayó porque olvidé configurar max_server_memory_usage. Segundo intento: confundí el repositorio oficial con un PPA sospechoso. Tercero: no configuré ulimit -n, y ClickHouse simplemente no pudo abrir suficientes descriptores de archivo.

Así que lo que sigue no es solo una copia de la documentación, sino una guía donde señalo todos los escollos. Todos los comandos han sido probados en un Ubuntu 22.04 LTS y Debian 12 limpios.

Paso 1. Agregar el repositorio oficial (no busques scripts prefabricados en Google)

La documentación oficial tiene un script curl https://clickhouse.com/ | sh. No recomiendo usarlo en un servidor si no entiendes completamente lo que hace. Es mejor hacer una instalación manual mediante apt con verificación de clave. Este es un caso donde la seguridad es más importante que la velocidad.

# Agregar la clave GPG de ClickHouse (firma del paquete)
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

# Agregar el repositorio a las fuentes de 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

# Actualizar la lista de paquetes
sudo apt-get update

¿Por qué tan complicado? Porque sin verificación de firma, corres el riesgo de instalar un paquete de un repositorio no oficial. En producción, tuvimos un caso donde un desarrollador ejecutó curl | sh y obtuvo una versión antigua con una vulnerabilidad. No repitas eso.

Paso 2. Instalar el servidor y el cliente

# Instalar paquetes
sudo apt-get install -y clickhouse-server clickhouse-client

# Si quieres utilidades de benchmarking
sudo apt-get install -y clickhouse-common-static

Durante la instalación, se te pedirá una contraseña para el usuario default. Nota importante: Si la dejas vacía, no se establecerá ninguna contraseña. En producción, esto es un desastre. Incluso para un entorno de desarrollo, establece una contraseña simple como clickhouse_dev — será más fácil recordarla después.

Después de la instalación, verás:

ClickHouse server has been installed.
Configuration file: /etc/clickhouse-server/config.xml
Logs directory: /var/log/clickhouse-server/
Data directory: /var/lib/clickhouse/

Paso 3. Verificar la versión — un truco que la documentación no menciona

clickhouse-server --version

Salida esperada (al momento de escribir):

ClickHouse server version 24.8.2.3 (official build).

Experiencia personal: Después de actualizar la versión de ClickHouse, el formato de almacenamiento de datos en disco a veces cambia. Si tenías una versión anterior y ejecutaste apt upgrade, el sistema podría no iniciar con el error Unknown data type. Siempre ejecuta clickhouse-server --version antes de actualizar y lee el changelog.

Paso 4. Iniciar mediante systemd — y verifica que no olvidaste nada

# Habilitar inicio automático al arrancar
sudo systemctl enable clickhouse-server

# Iniciar el servidor ahora
sudo systemctl start clickhouse-server

# Verificar estado
sudo systemctl status clickhouse-server

Si todo está bien, verás:

● clickhouse-server.service - ClickHouse Server (analytic DBMS)
     Loaded: loaded (/etc/systemd/system/clickhouse-server.service; enabled)
     Active: active (running) since ... 

Error común: El servidor no arranca debido a descriptores de archivo insuficientes. Verifica:

# Ver el límite actual para el servicio
cat /proc/$(pidof clickhouse-server)/limits | grep "open files"

# Si es menor a 262144, agrega a /etc/systemd/system/clickhouse-server.service.d/override.conf
[Service]
LimitNOFILE=262144
LimitNPROC=32768

Después de hacer cambios, no olvides:

sudo systemctl daemon-reload
sudo systemctl restart clickhouse-server

Paso 5. Primer inicio de sesión mediante clickhouse-client — y mi prueba favorita

clickhouse-client --password
# Ingresa la contraseña que configuraste en el paso 2

Si no configuraste contraseña, simplemente:

clickhouse-client

La primera consulta siempre es verificar la versión:

SELECT version();

Salida:

┌─version()─┐
│ 24.8.2.3  │
└───────────┘

Ahora puedes sentirte orgulloso — ClickHouse está funcionando.

Prueba de rendimiento adicional: Ejecuta esta consulta — mostrará qué tan rápido tu máquina puede generar y procesar datos:

SELECT sum(number) FROM numbers(100000000);

En un servidor decente (4+ núcleos), se ejecutará en 0.3-0.5 segundos. En una máquina virtual débil — hasta 2 segundos. Si es más de 5 segundos, tienes problemas de CPU o limitación.

Paso 6. Dónde se encuentran los archivos importantes — memoriza estas rutas

Archivo/Directorio	Propósito	Lo que cambié más a menudo
/etc/clickhouse-server/config.xml	Configuración principal	listen_host (para escuchar en más que solo localhost), max_server_memory_usage, http_port
/etc/clickhouse-server/users.xml	Configuración de usuarios	password para default, readonly, quota
/var/log/clickhouse-server/clickhouse-server.log	Log principal	Cuando no arranca, revisa aquí primero
/var/log/clickhouse-server/clickhouse-server.err.log	Log de errores	Aquí capturo errores de memoria y disco
/var/lib/clickhouse/	Datos de tablas	Verifica si el disco está lleno
/var/lib/clickhouse/status	PID y estado	Para scripts de monitoreo

Momento real: Una vez, ClickHouse dejó de aceptar solicitudes. Todo funcionaba, pero la consola se colgaba. Resultó que el archivo de log había crecido a 80 GB y llenó la partición raíz. Agrega rotación en la configuración:

<logger>
    <size>1000M</size>
    <count>10</count>
</logger>

Paso 7. Configuración mínima para desarrollo

Para una máquina local o servidor de desarrollo, uso este config.xml (solo cambio lo crítico):

<!-- /etc/clickhouse-server/config.d/dev-override.xml -->
<clickhouse>
    <!-- Escuchar en todas las interfaces, no solo localhost -->
    <listen_host>0.0.0.0</listen_host>
    
    <!-- Limitar memoria para no matar el portátil -->
    <max_server_memory_usage>0.75</max_server_memory_usage>  <!-- 75% de la RAM total -->
    <max_memory_usage_for_all_queries>0</max_memory_usage_for_all_queries>
    
    <!-- Timeouts para entorno de desarrollo -->
    <keep_alive_timeout>3</keep_alive_timeout>
    
    <!-- Evitar crear demasiadas particiones en disco -->
    <merge_tree>
        <max_parts_in_total>1000</max_parts_in_total>
    </merge_tree>
</clickhouse>

Aplica:

sudo systemctl restart clickhouse-server

¿Por qué un archivo separado en lugar de editar config.xml? Cuando se actualiza el paquete, config.xml puede ser sobrescrito. Pon todos los cambios personalizados en /etc/clickhouse-server/config.d/. Aprendí esto tras una degradación después de una actualización fallida — perdí una semana de configuraciones.

Paso 8. Abrir puertos para conexiones externas

ClickHouse escucha en tres puertos:

• 8123 — HTTP (para REST API, Grafana, intuitivo)
• 9000 — Protocolo TCP nativo (para clickhouse-client y drivers)
• 9009 — Comunicación entre servidores (para clústeres, no tocar innecesariamente)

En una máquina de desarrollo, abro al menos el 8123 para conectarme desde TablePlus o DBeaver:

# Verificar si el proceso está escuchando
sudo netstat -tulpn | grep clickhouse

# Si no, permitir en UFW
sudo ufw allow 8123/tcp
sudo ufw allow 9000/tcp

Error común: En Ubuntu 22.04, el firewall puede bloquear por defecto incluso si ClickHouse escucha en 0.0.0.0. Siempre verifica con telnet localhost 8123 y telnet $(hostname -I) 8123.

Problemas típicos de instalación y cómo los resolví

Problema 1: Code: 210. DB::NetException: Connection refused

Causa: El servidor no arrancó o solo escucha en 127.0.0.1.

Solución:

# Verificar estado
systemctl status clickhouse-server

# Ver log
tail -n 50 /var/log/clickhouse-server/clickhouse-server.log

# Editar configuración
sudo nano /etc/clickhouse-server/config.xml
# Buscar <listen_host>0.0.0.0</listen_host> y descomentar

Problema 2: cannot create directory '/var/lib/clickhouse/' Permission denied

Causa: Los permisos del directorio de datos se estropearon después de una intervención manual.

Solución:

sudo chown -R clickhouse:clickhouse /var/lib/clickhouse
sudo chmod 755 /var/lib/clickhouse

Problema 3: El servidor arranca pero se cuelga después de 30 segundos con Out of memory

Causa: ClickHouse por defecto quiere usar casi toda la RAM.

Solución: En un entorno de desarrollo, limita estrictamente la memoria:

# En /etc/clickhouse-server/config.xml agregar
<max_server_memory_usage>2147483648</max_server_memory_usage>  # 2 GB

O mediante límite del sistema:

sudo systemctl edit clickhouse-server
# Agregar:
[Service]
MemoryMax=2G

Problema 4: La instalación falla debido a conflicto con clickhouse-common-static

Causa: Restos de una versión anterior o caché de apt dañado.

Solución:

sudo apt-get remove --purge clickhouse-*
sudo rm -rf /etc/clickhouse-server /var/lib/clickhouse
sudo apt-get clean
# Repetir la instalación desde el principio

Verificación de salud — mi lista de verificación personal

Después de la instalación, siempre ejecuto tres pruebas:

1. Conexión local

   clickhouse-client -q "SELECT 1"
   # Debería devolver 1

2. Conexión HTTP remota (desde otra máquina)

   curl "http://TU_IP_DEL_SERVIDOR:8123/?query=SELECT+version()"

3. Escritura de datos

   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 todo pasa, la instalación es exitosa.

¿Qué sigue?

Ahora tienes un ClickHouse funcionando en Ubuntu/Debian. El siguiente paso es aprender a envolverlo en Docker y configurar un clúster de tres nodos con replicación.

➡️ Próximo artículo: [Instalación de ClickHouse mediante Docker: Clúster de producción en 10 minutos] (enlace próximamente)

⬅️ Artículo anterior: [Qué es ClickHouse: Por qué los DBMS columnares destrozan los análisis] (enlace próximamente)

Buena suerte con la instalación. Si te atascas, primero revisa /var/log/clickhouse-server/clickhouse-server.err.log. Ese error me ha salvado más veces que el café en un lunes por la mañana.

---

← Anterior: ClickHouse: Por qué los DBMS columnares destrozan la analítica
→ Siguiente: ClickHouse en Docker: Cómo dejé de preocuparme y lancé análisis en 2 minutos

— Editorial Team