Cómo montar SonarQube local con Docker para proyectos Vue/TypeScript

Cuando necesitas visibilizar la calidad del código de tus proyectos frontend pero la instancia corporativa de SonarQube está desactualizada (o directamente no soporta versiones modernas de TypeScript), montar una instancia local con Docker es la solución más rápida.

Esta guía documenta el proceso completo, incluyendo los problemas reales que encontré y cómo los resolví.

Requisitos previos

Docker instalado
OpenJDK 17+ (SonarQube lo necesita para empaquetar el análisis)
Un proyecto Vue con TypeScript
vitest configurado para tests

Paso 1: Levantar SonarQube con Docker

docker run -d \
  --name sonarqube \
  -p 9001:9000 \
  sonarqube:latest

Nota: uso el puerto 9001 porque el 9000 suele estar ocupado por otros servicios del stack de desarrollo.

Accede a http://localhost:9001 con las credenciales por defecto (admin / admin). El sistema te pedirá cambiar la contraseña.

Paso 2: Conectar con tu repositorio

SonarQube permite conectarse directamente a Azure DevOps, GitHub o GitLab. Sigue el asistente de configuración para vincular tu repositorio.

Paso 3: Configurar el proyecto

Al seleccionar un proyecto, SonarQube te proporcionará los datos para tu archivo de configuración. Para la estrategia de detección de código nuevo, selecciona “Number of days” si trabajas con un flujo de main branch.

Crear `sonar-project.properties`

En la raíz de tu proyecto web (si tu web está dentro de un monorepo con API, ubícalo en la carpeta client-app):

sonar.projectKey=mi-proyecto-front
sonar.projectName=Mi Proyecto Front
sonar.sources=src
sonar.tests=tests
sonar.test.inclusions=**/*.spec.ts,**/*.test.ts
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.host.url=http://localhost:9001
sonar.token=TU_TOKEN_AQUÍ

Generar un token

En SonarQube, ve a My Account > Security > Generate Tokens y crea un token para tu proyecto.

Paso 4: Configurar vitest para cobertura lcov

SonarQube necesita el formato lcov para procesar la cobertura de tests. Actualiza tu vitest.config.ts:

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'lcov', 'html'],
      reportsDirectory: './coverage',
    },
  },
});

Y añade un script combinado en package.json:

{
  "scripts": {
    "test:sonar": "vitest run --coverage && npx sonar-scanner"
  }
}

Paso 5: Instalar Java (si no lo tienes)

SonarQube Scanner necesita Java para empaquetar el análisis. Descarga OpenJDK 17 JRE desde Adoptium.

⚠️ Advertencia: durante mi primera instalación, la configuración de variables de entorno de Java rompió completamente otras herramientas de desarrollo. Me costó un día entero restaurar el entorno. Recomiendo usar un gestor de versiones de Java o Docker para el scanner.

Paso 6: Actualizar `.gitignore`

Añade los archivos generados por SonarQube:

.scannerwork/
coverage/

Qué mide SonarQube

SonarQube clasifica los problemas en tres tipos:

Tipo	Descripción
Bug	Punto de fallo real o potencial
Vulnerability	Agujero de seguridad explotable
Code Smell	Problema de mantenibilidad que dificulta cambios futuros

Complemento: Dependency-Track

Además de SonarQube, evaluamos Dependency-Track como complemento para el análisis de vulnerabilidades en dependencias. Mientras SonarQube se centra en el código que escribes, Dependency-Track analiza las dependencias que consumes.

Herramienta	Enfoque
SonarQube	Calidad y seguridad del código propio
Dependency-Track	Vulnerabilidades en dependencias (npm, NuGet, etc.)

La combinación de ambas herramientas ofrece una visión completa de la postura de seguridad del proyecto.

Conclusiones

Docker es la forma más rápida de tener SonarQube funcionando localmente.
La integración con vitest+lcov es directa y no requiere configuración compleja.
Cuidado con la instalación de Java — usa un gestor de versiones o Docker para el scanner.
SonarQube local es un buen primer paso antes de solicitar una instancia corporativa actualizada.
Complementa con Dependency-Track para cubrir también las vulnerabilidades de terceros.