Tutoriales de VPS
SonarQube Community en VPS: gates CI y copias recuperables
Instale Community Build 26.11 con PostgreSQL y Caddy. Cumpla límites, use tokens por proyecto, bloquee CI con gates fallidos y restaure la base y el volumen real de plugins.

SonarQube reúne análisis estático, pero un servicio utilizable también necesita límites Elasticsearch correctos, PostgreSQL, HTTPS, permisos, respuesta a CI y copias recuperables. La aceptación incluye un escaneo real y una Quality Gate rechazada que detenga la canalización.
El despliegue original fija Community Build 26.9.0.129388-community. Las versiones oficiales Community y Docker consultadas el 16 de noviembre de 2026 ofrecen 26.11.0.134175; Docker se publicó el 6 de noviembre. Para instalación nueva, use su imagen community explícita indicada abajo. Community Build publica mensualmente: evite etiquetas flotantes latest/community y no confunda sus versiones con SonarQube Server comercial.
- Revisar calidad estática antes de integrar/publicar, según capacidades de edición.
- Compartir Quality Gate entre Jenkins, GitHub Actions y otros CI.
- Mantener reglas, perfiles e historial comunes.
- Controlar infraestructura privada de análisis.
- Evaluar fiabilidad, seguridad, mantenibilidad, cobertura y duplicación del código nuevo.
Complementa pruebas, análisis de dependencias, seguridad dinámica y revisión humana. Jenkins automatiza; Harbor almacena y analiza imágenes.
| Producto | Uso | Ventaja | Responsabilidad |
|---|---|---|---|
| Community Build | Personas/equipos pequeños | Análisis propio gratuito | Host, base, actualización y recuperación |
| Server con licencia | Gobierno empresarial | Ramas, integraciones y seguridad según edición | Licencia y recursos |
| Cloud | Servicio administrado | Sin base de análisis que mantener | Datos en cloud y facturación |
Confirme lenguajes, ramas, PR e integraciones antes de comprar/migrar. Esta guía establece gate en rama principal y no promete idénticas funciones PR en todas las ediciones.
El mínimo pequeño original es 2 núcleos, 4GB y 30GB de disco con al menos 10% libre. La base en la misma VPS necesita margen.
| Uso | VPS inicial | Condición |
|---|---|---|
| Pocos repositorios personales | 2 núcleos, 4GB, 50GB NVMe, swap 2GB | Margen limitado para escaneo/actualización |
| Equipo pequeño | 4 núcleos, 8GB, 100GB NVMe | Base y servicio juntos |
| Análisis frecuente/muchos equipos | 8 núcleos, 16GB+, 200GB+ NVMe | Considere base independiente |
Importan tamaño del código, analizadores, jobs, latencia de base e I/O. Consulte dimensionamiento VPS. Swap ayuda con picos breves, sin reemplazar RAM.
El flujo lógico es CI/desarrollador → Caddy HTTPS → SonarQube → PostgreSQL privado:
开发者 / CI Runner
│ HTTPS 443
▼
Caddy
│ Docker 内网 HTTP 9000
▼
SonarQube
│ PostgreSQL 5432(仅 Docker 内网)
▼
PostgreSQL 17
Caddy se ejecuta en el host y conecta a loopback; PostgreSQL usa red Docker. Publique únicamente:
22/TCPpara SSH restringido.80/TCPpara ACME/redirecciones.443/TCPpara HTTPS de usuarios/runners autorizados.
Mantenga 5432, 9000 y Elasticsearch privados. SonarQube escucha en 127.0.0.1:9000.
Apunte el hostname a la IPv4 de entrada; publique AAAA con IPv6 operativo:
sonar.example.com → VPS 公网 IPv4
dig +short sonar.example.com A
Instale herramientas:
sudo apt update
sudo apt install -y ca-certificates curl gnupg openssl jq dnsutils
Instale Engine/Compose con Ubuntu oficial y compruebe:
docker version
docker compose version
Revise memoria/swap existentes antes de crear swap:
swapon --show
free -h
Los requisitos Linux oficiales actuales consultados coinciden con:
vm.max_map_count >= 524288.fs.file-max >= 131072.- Al menos 131072 descriptores abiertos por proceso.
- Al menos 8192 hilos.
Compruebe:
sysctl vm.max_map_count
sysctl fs.file-max
ulimit -n
ulimit -u
Haga persistentes los ajustes:
sudo tee /etc/sysctl.d/99-sonarqube.conf >/dev/null <<'EOF'
vm.max_map_count=524288
fs.file-max=131072
EOF
sudo sysctl --system
Compose define nofile/nproc. OpenVZ/LXC restringido puede impedir cambiar vm.max_map_count mediante sysctl. Confirme antes de contratar; no desactive bootstrap checks para ocultar incompatibilidad.
sudo mkdir -p /opt/sonarqube
sudo chown -R "$USER":"$USER" /opt/sonarqube
cd /opt/sonarqube
Use umask 077 antes de generar estos secretos iniciales. Sobrescribe .env; no regenere credenciales de una instancia existente:
POSTGRES_PASSWORD="$(openssl rand -base64 36 | tr -d '\n')"
SONAR_JWT_SECRET="$(openssl rand -base64 32 | tr -d '\n')"
printf 'POSTGRES_PASSWORD=%s\nSONAR_JWT_SECRET=%s\n' \
"$POSTGRES_PASSWORD" "$SONAR_JWT_SECRET" > .env
chmod 600 .env
unset POSTGRES_PASSWORD SONAR_JWT_SECRET
Conserve copias cifradas con acceso solo administrativo.
Cree compose.yaml:
services:
db:
image: postgres:17-alpine
container_name: sonarqube-db
restart: unless-stopped
environment:
POSTGRES_DB: sonarqube
POSTGRES_USER: sonarqube
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
volumes:
- sonarqube_db:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U sonarqube -d sonarqube"]
interval: 10s
timeout: 5s
retries: 10
start_period: 20s
networks:
- sonarnet
sonarqube:
image: sonarqube:26.9.0.129388-community
container_name: sonarqube-app
restart: unless-stopped
depends_on:
db:
condition: service_healthy
environment:
SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonarqube
SONAR_JDBC_USERNAME: sonarqube
SONAR_JDBC_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
SONAR_AUTH_JWTBASE64HS256SECRET: ${SONAR_JWT_SECRET:?set SONAR_JWT_SECRET in .env}
ports:
- "127.0.0.1:9000:9000"
volumes:
- sonarqube_data:/opt/sonarqube/data
- sonarqube_extensions:/opt/sonarqube/extensions
- sonarqube_logs:/opt/sonarqube/logs
- sonarqube_temp:/opt/sonarqube/temp
ulimits:
nofile:
soft: 131072
hard: 131072
nproc: 8192
healthcheck:
test: ["CMD-SHELL", "curl --fail --silent http://localhost:9000/api/system/status | grep -q '\"status\":\"UP\"'"]
interval: 30s
timeout: 10s
retries: 20
start_period: 180s
networks:
- sonarnet
networks:
sonarnet:
name: sonarqube-network
volumes:
sonarqube_db:
sonarqube_data:
sonarqube_extensions:
sonarqube_logs:
sonarqube_temp:
Para instalación nueva revisada, cambie la imagen Community explícita:
cd /opt/sonarqube
sed -i 's/sonarqube:26\.9\.0\.129388-community/sonarqube:26.11.0.134175-community/' compose.yaml
El rango original documentado es PostgreSQL 14–18; compruebe la matriz de su versión. Aquí se mantiene 17; su etiqueta principal puede recibir nuevos parches. Fije digest aprobado si necesita reproducción exacta.
El siguiente comando de configuración guarda secretos expandidos en un archivo temporal. Use umask 077, manténgalo privado y bórrelo tras revisar; para uso normal prefiera docker compose config --quiet:
docker compose config >/tmp/sonarqube-compose-rendered.yaml
docker compose pull
docker compose up -d
El arranque inicializa base e índices:
docker compose ps
docker compose logs -f --tail=200 sonarqube
Espere SonarQube is operational o API UP; salga de logs con Ctrl+C:
curl -fsS http://127.0.0.1:9000/api/system/status | jq
Instale Caddy desde repositorio oficial si falta. Añada sitio a /etc/caddy/Caddyfile y permita escribir el directorio de logs al servicio:
sonar.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:9000 {
header_up Host {host}
header_up X-Forwarded-Proto {scheme}
header_up X-Forwarded-For {remote_host}
}
log {
output file /var/log/caddy/sonarqube-access.log
format json
}
}
Valide/recargue:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
curl -I https://sonar.example.com
curl -fsS https://sonar.example.com/api/system/status | jq
Caddy termina TLS y transmite Host, X-Forwarded-Proto, X-Forwarded-For. Con otro proxy/CDN, configure confianza explícita para interpretar la IP original; no confíe en cabeceras arbitrarias del cliente. Consulte Caddy HTTPS.
Abra https://sonar.example.com y cambie inmediatamente credenciales admin/admin:
- Guarde contraseña nueva en gestor.
- Configure base URL en
Administration → Configuration → General → General. - Quite permisos anónimos innecesarios.
- Cree Project Analysis Token por proyecto CI.
- Defina caducidad y responsable.
- Evite User Token administrativo en CI.
https://sonar.example.com
El token completo se muestra al crear. Guárdelo en Credentials/Secrets, no en sonar-project.properties, Compose o logs.
Cree proyecto local:
Project key: my-api
Display name: My API
Main branch: main
Adapte sonar-project.properties a rutas reales:
sonar.projectKey=my-api
sonar.projectName=My API
sonar.sources=src
sonar.tests=tests
sonar.sourceEncoding=UTF-8
sonar.javascript.lcov.reportPaths=coverage/lcov.info
Genere antes el archivo de cobertura. No guarde sonar.token; use entorno restringido:
export SONAR_HOST_URL="https://sonar.example.com"
export SONAR_TOKEN="replace-with-project-analysis-token"
docker run --rm \
-e SONAR_HOST_URL \
-e SONAR_TOKEN \
-v "$PWD:/usr/src" \
sonarsource/sonar-scanner-cli:latest
unset SONAR_TOKEN
latest del scanner es demostración. Fije scanner/imagen revisados en producción y evite registrar tokens reales en historial shell.
Configure Settings → Secrets and variables → Actions:
SONAR_HOST_URL=https://sonar.example.com.SONAR_TOKEN= token del proyecto.
El workflow original .github/workflows/sonarqube.yml es:
name: SonarQube
on:
push:
branches: [main]
pull_request:
jobs:
scan:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Test
run: npm ci && npm test -- --coverage
- name: SonarQube Scan
uses: SonarSource/sonarqube-scan-action@v7
env:
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
Añada with al paso SonarQube Scan para esperar resultado y fallar si se rechaza:
with:
args: -Dsonar.qualitygate.wait=true
Subir análisis no demuestra gate aprobado. Para rama principal Community, quite pull_request hasta confirmar soporte de edición. PR desde forks no reciben secretos: no exponga tokens a código no confiable para evitar ese límite.
Runner hospedado necesita HTTPS accesible. Para servicio privado use runner propio confiable con rutas/CA correctas. Fije Actions por SHA revisado y adapte Node, pruebas y cobertura.
Instale/configure plugin SonarQube Scanner:
- Añada Secret Text del token en
Manage Jenkins → Credentials. - Configure URL/credencial en
Manage Jenkins → System → SonarQube servers.
Use Jenkinsfile:
pipeline {
agent any
stages {
stage('Test') {
steps {
sh 'npm ci'
sh 'npm test -- --coverage'
}
}
stage('SonarQube Analysis') {
steps {
withSonarQubeEnv('sonarqube-vps') {
sh 'npx sonar-scanner'
}
}
}
stage('Quality Gate') {
steps {
timeout(time: 10, unit: 'MINUTES') {
waitForQualityGate abortPipeline: true
}
}
}
}
}
Prepare scanner revisado en el agent; el npx sonar-scanner sin versión no debería descargar paquetes arbitrarios al ejecutar. Configure callback de waitForQualityGate:
https://jenkins.example.com/sonarqube-webhook/
Use secret aleatorio y credencial Jenkins/HMAC coincidentes; si se configura por paso, use webhookSecretId en waitForQualityGate. Provoque un gate fallido y confirme que CI se detiene; probar solo verde no demuestra bloqueo.
Sonar way se concentra en código nuevo. No exija borrar toda deuda histórica al comenzar:
- Aplique primero a New Code.
- Rechace problemas graves nuevos.
- Eleve cobertura desde una base medida.
- Mantenga duplicación práctica.
- Asigne revisión de hotspots.
- Haga fallar CI, además de notificar.
Use condiciones explicables y reproducibles.
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status numbered
Mantenga acceso SSH antes de activar UFW. Revise escucha:
sudo ss -lntp | grep -E ':(443|9000|5432)\b'
9000 debe mostrar 127.0.0.1:9000; 5432 no debe publicarse. VPN/proxy de identidad deben permitir acceso al CI confiable.
cd /opt/sonarqube
docker compose ps
docker compose logs --tail=200 sonarqube
docker compose logs --tail=200 db
web.log: web, autenticación, base.ce.log: análisis de fondo.es.log: arranque, índices y disco Elasticsearch.access.log: acceso web si habilitado.
docker exec sonarqube-app ls -lh /opt/sonarqube/logs
docker exec sonarqube-app tail -n 100 /opt/sonarqube/logs/web.log
docker exec sonarqube-app tail -n 100 /opt/sonarqube/logs/es.log
Supervise CPU, RAM libre, swap, disco/I/O, reinicios, conexiones y /api/system/status. Alerte antes de watermarks bloqueantes.
PostgreSQL conserva datos autoritativos; índices se reconstruyen. Preserve:
- Dumps PostgreSQL coherentes.
compose.yaml/.envcifrados.- Lista de plugins y volumen extensions.
- Caddy.
- Imágenes exactas aplicación/base.
- Manual y ensayo real de recuperación.
Prepare destino privado, con umask 077/permisos restrictivos:
sudo mkdir -p /opt/backups/sonarqube
sudo chown -R "$USER":"$USER" /opt/backups/sonarqube
cd /opt/sonarqube
BACKUP_DATE="$(date +%F-%H%M%S)"
docker compose exec -T db \
pg_dump -U sonarqube -d sonarqube -Fc \
> "/opt/backups/sonarqube/sonarqube-${BACKUP_DATE}.dump"
sha256sum "/opt/backups/sonarqube/sonarqube-${BACKUP_DATE}.dump" \
> "/opt/backups/sonarqube/sonarqube-${BACKUP_DATE}.dump.sha256"
Este helper histórico usa nombre lógico. Compose suele prefijarlo: use el volumen existente real para no copiar silenciosamente uno nuevo vacío:
docker run --rm \
-v sonarqube_extensions:/source:ro \
-v /opt/backups/sonarqube:/backup \
alpine:3.22 \
tar -czf /backup/sonarqube-extensions.tar.gz -C /source .
tar -czf "/opt/backups/sonarqube/sonarqube-config-${BACKUP_DATE}.tar.gz" \
-C /opt/sonarqube compose.yaml .env
Sustituya el primer comando helper por:
SONAR_EXTENSIONS_VOLUME="$(docker inspect sonarqube-app --format '{{range .Mounts}}{{if eq .Destination "/opt/sonarqube/extensions"}}{{.Name}}{{end}}{{end}}')"
test -n "$SONAR_EXTENSIONS_VOLUME"
docker volume inspect "$SONAR_EXTENSIONS_VOLUME" >/dev/null
docker run --rm \
--mount "type=volume,src=$SONAR_EXTENSIONS_VOLUME,dst=/source,readonly" \
--mount type=bind,src=/opt/backups/sonarqube,dst=/backup \
alpine:3.22 tar -czf /backup/sonarqube-extensions.tar.gz -C /source .
unset SONAR_EXTENSIONS_VOLUME
Compruebe archivos/checksums, conserve Caddy aparte, cifre y suba a almacenamiento independiente. Ensaye con la guía de copias.
Iguale versiones y use otro host/proyecto con volúmenes nuevos y nombres/puertos sin conflictos. Detenga SonarQube del destino:
cd /opt/sonarqube
docker compose stop sonarqube
Los comandos reemplazan sonarqube del destino; seleccione el archivo real:
docker compose exec -T db dropdb -U sonarqube --if-exists sonarqube
docker compose exec -T db createdb -U sonarqube sonarqube
docker compose exec -T db \
pg_restore -U sonarqube -d sonarqube --clean --if-exists \
< /opt/backups/sonarqube/sonarqube-YYYY-MM-DD-HHMMSS.dump
Restaure configuración/plugins y limpie solo índices reconstruibles comprobados:
docker compose run --rm --entrypoint sh sonarqube \
-c 'rm -rf /opt/sonarqube/data/es8/*'
docker compose up -d
docker compose logs -f --tail=200 sonarqube
es8 es la ruta de la imagen histórica; confírmela para la elegida antes de borrar. No lo sustituya por borrado completo del volumen. Revise login, proyectos/historial, permisos, nuevo scan y feedback CI.
No permita sustitución automática Watchtower:
- Lea notas intermedias.
- Compruebe base, plugins y recursos.
- Reserve disco de migración; referencia original: aproximadamente 50% libre en volumen de base.
- Copie y verifique la base.
- Actualice una copia restaurada.
- Cambie tag explícito.
- Descargue/inicie imagen elegida.
- Revise scan, gate, webhook, login y proyectos.
- Conserve imagen y base previas durante observación.
cd /opt/sonarqube
docker compose pull sonarqube
docker compose up -d sonarqube
docker compose logs -f --tail=200 sonarqube
Migración incompatible exige base anterior además de imagen anterior para rollback.
max virtual memory areas vm.max_map_count is too low
sysctl vm.max_map_count
sudo sysctl -w vm.max_map_count=524288
sudo sysctl --system
Compruebe persistencia tras reinicio y permisos del host.
docker inspect sonarqube-app --format '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}}'
docker compose logs --tail=300 sonarqube
free -h
dmesg -T | grep -i -E 'out of memory|killed process' | tail -n 30
Busque RAM, límites, disponibilidad de base, permisos o plugins.
docker compose ps db
docker compose logs --tail=200 db
docker compose exec db pg_isready -U sonarqube -d sonarqube
Revise .env y render privado docker compose config. No publique 5432.
curl -v https://sonar.example.com/api/system/status
curl -I https://sonar.example.com/batch/index
Pruebe desde runner: DNS, cadena, proxy saliente, cortafuegos y logs. CA interna necesita confianza correcta de scanner/JVM.
- Webhook debe terminar en
/sonarqube-webhook/. - Compruebe ruta SonarQube → Jenkins.
- Compruebe Host/TLS reenviados.
- Revise estado/cuerpo de webhook y access logs.
- Compruebe compatibilidad plugin/aplicación.
No prolongue waitForQualityGate a ciegas.
df -h
docker system df
docker exec sonarqube-app du -sh /opt/sonarqube/data /opt/sonarqube/logs /opt/sonarqube/extensions
docker exec sonarqube-db du -sh /var/lib/postgresql/data
Localice historial, base, logs, plugins e imágenes; use retención admitida, copia y ampliación, sin borrar volúmenes arbitrariamente.
- Valide DNS/HTTPS.
- Compruebe
vm.max_map_count,fs.file-max,nofile,nproc. - Fije imágenes aplicación/base.
- PostgreSQL interno y SonarQube loopback.
- Cambie administrador/base URL.
- Tokens por proyecto con caducidad.
- Complete scan real.
- Gate fallido debe bloquear CI.
- Configure/verifique HMAC webhook.
- Ensaye base externa y volumen real de plugins.
- Alerte disco, RAM, salud y reinicios.
- Actualice con versión/copia controladas.
Para pocos repositorios de baja frecuencia, con poco margen. Equipos pequeños pueden empezar en 4 núcleos/8GB/100GB NVMe y medir OOM/I/O.
Es para pruebas. Use base admitida por Community elegida; aquí PostgreSQL 17 con matriz original 14–18.
Use 127.0.0.1:9000 detrás de Caddy HTTPS.
Compruebe matriz de versión/producto. Análisis y gate de rama principal son independientes de prometer funciones comerciales PR/ramas.
No: base, configuración, secretos estables y plugins necesitan copia coherente/restauración aislada. Los índices pueden regenerarse.
Fije imágenes y ensaye cambios. Arrancar docker compose up -d no demuestra rollback seguro ni CI completo.