Cómo instalar Apache Superset en Ubuntu 24.04 con Docker

Apache Superset es una plataforma de exploración y visualización de datos de código abierto: se conecta a bases de datos SQL, ofrece un editor SQL (SQL Lab) y permite construir gráficos y dashboards interactivos desde el navegador. En este tutorial desplegarás Superset 6.1 en Ubuntu 24.04 con el Docker Compose oficial del proyecto, sustituirás las claves y contraseñas de ejemplo, lo publicarás tras Nginx con HTTPS y crearás tu primer gráfico.

Requisitos previos

Para seguir esta guía necesitas:

• Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 4 vCPU y 8 GB de RAM y 20 GB libres en disco. Superset levanta varios contenedores (aplicación, workers de Celery, PostgreSQL y Redis).
• Un usuario no root con privilegios sudo.
• Docker Engine y el plugin Docker Compose instalados desde el repositorio oficial de Docker, y git.
• Un subdominio, por ejemplo superset.your_domain, con un registro DNS A que apunte a la IP del servidor, y los puertos 80 y 443 accesibles.

Nota

el proyecto Superset indica que su Docker Compose no está soportado oficialmente para producción. Es adecuado para un equipo pequeño o para evaluar la herramienta; para una instalación grande y con alta disponibilidad, Superset recomienda Kubernetes con su chart de Helm.

Paso 1: Descargar la versión estable de Superset

El repositorio de Superset incluye docker-compose-image-tag.yml, que usa las imágenes publicadas de una versión concreta en lugar de compilar el código. Clona solo la etiqueta de la versión 6.1.0:

cd ~
git clone --depth 1 --branch 6.1.0 https://github.com/apache/superset.git
cd superset

Comprueba que estás en la etiqueta correcta:

git describe --tags

6.1.0

Para instalar una versión más reciente, consulta las etiquetas en https://github.com/apache/superset/releases y usa la misma en el git clone y en la variable TAG del paso 3.

Paso 2: Sustituir las claves y contraseñas por defecto

El archivo docker/.env trae valores de desarrollo: la clave secreta TEST_NON_DEV_SECRET, contraseñas de PostgreSQL como superset y un administrador admin con contraseña admin. Los contenedores cargan además docker/.env-local si existe, y sus valores tienen prioridad, así que ese es el archivo que debes editar.

Genera la clave secreta, que Superset usa para firmar sesiones y cifrar las contraseñas de las bases de datos conectadas:

openssl rand -base64 42

Genera también tres contraseñas, una para cada uso:

openssl rand -hex 16
openssl rand -hex 16
openssl rand -hex 16

Crea docker/.env-local:

nano ~/superset/docker/.env-local

SUPERSET_SECRET_KEY=clave_generada_con_base64

# Base de datos de metadatos de Superset (los dos valores deben coincidir)
DATABASE_PASSWORD=primera_contraseña
POSTGRES_PASSWORD=primera_contraseña

# Usuario de la base de datos de ejemplos
EXAMPLES_PASSWORD=segunda_contraseña

# Contraseña del usuario admin que se crea en el primer arranque
ADMIN_PASSWORD=tercera_contraseña

# Modo no desarrollo y sin datos de ejemplo
SUPERSET_LOAD_EXAMPLES=no
FLASK_DEBUG=false

Protege el archivo:

chmod 600 ~/superset/docker/.env-local

Importante

define estos valores antes del primer arranque. PostgreSQL aplica POSTGRES_PASSWORD solo al crear su volumen, y cambiar SUPERSET_SECRET_KEY más adelante deja ilegibles las contraseñas de las conexiones ya guardadas.

Paso 3: Limitar el puerto a localhost y arrancar

El servicio superset publica el puerto 8088 en todas las interfaces. Docker gestiona sus propias reglas de iptables, por lo que ese puerto quedaría abierto a Internet aunque UFW lo bloquee. Publícalo solo en 127.0.0.1, ya que el acceso externo se hará a través de Nginx:

sed -i 's/- 8088:8088/- "127.0.0.1:8088:8088"/' ~/superset/docker-compose-image-tag.yml
grep -n '8088' ~/superset/docker-compose-image-tag.yml

67:      - "127.0.0.1:8088:8088"

Añade también un archivo de configuración propio para que Superset confíe en las cabeceras X-Forwarded-* de Nginx y genere las URLs con https. El entorno de Docker importa automáticamente superset_config_docker.py si lo encuentra en docker/pythonpath_dev:

nano ~/superset/docker/pythonpath_dev/superset_config_docker.py

ENABLE_PROXY_FIX = True

Arranca Superset indicando la versión de las imágenes:

cd ~/superset
TAG=6.1.0 docker compose -f docker-compose-image-tag.yml up -d

El contenedor superset_init aplica las migraciones, crea el usuario admin e inicializa roles y permisos. Sigue su progreso hasta que termine:

docker compose -f docker-compose-image-tag.yml logs -f superset-init

superset_init  | Init Step 3/3 [Complete] -- Setting up roles and perms

Pulsa Ctrl+C y comprueba el estado de los contenedores y el endpoint de salud:

docker compose -f docker-compose-image-tag.yml ps
curl http://127.0.0.1:8088/health

OK

En la salida de ps deberían aparecer superset_app, superset_worker, superset_worker_beat, superset_db y superset_cache en estado Up. superset_init sale con código 0 al terminar, y es lo esperado.

Paso 4: Publicar Superset con Nginx y HTTPS

Instala Nginx y Certbot:

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

Crea el bloque de servidor:

sudo nano /etc/nginx/sites-available/superset

