Tutoriais de VPS
SonarQube Community na VPS: gates CI e backups recuperáveis
Instale Community Build 26.11 com PostgreSQL e Caddy. Atenda limites, use tokens por projeto, bloqueie CI com gates falhos e restaure banco e volume real de plugins.

SonarQube reúne análise estática, mas um serviço utilizável também precisa de limites Elasticsearch corretos, PostgreSQL, HTTPS, permissões, retorno ao CI e backups recuperáveis. A aceitação inclui uma análise real e uma Quality Gate rejeitada que interrompa o pipeline.
A implantação original fixa Community Build 26.9.0.129388-community. As versões oficiais Community e Docker consultadas em 16 de novembro de 2026 oferecem 26.11.0.134175; Docker foi publicado em 6 de novembro. Em instalação nova, use sua imagem community explícita indicada abaixo. Community Build é mensal: evite tags flutuantes latest/community e não confunda suas versões com SonarQube Server comercial.
- Revisar qualidade estática antes de integrar/publicar, conforme a edição.
- Compartilhar Quality Gate entre Jenkins, GitHub Actions e outros CI.
- Manter regras, perfis e histórico comuns.
- Controlar infraestrutura privada de análise.
- Avaliar confiabilidade, segurança, manutenção, cobertura e duplicação do código novo.
Complementa testes, análise de dependências, segurança dinâmica e revisão humana. Jenkins automatiza; Harbor armazena e analisa imagens.
| Produto | Uso | Vantagem | Responsabilidade |
|---|---|---|---|
| Community Build | Pessoas/equipes pequenas | Análise própria gratuita | Host, banco, atualização e recuperação |
| Server licenciado | Governança empresarial | Branches, integrações e segurança conforme edição | Licença e recursos |
| Cloud | Serviço gerenciado | Sem banco de análise para operar | Dados na nuvem e cobrança |
Confira linguagens, branches, PRs e integrações antes de contratar/migrar. Este guia estabelece gate na branch principal sem prometer funções PR idênticas em todas as edições.
O mínimo pequeno original é 2 núcleos, 4GB e disco de 30GB com pelo menos 10% livre. Banco na mesma VPS exige folga.
| Uso | VPS inicial | Condição |
|---|---|---|
| Poucos repositórios pessoais | 2 núcleos, 4GB, NVMe de 50GB, swap 2GB | Folga limitada para análise/atualização |
| Equipe pequena | 4 núcleos, 8GB, NVMe de 100GB | Banco e serviço juntos |
| Análise frequente/muitas equipes | 8 núcleos, 16GB+, NVMe de 200GB+ | Considere banco independente |
Tamanho do código, analisadores, jobs, latência e I/O importam. Veja dimensionamento VPS. Swap ajuda em picos breves sem substituir RAM.
O fluxo lógico é CI/desenvolvedor → Caddy HTTPS → SonarQube → PostgreSQL privado:
开发者 / CI Runner
│ HTTPS 443
▼
Caddy
│ Docker 内网 HTTP 9000
▼
SonarQube
│ PostgreSQL 5432(仅 Docker 内网)
▼
PostgreSQL 17
Caddy roda no host e conecta ao loopback; PostgreSQL usa rede Docker. Publique somente:
22/TCPpara SSH restrito.80/TCPpara ACME/redirecionamento.443/TCPpara HTTPS de usuários/runners autorizados.
Mantenha 5432, 9000 e Elasticsearch privados. SonarQube escuta em 127.0.0.1:9000.
Aponte hostname à IPv4 de entrada; publique AAAA com IPv6 funcionando:
sonar.example.com → VPS 公网 IPv4
dig +short sonar.example.com A
Instale ferramentas:
sudo apt update
sudo apt install -y ca-certificates curl gnupg openssl jq dnsutils
Instale Engine/Compose pelo Ubuntu oficial e confira:
docker version
docker compose version
Veja memória/swap existentes antes de criar swap:
swapon --show
free -h
Os requisitos Linux oficiais atuais consultados correspondem a:
vm.max_map_count >= 524288.fs.file-max >= 131072.- Pelo menos 131072 descritores abertos por processo.
- Pelo menos 8192 threads.
Confira:
sysctl vm.max_map_count
sysctl fs.file-max
ulimit -n
ulimit -u
Torne configurações persistentes:
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 restrito pode impedir alterar vm.max_map_count com sysctl. Confira antes de contratar; não desative bootstrap checks para esconder incompatibilidade.
sudo mkdir -p /opt/sonarqube
sudo chown -R "$USER":"$USER" /opt/sonarqube
cd /opt/sonarqube
Use umask 077 antes da geração inicial. Ela sobrescreve .env; não gere novamente credenciais de instância 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
Preserve cópias criptografadas com acesso administrativo.
Crie 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:
Na instalação nova revisada, altere a imagem Community explícita:
cd /opt/sonarqube
sed -i 's/sonarqube:26\.9\.0\.129388-community/sonarqube:26.11.0.134175-community/' compose.yaml
O intervalo original documentado é PostgreSQL 14–18; confira a matriz escolhida. Aqui mantemos 17; a tag da versão principal ainda recebe patches. Fixe digest aprovado para reprodução exata.
O próximo comando grava segredos expandidos em arquivo temporário. Use umask 077, mantenha privado e apague após revisar; no uso normal prefira docker compose config --quiet:
docker compose config >/tmp/sonarqube-compose-rendered.yaml
docker compose pull
docker compose up -d
O início prepara banco/índices:
docker compose ps
docker compose logs -f --tail=200 sonarqube
Espere SonarQube is operational ou API UP; saia dos logs com Ctrl+C:
curl -fsS http://127.0.0.1:9000/api/system/status | jq
Instale Caddy pelo repositório oficial se necessário. Adicione o site a /etc/caddy/Caddyfile e permita escrita do diretório de logs ao serviço:
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/recarregue:
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 e envia Host, X-Forwarded-Proto, X-Forwarded-For. Com outro proxy/CDN, configure confiança explícita para identificar o cliente original; não aceite cabeçalhos arbitrários do cliente. Veja Caddy HTTPS.
Abra https://sonar.example.com e troque imediatamente admin/admin:
- Guarde senha nova no gerenciador.
- Configure base URL em
Administration → Configuration → General → General. - Remova permissões anônimas desnecessárias.
- Crie Project Analysis Token por projeto CI.
- Defina validade e responsável.
- Evite User Token administrativo no CI.
https://sonar.example.com
O token completo aparece ao criar. Guarde em Credentials/Secrets, não em sonar-project.properties, Compose ou logs.
Crie projeto local:
Project key: my-api
Display name: My API
Main branch: main
Adapte sonar-project.properties às rotas reais:
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
Gere antes o arquivo de cobertura. Não guarde sonar.token; use ambiente restrito:
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 do scanner é demonstração. Fixe scanner/imagem revisados na produção e evite tokens reais no histórico shell.
Configure Settings → Secrets and variables → Actions:
SONAR_HOST_URL=https://sonar.example.com.SONAR_TOKEN= token do projeto.
O workflow original .github/workflows/sonarqube.yml é:
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 }}
Adicione with ao passo SonarQube Scan para aguardar resultado e falhar se rejeitado:
with:
args: -Dsonar.qualitygate.wait=true
Enviar análise não comprova gate aprovado. Para branch principal Community, retire pull_request até confirmar suporte da edição. PRs de forks não recebem segredos: não exponha tokens a código não confiável para contornar essa restrição.
Runner hospedado precisa acessar HTTPS. Para serviço privado, use runner próprio confiável com rotas/CA corretas. Fixe Actions por SHA revisado e adapte Node, testes e cobertura.
Instale/configure plugin SonarQube Scanner:
- Adicione Secret Text do token em
Manage Jenkins → Credentials. - Configure URL/credencial em
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 no agent; o npx sonar-scanner sem versão não deve baixar pacotes arbitrários na execução. Configure callback de waitForQualityGate:
https://jenkins.example.com/sonarqube-webhook/
Use secret aleatório e credencial Jenkins/HMAC correspondentes; quando por passo, configure webhookSecretId em waitForQualityGate. Provoque gate falho e confira que CI para; testar apenas verde não comprova bloqueio.
Sonar way concentra-se no código novo. Não exija eliminar toda dívida histórica ao começar:
- Aplique primeiro a New Code.
- Rejeite problemas graves novos.
- Eleve cobertura de uma base medida.
- Mantenha duplicação prática.
- Atribua revisão de hotspots.
- Faça CI falhar além de notificar.
Use condições explicáveis e reproduzíveis.
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status numbered
Preserve acesso SSH antes de ativar UFW. Confira escuta:
sudo ss -lntp | grep -E ':(443|9000|5432)\b'
9000 deve mostrar 127.0.0.1:9000; 5432 não deve estar publicado. VPN/proxy de identidade ainda devem permitir CI confiável.
cd /opt/sonarqube
docker compose ps
docker compose logs --tail=200 sonarqube
docker compose logs --tail=200 db
web.log: web, autenticação, banco.ce.log: análise em segundo plano.es.log: início, índices e disco Elasticsearch.access.log: acesso web se 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
Monitore CPU, RAM livre, swap, disco/I/O, reinícios, conexões e /api/system/status. Alerte antes de watermarks bloqueantes.
PostgreSQL guarda dados autoritativos; índices são reconstruíveis. Preserve:
- Dumps PostgreSQL consistentes.
compose.yaml/.envcriptografados.- Lista de plugins e volume extensions.
- Caddy.
- Imagens exatas aplicação/banco.
- Manual e ensaio real de recuperação.
Prepare destino privado com umask 077/permissões restritas:
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 nome lógico. Compose costuma prefixá-lo: use volume existente real para não copiar silenciosamente um volume novo vazio:
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
Substitua o primeiro 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
Confira arquivos/checksums, guarde Caddy separadamente, criptografe e envie a armazenamento independente. Ensaie com o guia de backups.
Iguale versões e use outro host/projeto com volumes novos e nomes/portas sem conflitos. Pare SonarQube do destino:
cd /opt/sonarqube
docker compose stop sonarqube
Os comandos substituem sonarqube do destino; escolha o arquivo 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 configuração/plugins e limpe somente índices reconstruíveis verificados:
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 é a rota da imagem histórica; confira na escolhida antes de apagar. Não substitua por limpeza completa do volume. Confira login, projetos/histórico, permissões, novo scan e retorno CI.
Não permita substituição automática pelo Watchtower:
- Leia notas intermediárias.
- Confira banco, plugins e recursos.
- Reserve disco para migração; referência original: cerca de 50% livre no volume do banco.
- Copie/verifique banco.
- Atualize cópia restaurada.
- Altere tag explícita.
- Baixe/inicie a imagem escolhida.
- Confira scan, gate, webhook, login e projetos.
- Guarde imagem/banco anteriores durante observação.
cd /opt/sonarqube
docker compose pull sonarqube
docker compose up -d sonarqube
docker compose logs -f --tail=200 sonarqube
Migração incompatível exige banco anterior além da imagem 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
Confira persistência após reiniciar e permissões do 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, limites, disponibilidade do banco, permissões ou plugins.
docker compose ps db
docker compose logs --tail=200 db
docker compose exec db pg_isready -U sonarqube -d sonarqube
Confira .env e renderização privada docker compose config. Não publique 5432.
curl -v https://sonar.example.com/api/system/status
curl -I https://sonar.example.com/batch/index
Teste no runner: DNS, cadeia, proxy de saída, firewall e logs. CA interna exige confiança correta no scanner/JVM.
- Webhook termina em
/sonarqube-webhook/. - Confira rota SonarQube → Jenkins.
- Confira Host/TLS encaminhados.
- Veja status/corpo webhook e access logs.
- Confira compatibilidade plugin/aplicação.
Não aumente waitForQualityGate às cegas.
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
Localize histórico, banco, logs, plugins e imagens. Use retenção suportada, backup e expansão, sem apagar volumes arbitrariamente.
- Valide DNS/HTTPS.
- Confira
vm.max_map_count,fs.file-max,nofile,nproc. - Fixe imagens aplicação/banco.
- PostgreSQL interno e SonarQube loopback.
- Troque administrador/base URL.
- Tokens por projeto com validade.
- Complete scan real.
- Gate falho deve bloquear CI.
- Configure/verifique HMAC webhook.
- Ensaie banco externo e volume real de plugins.
- Alerte disco, RAM, saúde e reinícios.
- Atualize com versão/backup controlados.
Para poucos repositórios de baixa frequência e pequena folga. Equipes pequenas podem começar em 4 núcleos/8GB/100GB NVMe e medir OOM/I/O.
É para testes. Use banco suportado pela Community escolhida; aqui PostgreSQL 17 com matriz original 14–18.
Use 127.0.0.1:9000 atrás de Caddy HTTPS.
Confira matriz da versão/produto. Análise e gate da branch principal independem de prometer funções comerciais PR/branches.
Não: banco, configuração, segredos estáveis e plugins precisam de backup consistente/restauração isolada. Índices podem ser regenerados.
Fixe imagens e ensaie mudanças. Iniciar docker compose up -d não comprova rollback seguro nem integração CI completa.