Hospedar o Jenkins em um VPS gerenciado é compilar, testar e implantar seus projetos a partir de uma máquina própria, que nossas equipes mantêm atualizada e supervisionam dia e noite. O Jenkins é um software livre sob a licença MIT. Este guia segue a documentação oficial dele: a escolha da versão LTS, a instalação com Docker Compose ou com os pacotes Linux, o HTTPS e a URL do Jenkins, os agentes, as permissões, os plugins, os backups e as atualizações.
Por Simon Vasconcelos Lee
Publicado em 16 de novembro de 2026Leitura: 15 minutos
jenkins/jenkins e as tags lts dela, ou com os pacotes Linux do projeto, atrás de um proxy reverso em HTTPS; depois, informe esse endereço como URL do Jenkins.JENKINS_HOME, guarde secrets/master.key à parte e leia o guia de atualização de cada LTS antes de aplicá-la.O Jenkins se apresenta como o principal servidor de automação de código aberto. Escrito em Java, ele oferece mais de 2.000 plugins para automatizar praticamente qualquer coisa. O README dele lista os usos mais comuns: compilar projetos, executar testes para detectar os bugs assim que surgem, a análise estática de código e a implantação.
Jenkinsfile, que a documentação recomenda versionar no controle de código-fonte do projeto.O Jenkins é distribuído sob a licença MIT. Ela permite usar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e vender o software, com uma condição: manter o aviso de copyright e o texto da licença em cada cópia. Você pode, portanto, rodar o Jenkins em sua empresa, para seus próprios projetos e para os de seus clientes, sem licença a comprar.
A licença cobre o código. O nome “Jenkins” é uma marca registrada da LF Charities, Inc., organização ligada à Linux Foundation, e o projeto aplica a política de marca da Linux Foundation. Essa política se dirige a quem coloca a palavra no nome de seu próprio produto ou serviço e propõe para isso formas como “seu produto for Jenkins”: leia-a se você estiver construindo uma oferta em torno do software. Citar o Jenkins para descrevê-lo, como faz este guia, é um uso legítimo.
Esta publicação é independente do projeto Jenkins, da LF Charities, Inc. e da Linux Foundation: ela não é afiliada a eles, nem patrocinada, nem aprovada por eles.
O Jenkins sai em duas linhas. A versão semanal traz novos recursos e correções toda semana. A linha LTS, de Long-Term Support, parte de uma versão semanal selecionada a cada 12 semanas como base e recebe depois correções retroportadas. A documentação apresenta as tags LTS da imagem Docker como a versão mais estável, pronta para a produção: é ela que este guia instala.
| Linha | Em 8 de novembro de 2026 | Ritmo |
|---|---|---|
| LTS | 2.580.2, de 28 de outubro de 2026, após a 2.580.1, de 30 de setembro | Três versões por base, .1, .2 e .3, cada uma após duas semanas de retroporte e duas semanas de testes |
| Semanal | 2.589 | Uma versão por semana |
A LTS 2.580.2 exige Java 21 ou Java 25: com qualquer outra versão, o controlador não roda. O projeto prevê encerrar o suporte ao Java 21 em setembro de 2027 e ao Java 25 em setembro de 2029. A exigência vale para todo o sistema, controlador, agentes e linha de comando; seus próprios projetos são compilados com a versão do Java que convier a eles.
A documentação recomenda a imagem oficial jenkins/jenkins. A tag lts acompanha a LTS com Java 21, lts-jdk25 a mesma LTS com Java 25, e latest a versão semanal. Em um servidor com o Docker instalado, crie uma pasta e coloque nela este compose.yaml, extraído do exemplo com Caddy da documentação: o Caddy recebe os visitantes nas portas 80 e 443, obtém o certificado HTTPS e repassa ao Jenkins, acessível apenas pela rede interna.
services:
jenkins:
image: jenkins/jenkins:lts-jdk25
container_name: jenkins
restart: unless-stopped
volumes:
- jenkins_home:/var/jenkins_home
expose:
- "8080"
networks:
- web
caddy:
image: caddy:2
container_name: caddy
restart: unless-stopped
depends_on:
- jenkins
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
networks:
- web
networks:
web:
driver: bridge
volumes:
jenkins_home:
caddy_data:
caddy_config:
jenkins.example.com {
encode zstd gzip
reverse_proxy jenkins:8080
}
docker compose up -d
/var/jenkins_home: todos os dados ficam nele, plugins e configuração incluídos. O README da imagem prefere esse volume a uma pasta do servidor, que pode causar problemas de permissão: o usuário jenkins do contêiner tem o ID 1000.web. A porta 50000 serve aos agentes TCP de entrada; os agentes WebSocket e SSH dispensam essa porta, por isso ela não é publicada aqui.2.580.2-lts-jdk25 fixa a versão, enquanto lts-jdk25 acompanha a LTS do momento.A documentação fixa um mínimo de 256 MB de memória e 1 GB de disco, pelo menos 10 GB em um contêiner Docker, e recomenda 4 GB de memória ou mais e 50 GB de disco ou mais para uma equipe pequena. Ela explica que a memória do controlador vai de 200 MB em uma instalação pequena a mais de 70 GB nas maiores; cada agente conectado ocupa ali 2 ou 3 threads, cerca de 2 MB ou mais. O grosso do trabalho, os builds, roda nos agentes.
Em um VPS gerenciado, fale-nos de seus projetos e da frequência de seus builds: recomendamos o tamanho adequado para o controlador e para os agentes.
O projeto também publica pacotes para Debian e Ubuntu, Fedora, Red Hat Enterprise Linux e os derivados dele. No Debian ou no Ubuntu, instale primeiro o Java: a documentação o recomenda fortemente, pois um Jenkins instalado antes do Java pode não encontrar uma instalação Java válida na inicialização.
sudo apt update
sudo apt install fontconfig openjdk-21-jre
java -version
Acrescente então o repositório LTS, debian-stable, com a chave de assinatura dele, e instale o Jenkins:
sudo wget -O /etc/apt/keyrings/jenkins-keyring.asc \
https://pkg.jenkins.io/debian-stable/jenkins.io-2026.key
echo "deb [signed-by=/etc/apt/keyrings/jenkins-keyring.asc]" \
https://pkg.jenkins.io/debian-stable binary/ | sudo tee \
/etc/apt/sources.list.d/jenkins.list > /dev/null
sudo apt update
sudo apt install jenkins
O pacote cria um serviço systemd e um usuário jenkins, envia o log para o journald (journalctl -u jenkins.service), guarda os dados em /var/lib/jenkins e escuta na porta 8080, em todas as interfaces. Atrás de um proxy no mesmo servidor, limite-o ao endereço local com sudo systemctl edit jenkins e depois sudo systemctl restart jenkins:
[Service]
Environment="JENKINS_LISTEN_ADDRESS=127.0.0.1"
Este bloco retoma o exemplo de Nginx da documentação, reduzido ao bloco location / dele, a forma que ela prevê quando o Nginx não lê ele mesmo os arquivos do Jenkins:
upstream jenkins {
keepalive 32;
server 127.0.0.1:8080;
}
map $http_upgrade $connection_upgrade {
default upgrade;
'' '';
}
server {
listen 80;
server_name jenkins.example.com;
ignore_invalid_headers off;
location / {
sendfile off;
proxy_pass http://jenkins;
proxy_redirect default;
proxy_http_version 1.1;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Host $http_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_max_temp_file_size 0;
client_max_body_size 10m;
client_body_buffer_size 128k;
proxy_connect_timeout 90;
proxy_send_timeout 90;
proxy_read_timeout 90;
proxy_request_buffering off;
}
}
proxy_pass sem barra final: a documentação avisa que terminar esse valor com uma barra causa problemas.Upgrade e Connection atendem os agentes WebSocket, e o map mantém as conexões ativas para o resto do tráfego.proxy_request_buffering off é necessário para os comandos da linha de comando do Jenkins enviados por HTTP.client_max_body_size fixa o tamanho máximo dos envios, 10 MB no exemplo.Em seguida, o Certbot instala o certificado e cuida de renová-lo:
sudo certbot --nginx
Com o Jenkins no ar, informe o endereço público dele, por exemplo https://jenkins.example.com/, em Manage Jenkins, System, na seção Jenkins Location. O Jenkins o usa em todos os endereços que gera, na interface como nos arquivos dos agentes, e para se comunicar com os agentes e as ferramentas externas. As opções de porta não mudam nada para ele: é essa URL que conta.
O Jenkins monitora o próprio proxy reverso. Se ele exibir “It appears that your reverse proxy setup is broken”, verifique primeiro se essa URL corresponde ao endereço que você usa e depois se o proxy envia X-Forwarded-Proto quando recebe HTTPS e fala com o Jenkins em HTTP, como fazem os dois exemplos deste guia.
Servido em um caminho como /jenkins em vez de um nome de domínio próprio, o Jenkins precisa conhecer esse caminho: --prefix=/jenkins, por JENKINS_OPTS com o Docker ou JENKINS_PREFIX com os pacotes. A documentação recomenda o mesmo caminho dos dois lados, pois reescrevê-lo no proxy obriga a corrigir uma grande quantidade de endereços.
No primeiro acesso, o Jenkins pede uma senha gerada automaticamente, que ele grava no log e em secrets/initialAdminPassword. Abra seu endereço HTTPS e leia-a:
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
admin mantém como senha a senha de desbloqueio.O assistente deixa no lugar a estratégia de autorização “Logged-in users can do anything”: toda conta conectada tem todos os direitos. Ela convém enquanto só pessoas de total confiança tiverem uma conta. Antes de abrir mais contas, passe para a segurança baseada em matriz, descrita mais adiante.
Um build executa comandos que outras pessoas além do administrador controlam: scripts de build, testes, o código de cada commit. No nó integrado, esses comandos têm o mesmo acesso ao sistema de arquivos do controlador que o próprio Jenkins. A documentação recomenda, portanto, não executar nenhum build no nó integrado e entregá-los a agentes, o que também reserva a CPU e a memória do controlador ao trabalho próprio dele.
| Conexão | Como | Do lado da rede |
|---|---|---|
| SSH | O controlador se conecta ao agente, com o plugin SSH Build Agents | Nenhuma porta a abrir no controlador |
| WebSocket | O agente se conecta ao controlador pelo endereço HTTPS dele, desde o Jenkins 2.217 | Nenhuma porta extra: o proxy repassa o WebSocket |
| TCP de entrada | O agente se conecta ao controlador em uma porta TCP dedicada | Uma porta fixa a abrir e a publicar, 50000 na imagem Docker |
A documentação aconselha agentes genéricos e intercambiáveis, preparados com uma ferramenta de gerenciamento de configuração, uma imagem pronta ou um contêiner: um agente que cai é então substituído sem esforço. Com um único servidor, ela sugere um agente que rode com outro usuário do sistema operacional, sem acesso de leitura nem de escrita ao JENKINS_HOME e sem sudo. Em um VPS gerenciado, um segundo VPS também pode servir de agente, dimensionado para seus builds.
O controle de acesso do agente ao controlador, que impede um agente comprometido de enviar comandos ao controlador, está sempre ativo desde o Jenkins 2.326.
O Jenkins separa a autenticação, que estabelece quem você é, da autorização, que diz o que você pode fazer. O banco de usuários integrado dele, ativo por padrão, convém às equipes pequenas; LDAP, Active Directory, SAML ou OpenID Connect se conectam por plugins. Para a autorização, veja as estratégias que a documentação descreve:
| Estratégia | O que ela concede | Quando escolhê-la |
|---|---|---|
| Anyone can do anything | Todos os direitos, até aos visitantes anônimos | Apenas para um teste local |
| Logged-in users can do anything | Todos os direitos a toda conta conectada; a configuração que o assistente deixa | Enquanto só pessoas de total confiança tiverem uma conta |
| Matrix-based security | Permissões concedidas por usuário ou por grupo | O ponto de partida que a documentação recomenda para a produção |
| Project-based Matrix Authorization Strategy | A mesma matriz, estendida projeto a projeto | Para reservar certos projetos a certas pessoas |
As duas estratégias de matriz vêm do plugin Matrix Authorization Strategy, que está entre os plugins sugeridos pelo assistente. Na matriz, conceda pouco às linhas anonymous e authenticated: Overall/Administer concedido a authenticated equivale a “Logged-in users can do anything”. Tome o mesmo cuidado se você abrir o autocadastro ou um provedor de identidade em que qualquer pessoa pode criar uma conta.
JENKINS_HOME com as chaves da pasta secrets, que a seção sobre os backups trata à parte.Os plugins fazem a versatilidade do Jenkins, e cada um é um código que roda dentro do controlador. O Jenkins consulta o Update Center uma vez a cada 24 horas; as atualizações aparecem na aba Updates de Manage Jenkins, Plugins, e valem após uma reinicialização. O botão Check now força uma verificação.
Com o Docker, você também pode montar sua própria imagem a partir de jenkins/jenkins e instalar nela seus plugins com jenkins-plugin-cli, a partir de uma lista plugins.txt que fixa as versões deles e que a ferramenta sabe atualizar. O README da imagem descreve esse método.
As notificações de build passam pelo plugin Mailer: um build com falha, um sucesso após uma falha ou um build que se torna instável dispara um e-mail. O servidor de envio é configurado em Manage Jenkins, System, na seção E-mail Notification.
Em um VPS Simafri, o envio passa por um relay SMTP autenticado, na porta 587: o endereço de uma conta de e-mail que você já tem, ou o Simafri Suite. Nas opções avançadas, marque Use SMTP Authentication com o nome de usuário e a senha da conta e depois Use TLS: o plugin passa então a usar a porta 587. A opção Test configuration by sending test e-mail envia uma mensagem de teste.
A documentação considera os backups do controlador de importância crítica: eles servem à recuperação após um desastre, à recuperação de uma configuração alterada por engano ou de um arquivo corrompido ou excluído. Tudo fica no JENKINS_HOME: /var/jenkins_home na imagem Docker, /var/lib/jenkins com os pacotes.
| Elemento | O que ele guarda | A salvar |
|---|---|---|
*.xml, entre eles config.xml | A configuração principal e a configuração do sistema | Obrigatório |
jobs/ | Os jobs e o histórico dos builds; em builds/archive, os artefatos arquivados | Obrigatório; os artefatos conforme a necessidade, eles ficam volumosos |
plugins/*.jpi | Os plugins instalados, nas versões deles | Recomendado, para restaurar de forma idêntica |
secrets/ | As chaves que criptografam as credenciais | A pasta, exceto master.key, guardada à parte |
workspace/ | Os arquivos obtidos do controle de código-fonte para os builds | Opcional: um novo checkout os recria |
war/, cache/, tools/ | O WAR descompactado, as ferramentas baixadas e extraídas | Opcional: recriados conforme a necessidade |
A documentação pede para nunca colocar a chave mestra no backup regular. secrets/master.key criptografa a chave que protege suas credenciais: quem tiver seus backups e essa chave lê tudo. Copie-a uma vez e guarde-a à parte em um lugar muito seguro, como uma chave privada SSH; uma restauração completa precisa dela.
O README da imagem pede para tratar o jenkins_home como um banco de dados. Pare o Jenkins durante a cópia e arquive o volume com um contêiner temporário, segundo o método da documentação do Docker:
docker compose stop jenkins
docker run --rm --volumes-from jenkins -v "$(pwd)":/backup ubuntu \
tar -czf /backup/jenkins_home-$(date +%F).tar.gz --exclude=./secrets/master.key -C /var/jenkins_home .
docker compose start jenkins
docker cp jenkins:/var/jenkins_home/secrets/master.key ./master.key
sudo systemctl stop jenkins
sudo tar -czf jenkins_home-$(date +%F).tar.gz --exclude=./secrets/master.key -C /var/lib/jenkins .
sudo systemctl start jenkins
Uma cópia feita com o serviço parado é coerente. Para fazer backup sem parar, a documentação aponta os snapshots do sistema de arquivos, LVM, btrfs ou ZFS, mais coerentes e mais rápidos que uma cópia em funcionamento; entre os plugins de backup de código aberto, ela cita o thinBackup como o único ainda mantido. Dê a cada cópia um nome com data e hora, evite /tmp, que pode ser limpo na reinicialização, e envie as cópias prontas para um servidor remoto.
Colocados no disco do servidor, esses arquivos também entram nos backups noturnos dele.
A documentação pede para validar cada backup e dá o método simples: restaure-o em uma pasta temporária, recoloque o master.key e inicie sobre ela um segundo Jenkins da mesma versão, em outra porta:
export JENKINS_HOME=/mnt/backup-test
java -jar jenkins.war --httpPort=9999
Antes de cada atualização do núcleo, leia a página da LTS de destino nos guias de atualização do projeto: cada seção trata da atualização a partir da LTS anterior. Para a 2.580.2, ela não aponta nenhuma mudança notável. Para a 2.580.1, ela observa que vários plugins separados do núcleo deixaram de vir no WAR: o Jenkins os instala sozinho quando o Update Center está acessível. Faça então o backup do JENKINS_HOME e atualize:
docker compose pull
docker compose up -d
sudo apt update
sudo apt install jenkins
A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Jenkins continua sendo seu software, com os pipelines, as configurações e os dados dele.
| Assunto | Nossas equipes | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, com intervenções no servidor incluídas | O momento que convém a sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligação | A leitura dos logs de sua instância e de seus builds |
| Jenkins | Acompanhamento proativo: erros, lentidões e espaço em disco identificados, correção recomendada | A instalação, as atualizações, os plugins e as configurações dele, que você aplica, por conta própria ou com seu assistente de IA |
| Os pipelines e os agentes | Os servidores que os sustentam, monitorados e com backup | Os jobs, os agentes, as contas, as permissões e as credenciais |
| Os backups | Toda noite, criptografados e guardados fora da máquina; restauração incluída | Os arquivos próprios do Jenkins, o arquivo master.key e o pedido de restauração, quando você precisar |
| A migração | Seu servidor atual migrado, grátis | O momento da virada |
Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.
Com um VPS gerenciado Simafri, nossas equipes mantêm atualizado o servidor de sua instância Jenkins, monitoram-no dia e noite e intervêm sem esperar sua ligação; elas também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica por conta própria ou com seu assistente de IA. Os backups são criptografados todas as noites e guardados fora da máquina, a restauração está incluída, e a migração de seu servidor atual é grátis.
Sim. O Jenkins está sob a licença MIT: você pode usá-lo, modificá-lo e rodá-lo em sua empresa sem licença a comprar, desde que mantenha o aviso de copyright e de licença dele. Resta o custo dos servidores que levam o controlador e os agentes.
A linha LTS, que a documentação apresenta como pronta para a produção: a 2.580.2 em 28 de outubro de 2026. Ela exige Java 21 ou Java 25. Uma nova base LTS é selecionada a cada 12 semanas, e cada base recebe três versões de correção.
Use a imagem oficial jenkins/jenkins com uma tag LTS, como lts-jdk25, e um volume nomeado montado em /var/jenkins_home. Coloque na frente um proxy reverso em HTTPS, por exemplo o Caddy no mesmo arquivo compose.yaml, e informe o endereço público como URL do Jenkins.
No log de inicialização e no arquivo secrets/initialAdminPassword do JENKINS_HOME: /var/jenkins_home com a imagem Docker, /var/lib/jenkins com os pacotes. Cole-a na página Unlock Jenkins e crie sua própria conta de administrador.
A documentação recomenda executá-los em agentes: no nó integrado, um build tem o mesmo acesso aos arquivos do controlador que o Jenkins. Conecte um agente, por SSH ou WebSocket, e coloque os executores do nó integrado em 0.
Sirva-a em HTTPS atrás de um proxy reverso, passe para a segurança baseada em matriz, reserve Overall/Administer a pessoas de confiança, mantenha a proteção CSRF ativa, execute os builds em agentes e aplique sem demora as versões LTS que trazem correções de segurança.
Arquive o JENKINS_HOME, com o serviço parado ou por um snapshot do sistema de arquivos. Deixe secrets/master.key fora desse backup, guardado à parte em um lugar muito seguro, e valide cada backup restaurando-o em um Jenkins de teste iniciado em outra porta.
Um VPS gerenciado cobre o servidor: sistema, segurança, supervisão e backups. Nossas equipes também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica. Uma intervenção na aplicação é cobrada por hora ou por valor fechado.
Simafri
Vamos falar de seu site
Conte para a gente sobre seu projeto em poucas palavras: responderemos rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o e-mail? Escreva para a gente em support@simafri.com.