server {
    listen 80;
    listen [::]:80;
    server_name superset.your_domain;

    location / {
        proxy_pass http://127.0.0.1:8088;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }
}

proxy_read_timeout evita que Nginx corte consultas largas de SQL Lab a los 60 segundos por defecto. Activa el sitio y recarga Nginx:

sudo ln -s /etc/nginx/sites-available/superset /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Abre los puertos web en UFW y solicita el certificado:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo certbot --nginx -d superset.your_domain

Congratulations! You have successfully enabled HTTPS on https://superset.your_domain

Abre https://superset.your_domain e inicia sesión con el usuario admin y la contraseña que pusiste en ADMIN_PASSWORD. Después, en el menú Settings, entra en Info y actualiza el correo del administrador, que por defecto es [email protected].

Paso 5: Conectar una base de datos

Superset se conecta a las bases de datos mediante URIs de SQLAlchemy. El arranque instala los controladores de PostgreSQL. Para otros motores, añade el paquete Python de su controlador a docker/requirements-local.txt (por ejemplo pymysql para MySQL o clickhouse-connect para ClickHouse, uno por línea) y recrea los contenedores con TAG=6.1.0 docker compose -f docker-compose-image-tag.yml up -d: el script de arranque instala ese archivo automáticamente.

Crea en tu base de datos un usuario de solo lectura para Superset. En PostgreSQL, por ejemplo:

CREATE ROLE superset_ro WITH LOGIN PASSWORD 'your_strong_password';
GRANT CONNECT ON DATABASE your_database TO superset_ro;
GRANT USAGE ON SCHEMA public TO superset_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO superset_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO superset_ro;

En Superset, abre Settings, entra en Database Connections y pulsa + Database. Elige PostgreSQL y rellena el formulario, o introduce directamente la URI:

postgresql://superset_ro:your_strong_password@db_host:5432/your_database

Pulsa Test connection. Si el resultado es correcto, guarda la conexión. El host db_host debe ser accesible desde los contenedores de Superset: si la base de datos está en otro servidor, permite en su firewall solo la IP de este servidor.

Paso 6: Crear un dataset, un gráfico y un dashboard

En Superset los gráficos se construyen sobre datasets, que representan una tabla o una consulta SQL.

1. En el menú Datasets, pulsa + Dataset, elige la conexión, el esquema y la tabla, y pulsa Create dataset and create chart.
2. Elige un tipo de visualización, por ejemplo Bar Chart.
3. Arrastra una columna de fecha al eje X, define una métrica (por ejemplo COUNT(*) o SUM(importe)) y pulsa Update chart.
4. Guarda el gráfico y, en el mismo diálogo, añádelo a un dashboard nuevo.

Para consultas libres, abre SQL, entra en SQL Lab, selecciona la base de datos y ejecuta una consulta:

SELECT date_trunc('month', fecha_venta) AS mes,
       SUM(importe) AS total
FROM ventas
GROUP BY 1
ORDER BY 1;

Desde el resultado puedes guardar la consulta como dataset y crear gráficos sobre ella.

Para dar acceso al equipo, crea usuarios en Settings, sección List Users. Superset incluye roles predefinidos: Admin (todo), Alpha (crea y edita contenido en todas las fuentes), Gamma (solo ve lo que se le concede) y sql_lab (acceso a SQL Lab). Lo habitual es combinar Gamma con permisos sobre fuentes concretas para los usuarios que solo consultan dashboards.

Paso 7: Copias de seguridad y actualizaciones

Los dashboards, gráficos, usuarios y conexiones viven en la base de datos de metadatos. Haz una copia desde el directorio del proyecto:

cd ~/superset
docker compose -f docker-compose-image-tag.yml exec -T db pg_dump -U superset superset | gzip > ~/superset-$(date +%F).sql.gz

Guarda también docker/.env-local fuera del servidor: sin SUPERSET_SECRET_KEY la copia no sirve para restaurar las conexiones.

Para actualizar, haz una copia, descarga la nueva etiqueta y recrea los contenedores con el nuevo TAG. El contenedor superset_init aplica las migraciones al arrancar. Revisa antes las notas de la versión (el archivo UPDATING.md del repositorio), porque las versiones mayores pueden requerir cambios de configuración. Tras actualizar el código, vuelve a aplicar el cambio del puerto 8088 del paso 3, ya que git restaura el archivo original.

Solución de problemas

superset_app se reinicia en bucle. Revisa docker compose -f docker-compose-image-tag.yml logs --tail 100 superset. Un error de autenticación contra db suele indicar que cambiaste POSTGRES_PASSWORD después del primer arranque; PostgreSQL mantiene la contraseña con la que se creó el volumen.

Aviso sobre SECRET_KEY por defecto en los logs. Superset no ha leído docker/.env-local. Comprueba el nombre y la ruta del archivo y recrea los contenedores con up -d.

Tras iniciar sesión vuelves a la pantalla de login o se redirige a http://. Falta ENABLE_PROXY_FIX = True o la cabecera X-Forwarded-Proto en Nginx. Revisa ambos y reinicia con docker compose -f docker-compose-image-tag.yml restart superset.

Las consultas largas terminan con 504 Gateway Timeout. Aumenta proxy_read_timeout en Nginx y recárgalo.

Conclusión

Tienes Apache Superset 6.1 en Ubuntu 24.04 con Docker Compose, con claves y contraseñas propias, accesible solo a través de Nginx con HTTPS y conectado a tus datos con un usuario de solo lectura. Como siguientes pasos puedes configurar el correo saliente para usar alertas e informes programados, añadir controladores para otras bases de datos o migrar a Kubernetes con el chart de Helm oficial si el uso crece.