Hospedar Jenkins® em um VPS gerenciado: seus builds em seu servidor

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.

Simon Vasconcelos Lee Por Publicado em 16 de novembro de 2026Leitura: 15 minutos

Todos os guias

O essencial

  1. A licença MIT permite usar o Jenkins livremente em sua empresa, desde que você mantenha o aviso de licença dele. O nome segue à parte a política de marca adotada pelo projeto, a da Linux Foundation.
  2. Escolha a linha LTS: a 2.580.2 em 28 de outubro de 2026, que roda com Java 21 ou Java 25. Uma nova base LTS é selecionada a cada 12 semanas.
  3. Instale-o com a imagem oficial 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.
  4. Execute os builds em agentes e coloque os executores do controlador em 0. Conceda as permissões com a segurança baseada em matriz e mantenha a proteção CSRF ativa.
  5. Faça backup do JENKINS_HOME, guarde secrets/master.key à parte e leia o guia de atualização de cada LTS antes de aplicá-la.

O que o Jenkins faz

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.

A licença MIT e a marca

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.

LTS ou semanal: qual versão instalar

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.

LinhaEm 8 de novembro de 2026Ritmo
LTS2.580.2, de 28 de outubro de 2026, após a 2.580.1, de 30 de setembroTrês versões por base, .1, .2 e .3, cada uma após duas semanas de retroporte e duas semanas de testes
Semanal2.589Uma 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 instalação com Docker Compose

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.

compose.yaml
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:
Caddyfile
jenkins.example.com {
  encode zstd gzip
  reverse_proxy jenkins:8080
}
Terminal
docker compose up -d

Dimensionar o servidor

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.

Com os pacotes Debian ou Ubuntu

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.

Terminal
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:

Terminal
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:

Ajuste do serviço
[Service]
Environment="JENKINS_LISTEN_ADDRESS=127.0.0.1"

Com o Nginx e o Certbot

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:

Bloco do Nginx
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;
  }
}

Em seguida, o Certbot instala o certificado e cuida de renová-lo:

Terminal
sudo certbot --nginx

A URL do Jenkins e o proxy reverso

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.

A primeira inicialização: a senha inicial e o assistente

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:

Terminal, com Docker Compose
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
Terminal, com os pacotes
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
  1. Cole essa senha na página Unlock Jenkins.
  2. Escolha Install suggested plugins, o conjunto que a documentação aconselha quando você ainda não sabe bem de quais plugins precisa; os outros são acrescentados mais tarde em Manage Jenkins, Plugins.
  3. Crie o primeiro administrador, com uma senha forte. Se você pular essa etapa, a conta admin mantém como senha a senha de desbloqueio.
  4. Informe a URL do Jenkins, como na seção anterior.

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.

Os builds nos agentes, o controlador para orquestrar

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.

  1. Conecte pelo menos um agente: outra máquina, um contêiner ou uma nuvem. O agente precisa do Java e de uma conexão de rede com o controlador.
  2. Em Manage Jenkins, Nodes, abra Built-In Node, depois Configure, e coloque o número de executores em 0. Faça isso quando um agente já estiver no lugar, pois os builds passam então a esperar um agente para começar. A imagem Docker define 2 por padrão.
ConexãoComoDo lado da rede
SSHO controlador se conecta ao agente, com o plugin SSH Build AgentsNenhuma porta a abrir no controlador
WebSocketO agente se conecta ao controlador pelo endereço HTTPS dele, desde o Jenkins 2.217Nenhuma porta extra: o proxy repassa o WebSocket
TCP de entradaO agente se conecta ao controlador em uma porta TCP dedicadaUma 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.

As contas e as permissões

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égiaO que ela concedeQuando escolhê-la
Anyone can do anythingTodos os direitos, até aos visitantes anônimosApenas para um teste local
Logged-in users can do anythingTodos os direitos a toda conta conectada; a configuração que o assistente deixaEnquanto só pessoas de total confiança tiverem uma conta
Matrix-based securityPermissões concedidas por usuário ou por grupoO ponto de partida que a documentação recomenda para a produção
Project-based Matrix Authorization StrategyA mesma matriz, estendida projeto a projetoPara 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.

Os plugins e as atualizações deles

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 por e-mail

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.

O backup do JENKINS_HOME

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.

ElementoO que ele guardaA salvar
*.xml, entre eles config.xmlA configuração principal e a configuração do sistemaObrigatório
jobs/Os jobs e o histórico dos builds; em builds/archive, os artefatos arquivadosObrigatório; os artefatos conforme a necessidade, eles ficam volumosos
plugins/*.jpiOs plugins instalados, nas versões delesRecomendado, para restaurar de forma idêntica
secrets/As chaves que criptografam as credenciaisA pasta, exceto master.key, guardada à parte
workspace/Os arquivos obtidos do controle de código-fonte para os buildsOpcional: um novo checkout os recria
war/, cache/, tools/O WAR descompactado, as ferramentas baixadas e extraídasOpcional: 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.

Com Docker Compose

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:

Terminal, na pasta do compose.yaml
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
Terminal, uma vez: a chave mestra
docker cp jenkins:/var/jenkins_home/secrets/master.key ./master.key

Com os pacotes

Terminal
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.

Validar um backup

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:

Terminal
export JENKINS_HOME=/mnt/backup-test
java -jar jenkins.war --httpPort=9999

As atualizações

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:

Terminal, com Docker Compose
docker compose pull
docker compose up -d
Terminal, com os pacotes
sudo apt update
sudo apt install jenkins

Quem faz o quê em um VPS gerenciado

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.

AssuntoNossas equipesVocê
O servidorAtualizações do sistema e de segurança, com intervenções no servidor incluídasO momento que convém a sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligaçãoA leitura dos logs de sua instância e de seus builds
JenkinsAcompanhamento proativo: erros, lentidões e espaço em disco identificados, correção recomendadaA 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 agentesOs servidores que os sustentam, monitorados e com backupOs jobs, os agentes, as contas, as permissões e as credenciais
Os backupsToda noite, criptografados e guardados fora da máquina; restauração incluídaOs arquivos próprios do Jenkins, o arquivo master.key e o pedido de restauração, quando você precisar
A migraçãoSeu servidor atual migrado, grátisO 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.

Jenkins, em um servidor cuidado por nós

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.

Conhecer os VPS gerenciados

Perguntas frequentes

O Jenkins é gratuito para uma empresa?

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.

Qual versão do Jenkins instalar?

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.

Como instalar o Jenkins com Docker?

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.

Onde encontrar a senha inicial de administrador 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.

Os builds devem rodar no controlador Jenkins?

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.

Como proteger uma instância Jenkins?

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.

Como fazer backup do Jenkins?

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 Jenkins?

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.

Fontes e documentação oficial

Entre em contato