Alojar Jenkins® num VPS gerido: os seus builds no seu servidor

Alojar Jenkins num VPS gerido é compilar, testar e implementar os seus projetos a partir de uma máquina sua, que as nossas equipas mantêm atualizada e supervisionam dia e noite. O Jenkins é um software livre sob licença MIT. Este guia segue a sua documentação oficial: a escolha da versão LTS, a instalação com o Docker Compose ou com os pacotes Linux, o HTTPS e o URL do Jenkins, os agentes, as permissões, os plugins, as cópias de segurança e as atualizações.

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

Todos os guias

O essencial

  1. A licença MIT permite utilizar livremente o Jenkins numa empresa, desde que mantenha o seu aviso de licença. O nome depende, à parte, da política de marca que o projeto adotou, a da Linux Foundation.
  2. Escolha a linha LTS: a 2.580.2 em 28 de outubro de 2026, que corre em 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 suas etiquetas lts, ou com os pacotes Linux do projeto, atrás de um proxy inverso em HTTPS; indique depois esse endereço como URL do Jenkins.
  4. Faça correr os builds em agentes e ponha a 0 os executores do controlador. Atribua as permissões com a segurança por matriz e mantenha ativa a proteção CSRF.
  5. Faça a cópia de segurança do JENKINS_HOME, guarde secrets/master.key à parte e leia o guia de atualização de cada LTS antes de a aplicar.

O que faz o Jenkins

O Jenkins apresenta-se como o principal servidor de automatização de código aberto. Construído em Java, oferece mais de 2000 plugins para automatizar praticamente tudo. O seu README enumera as utilizações mais comuns: compilar projetos, executar testes para detetar os erros logo que são introduzidos, a análise estática do código e a implementação.

A licença MIT e a marca

O Jenkins é publicado sob a licença MIT. Esta permite utilizar, copiar, modificar, fundir, publicar, distribuir, sublicenciar e vender o software, com uma condição: manter o aviso de direitos de autor e o texto da licença em todas as cópias. Pode, portanto, fazer correr o Jenkins na sua empresa, para os seus próprios projetos e para os dos seus clientes, sem licença para comprar.

A licença cobre o código. O nome «Jenkins» é uma marca registada da LF Charities, Inc., organização ligada à Linux Foundation, e o projeto aplica a política de marca da Linux Foundation. Essa política dirige-se a quem coloca a palavra no nome do seu próprio produto ou serviço, e propõe para isso formas como «o seu produto for Jenkins»: leia-a se estiver a construir uma oferta em torno do software. Citar o Jenkins para o descrever, como faz este guia, é uma utilização legítima.

Esta publicação é independente do projeto Jenkins, da LF Charities, Inc. e da Linux Foundation, e não é afiliada, patrocinada nem aprovada por eles.

LTS ou semanal: que versão instalar

O Jenkins é publicado em duas linhas. A versão semanal traz novidades e correções todas as semanas. 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 transpostas. A documentação apresenta as etiquetas LTS da imagem Docker como a versão mais estável, pronta para a produção: é a que este guia instala.

LinhaEm 8 de novembro de 2026Ritmo
LTSA 2.580.2, de 28 de outubro de 2026, depois da 2.580.1, de 30 de setembroTrês versões por base, .1, .2 e .3, cada uma depois de duas semanas de transposição 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 arranca. O projeto prevê terminar o suporte do Java 21 em setembro de 2027 e o do Java 25 em setembro de 2029. O requisito aplica-se a todo o sistema, controlador, agentes e linha de comandos; os seus projetos, esses, compilam com a versão de Java que lhes convier.

A instalação com o Docker Compose

A documentação recomenda a imagem oficial jenkins/jenkins. A etiqueta lts acompanha a LTS em Java 21, lts-jdk25 a mesma LTS em Java 25, e latest a versão semanal. Num servidor com o Docker instalado, crie uma pasta e coloque nela este compose.yaml, tirado do exemplo Caddy da documentação: o Caddy recebe os visitantes nas portas 80 e 443, obtém o certificado HTTPS e encaminha para o Jenkins, acessível apenas na 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 num contentor Docker, e recomenda 4 GB de memória ou mais e 50 GB de disco ou mais para uma pequena equipa. Explica que a memória do controlador vai de 200 MB para uma pequena instalação a mais de 70 GB para as maiores; cada agente ligado ocupa nele 2 ou 3 threads, cerca de 2 MB ou mais. O essencial do trabalho, os builds, corre nos agentes.

Num VPS gerido, descreva-nos os seus projetos e a frequência dos seus builds: recomendamos-lhe o tamanho adequado para o controlador e para os agentes.

Com os pacotes Debian ou Ubuntu

O projeto publica também pacotes para Debian e Ubuntu, Fedora, Red Hat Enterprise Linux e os seus derivados. No Debian ou no Ubuntu, instale primeiro o Java: a documentação recomenda-o vivamente, porque um Jenkins instalado antes do Java pode não encontrar uma instalação Java válida no arranque.

Terminal
sudo apt update
sudo apt install fontconfig openjdk-21-jre
java -version

Acrescente depois o repositório LTS, debian-stable, com a sua chave de assinatura, 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 utilizador jenkins, envia o seu registo para o journald (journalctl -u jenkins.service), guarda os seus 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 Nginx da documentação, reduzido ao seu bloco location /, a forma que ela prevê para quando o Nginx não lê ele próprio os ficheiros do Jenkins:

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

O Certbot instala depois o certificado e encarrega-se de o renovar:

Terminal
sudo certbot --nginx

O URL do Jenkins e o proxy inverso

Com o Jenkins em linha, indique o seu endereço público, por exemplo https://jenkins.example.com/, em Manage Jenkins, System, na secção Jenkins Location. O Jenkins utiliza-o para todos os endereços que gera, na interface como nos ficheiros dos agentes, e para comunicar com os agentes e as ferramentas externas. As opções de porta não mudam nada: é este URL que conta.

O Jenkins vigia o seu próprio proxy inverso. Se apresentar «It appears that your reverse proxy setup is broken», verifique primeiro que este URL corresponde ao endereço que utiliza e depois que o proxy envia X-Forwarded-Proto quando recebe HTTPS e fala com o Jenkins em HTTP, como fazem os dois exemplos deste guia.

Servido num caminho como /jenkins em vez de no seu próprio nome de domínio, o Jenkins tem de conhecer esse caminho: --prefix=/jenkins, através de JENKINS_OPTS com o Docker ou de JENKINS_PREFIX com os pacotes. A documentação recomenda o mesmo caminho dos dois lados, porque reescrevê-lo no proxy obriga a corrigir muitíssimos endereços.

O primeiro arranque: a palavra-passe inicial e o assistente

No primeiro acesso, o Jenkins pede uma palavra-passe gerada automaticamente, que escreve no seu registo e em secrets/initialAdminPassword. Abra o seu endereço HTTPS e leia-a depois:

Terminal, com o Docker Compose
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
Terminal, com os pacotes
sudo cat /var/lib/jenkins/secrets/initialAdminPassword
  1. Cole esta palavra-passe na página Unlock Jenkins.
  2. Escolha Install suggested plugins, o conjunto que a documentação aconselha quando ainda não sabe bem de que plugins precisa; os outros acrescentam-se mais tarde em Manage Jenkins, Plugins.
  3. Crie o primeiro administrador, com uma palavra-passe sólida. Se saltar este passo, a conta admin fica com a palavra-passe de desbloqueio como palavra-passe.
  4. Indique o URL do Jenkins, como na secção anterior.

O assistente deixa ativa a estratégia de autorização «Logged-in users can do anything»: qualquer conta com sessão iniciada tem todos os direitos. Convém-lhe enquanto só pessoas de total confiança tiverem uma conta. Antes de abrir mais contas, passe para a segurança por matriz, descrita mais abaixo.

Os builds nos agentes, o controlador para orquestrar

Um build executa comandos que outras pessoas além do administrador controlam: scripts de compilação, testes, o código de cada commit. No nó integrado, esses comandos têm o mesmo acesso ao sistema de ficheiros do controlador que o próprio Jenkins. A documentação recomenda, por isso, não executar nenhum build no nó integrado e confiá-los a agentes, o que reserva também o processador e a memória do controlador para a sua própria tarefa.

  1. Ligue pelo menos um agente: outra máquina, um contentor ou uma cloud. O agente precisa do Java e de uma ligação de rede ao controlador.
  2. Em Manage Jenkins, Nodes, abra Built-In Node, depois Configure, e ponha o número de executores a 0. Faça-o com um agente já instalado, porque os builds passam a esperar por um agente para arrancar. A imagem Docker define 2 por predefinição.
LigaçãoComoDo lado da rede
SSHO controlador liga-se ao agente, com o plugin SSH Build AgentsNenhuma porta a abrir no controlador
WebSocketO agente liga-se ao controlador pelo seu endereço HTTPS, desde o Jenkins 2.217Nenhuma porta adicional: o proxy transmite o WebSocket
TCP de entradaO agente liga-se ao controlador numa porta TCP dedicadaUma porta fixa a abrir e a publicar, a 50000 na imagem Docker

A documentação aconselha agentes genéricos e intermutáveis, preparados com uma ferramenta de gestão da configuração, uma imagem pré-construída ou um contentor: um agente que falhe é então substituído sem esforço. Com um único servidor, sugere um agente que corra com outro utilizador do sistema operativo, sem acesso de leitura nem de escrita ao JENKINS_HOME e sem sudo. Num VPS gerido, um segundo VPS pode também servir de agente, dimensionado para os seus builds.

O controlo 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 é, da autorização, que diz o que pode fazer. A sua base de utilizadores integrada, ativa por predefinição, convém às pequenas equipas; LDAP, Active Directory, SAML ou OpenID Connect ligam-se através de plugins. Para a autorização, eis as estratégias que a documentação descreve:

EstratégiaO que concedeQuando a escolher
Anyone can do anythingTodos os direitos, até aos visitantes anónimosApenas para um teste local
Logged-in users can do anythingTodos os direitos a qualquer conta com sessão iniciada; a definição que o assistente deixaEnquanto só pessoas de total confiança tiverem uma conta
Matrix-based securityPermissões atribuídas por utilizador ou por grupoO ponto de partida que a documentação recomenda para a produção
Project-based Matrix Authorization StrategyA mesma matriz, alargada projeto a projetoPara reservar certos projetos a certas pessoas

As duas estratégias por matriz vêm do plugin Matrix Authorization Strategy, que faz parte dos 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». Tenha o mesmo cuidado se abrir a inscrição livre ou um fornecedor de identidade onde qualquer pessoa pode criar uma conta.

Os plugins e as suas atualizações

Os plugins são o que torna o Jenkins tão polivalente, e cada um é código que corre dentro do controlador. O Jenkins consulta o Update Center uma vez a cada 24 horas; as atualizações aparecem no separador Updates de Manage Jenkins, Plugins, e entram em vigor depois de um reinício. O botão Check now força uma verificação.

Com o Docker, pode também construir a sua própria imagem a partir de jenkins/jenkins e instalar nela os seus plugins com jenkins-plugin-cli, a partir de uma lista plugins.txt que fixa as suas versões e que a ferramenta sabe atualizar. O README da imagem descreve este método.

As notificações por e-mail

As notificações de build passam pelo plugin Mailer: um build falhado, um sucesso depois de uma falha ou um build que se torna instável desencadeiam um e-mail. O servidor de envio define-se em Manage Jenkins, System, na secção E-mail Notification.

Num VPS Simafri, o envio passa por uma retransmissão SMTP autenticada, na porta 587: o endereço de uma conta de correio que já tenha, ou o Simafri Suite. Nas opções avançadas, marque Use SMTP Authentication com o nome de utilizador e a palavra-passe da conta e depois Use TLS: o plugin passa então a utilizar a porta 587. A opção Test configuration by sending test e-mail envia uma mensagem de teste.

A cópia de segurança do JENKINS_HOME

A documentação considera as cópias de segurança do controlador de importância crítica: servem para recuperar de um desastre, de uma configuração alterada por engano ou de um ficheiro corrompido ou eliminado. Tudo vive no JENKINS_HOME: /var/jenkins_home na imagem Docker, /var/lib/jenkins com os pacotes.

ElementoO que guardaA copiar
*.xml, incluindo config.xmlA configuração principal e a do sistemaObrigatório
jobs/As tarefas e o histórico dos builds; em builds/archive, os artefactos arquivadosObrigatório; os artefactos consoante a necessidade, porque crescem muito
plugins/*.jpiOs plugins instalados, nas suas versõesRecomendado, para restaurar de forma idêntica
secrets/As chaves que cifram as credenciaisA pasta, exceto master.key, guardada à parte
workspace/Os ficheiros obtidos do controlo de versões para os buildsFacultativo: uma nova obtenção recria-os
war/, cache/, tools/O WAR descompactado, as ferramentas transferidas e extraídasFacultativo: recriados quando necessário

A documentação pede que nunca coloque a chave mestra na sua cópia de segurança habitual. secrets/master.key cifra a chave que protege as suas credenciais: quem tiver as suas cópias de segurança e esta chave pode ler tudo. Copie-a uma vez e guarde-a à parte num local muito seguro, como uma chave privada SSH; um restauro completo precisa dela.

Com o Docker Compose

O README da imagem pede que trate o jenkins_home como uma base de dados. Pare o Jenkins durante a cópia e arquive depois o volume com um contentor 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 copiar sem parar, a documentação remete para os instantâneos do sistema de ficheiros, LVM, btrfs ou ZFS, mais coerentes e mais rápidos do que uma cópia a quente; entre os plugins de cópia de segurança de código aberto, 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 no reinício, e envie as cópias terminadas para um servidor remoto.

Colocados no disco do servidor, estes arquivos entram também nas suas cópias de segurança noturnas.

Validar uma cópia de segurança

A documentação pede que valide cada cópia de segurança e dá o método simples: restaure-a numa pasta temporária, volte a colocar o master.key e arranque sobre ela um segundo Jenkins da mesma versão, noutra 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 visada nos guias de atualização do projeto: cada secção trata da passagem a partir da LTS anterior. Para a 2.580.2, não indica nenhuma alteração digna de nota. Para a 2.580.1, assinala que vários plugins separados do núcleo deixaram de vir incluídos no WAR: o Jenkins instala-os sozinho quando o Update Center está acessível. Faça depois a cópia de segurança do JENKINS_HOME e atualize:

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

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Jenkins continua a ser o seu software, com os seus pipelines, as suas definições e os seus dados.

AssuntoAs nossas equipasVocê
O servidorAtualizações do sistema e de segurança, intervenções no servidor incluídasO momento que convém à sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamadaA leitura dos registos da sua instância e dos seus builds
JenkinsAcompanhamento proativo: erros, lentidão e espaço em disco identificados, correção recomendadaA sua instalação, as suas atualizações, os seus plugins e as suas definições, que aplica diretamente ou com o seu assistente de IA
Os pipelines e os agentesOs servidores que os suportam, vigiados e com cópias de segurançaAs tarefas, os agentes, as contas, as permissões e as credenciais
As cópias de segurançaTodas as noites, cifradas e guardadas fora da máquina; restauro incluídoOs arquivos próprios do Jenkins, o ficheiro master.key e o pedido de restauro, quando precisar
A migraçãoO seu servidor atual migrado, oferecidoO momento da mudança

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.

O Jenkins, num servidor mantido por si

Com um VPS gerido da Simafri, as nossas equipas mantêm atualizado o servidor da sua instância Jenkins, vigiam-no dia e noite e intervêm sem esperar pela sua chamada; acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica diretamente ou com o seu assistente de IA. As cópias de segurança são cifradas todas as noites e guardadas fora da máquina, o seu restauro está incluído, e a migração do seu servidor atual é oferecida.

Descobrir os VPS geridos

Perguntas frequentes

O Jenkins é gratuito para uma empresa?

Sim. O Jenkins está sob licença MIT: pode utilizá-lo, modificá-lo e fazê-lo correr na sua empresa sem licença para comprar, desde que mantenha o seu aviso de direitos de autor e de licença. Resta o custo dos servidores que suportam o controlador e os agentes.

Que 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. 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 o Docker?

Utilize a imagem oficial jenkins/jenkins com uma etiqueta LTS, como lts-jdk25, e um volume com nome montado em /var/jenkins_home. Coloque um proxy inverso em HTTPS à frente, por exemplo o Caddy no mesmo ficheiro compose.yaml, e indique depois o endereço público como URL do Jenkins.

Onde encontrar a palavra-passe inicial de administração do Jenkins?

No registo de arranque, e no ficheiro 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 depois a sua própria conta de administrador.

Os builds devem correr no controlador Jenkins?

A documentação recomenda fazê-los correr em agentes: no nó integrado, um build tem o mesmo acesso aos ficheiros do controlador que o Jenkins. Ligue um agente, por SSH ou WebSocket, e ponha depois a 0 os executores do nó integrado.

Como proteger uma instância Jenkins?

Sirva-a em HTTPS atrás de um proxy inverso, passe para a segurança por matriz, reserve Overall/Administer a pessoas de confiança, mantenha ativa a proteção CSRF, faça correr os builds em agentes e aplique sem demora as versões LTS que trazem correções de segurança.

Como fazer a cópia de segurança do Jenkins?

Arquive o JENKINS_HOME, com o serviço parado ou através de um instantâneo do sistema de ficheiros. Deixe secrets/master.key fora dessa cópia, guardado à parte num local muito seguro, e valide cada cópia restaurando-a num Jenkins de teste arrancado noutra porta.

Um VPS gerido cobre o Jenkins?

Um VPS gerido cobre o servidor: sistema, segurança, supervisão e cópias de segurança. As nossas equipas acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica. Uma intervenção na aplicação é faturada à hora ou por pacote.

Fontes e documentação oficial

Contacte-nos