Como auto-hospedar o GitLab CE em uma VPS

É sexta à tarde, o pull request da sua equipe está aguardando revisão e seu notebook apita com uma mensagem conhecida: o GitHub está com problemas de novo.

Talvez o Actions esteja travado.

Talvez o git push retorne um erro 500 pela terceira vez este mês.

A conversa no chat da equipe já tem oito mensagens.

Na primeira vez que isso acontece, você ri. Na segunda, alguém compartilha o link da página de status do GitHub e todo mundo vai tomar um café. Na terceira, geralmente logo antes de uma janela de lançamento, alguém finalmente coloca a pergunta em palavras: Não seria melhor rodar o nosso próprio?

Para a maioria das equipes, a resposta honesta é não. O plano Free do GitLab.com atende bem equipes pequenas, e o custo operacional de manter seu próprio servidor de controle de versão não é zero.

É o tipo de troca que você só faz por um motivo real.

Talvez sua equipe tenha um desses motivos: um contrato com cliente que proíbe SaaS de terceiros, uma exigência de conformidade ou uma conta de licenças por usuário que está começando a ficar absurda. Nesse caso, auto-hospedar o GitLab CE é a saída mais limpa. Ele é de código aberto e roda em uma única VPS. Depois de ajustado, a manutenção leva cerca de uma hora por mês.

Na DreamHost, já hospedamos inúmeros servidores autogerenciados e sempre vemos o mesmo padrão. Os desenvolvedores que têm sucesso com o GitLab auto-hospedado escolhem o plano certo desde o início e fazem direito a preparação do Secure Shell Protocol (SSH) e do Domain Name System (DNS). Depois que tudo fica estável, eles resistem à vontade de continuar mexendo.

Por que auto-hospedar o GitLab em vez de usar o GitLab.com?

Você auto-hospeda o GitLab quando o GitLab.com ou o GitHub.com não atendem às suas necessidades de privacidade, conformidade ou controle de custos. Para a maioria das outras equipes, a opção hospedada é uma troca melhor.

Três motivos reais resistem a uma análise cuidadosa:

1. Privacidade e soberania de dados: seu código-fonte fica em uma infraestrutura que você gerencia e atualiza no seu próprio ritmo. Não há acesso de terceiros nem plataforma compartilhada, e o impacto de um vazamento não vai além do seu próprio servidor.
2. Conformidade: setores regulados, como saúde, finanças e governo, muitas vezes precisam controlar onde os dados ficam armazenados. O GitLab CE auto-hospedado é a forma mais simples de manter o código dentro de um perímetro controlado.
3. Controle de custos em escala: o GitLab.com cobra por usuário ativo. Segundo a página de preços do GitLab, o Premium custa US$ 29 por usuário por mês, e o preço do Ultimate só é informado sob consulta. Uma equipe de 50 pessoas no Premium gasta US$ 17.400 por ano, sem contar complementos. Uma VPS autogerenciada mais uma hora de manutenção mensal costuma sair mais barato.

Se a sua equipe tem duas pessoas e nenhum motivo de privacidade ou conformidade, a resposta certa é o plano gratuito do GitLab. (Sim, sabemos que isso soa engraçado vindo de uma empresa de hospedagem).

Com a auto-hospedagem, você troca uma conta mensal de SaaS por tempo operacional contínuo. Essa troca só vale a pena se você tiver um bom motivo para fazer a mudança.

Veja quando essa opção faz sentido e quando não faz:

O GitLab Community Edition é gratuito sob uma licença de código aberto no estilo MIT. Não há limite de usuários, nem bloqueio de recursos básicos, nem ofertas insistentes de upgrade. A plataforma inteira é sua para rodar.

Quais são os requisitos de hardware do GitLab CE?

O GitLab CE tem requisitos de hardware claros. Acertá-los é a diferença entre uma instalação ágil e uma que vive se arrastando na memória swap (o espaço em disco que o sistema operacional usa quando a RAM enche).

Segundo os requisitos oficiais de instalação do GitLab, o dimensionamento é expresso em requisições por segundo, e não em faixas fixas por usuário. A referência publicada é de 8 vCPUs e 16 GB de RAM para até 1.000 usuários (cerca de 20 requisições por segundo). Equipes menores podem rodar com menos. Para avaliação, o mínimo documentado é de 2 GB de RAM mais 1 GB de swap, mas o desempenho cai abaixo de 4 GB.

Uma instalação nova do GitLab consome cerca de 4 a 6 GB em repouso. Quando os jobs de CI/CD começam a rodar, o uso de memória dispara rápido. Então planeje uma folga, ou prepare-se para a lentidão.

Em relação ao armazenamento, a referência oficial do GitLab é de 40 GB mais o tamanho dos repositórios, mas 50 GB é um ponto de partida mais seguro na prática. Os repositórios crescem e os artefatos de build se acumulam. O NVMe, um tipo mais rápido de armazenamento em estado sólido, faz uma diferença perceptível nas operações do Git e na leitura do cache de CI.

Veja como esses requisitos se encaixam nos planos de hospedagem VPS da DreamHost:

O plano certo para a maioria das equipes com pipelines de CI/CD de verdade é o Stack 32, o único Stack que atende à referência de 8 vCPUs do GitLab. O Stack 16 tem a memória necessária, mas metade dos núcleos, então trate-o como um tamanho para testes. Parece exagero até você ver o primeiro build começar e o Sidekiq, o Postgres e um runner dispararem ao mesmo tempo*.*

Com 16 GB de RAM, você tem folga suficiente para o conjunto de serviços do GitLab (cerca de 4 a 6 GB em repouso em uma instalação padrão). Também sobra espaço para alguns workers de CI (1 a 2 GB cada) rodarem a todo vapor ao mesmo tempo, sem que ninguém no chat da equipe perceba.

Como preparar sua VPS antes de instalar o GitLab?

Dedique 10 minutos à preparação: isso compensa na primeira vez que você reiniciar o servidor. É só seguir estes passos:

1. Provisione a VPS: escolha o Ubuntu 24.04 LTS. Ele é compatível com os pacotes oficiais Omnibus do GitLab (o instalador tudo-em-um que o GitLab distribui) e ainda tem anos de atualizações de segurança gratuitas pela frente.
   
2. Aponte um domínio para o IP do servidor: crie um registro A (o tipo de registro DNS que associa um domínio a um endereço IP). Antes de instalar, aguarde pelo menos 15 a 30 minutos para a propagação. Sem isso, a configuração automática de SSL vai falhar, porque a autoridade certificadora não terá onde fazer a validação.
   
3. Atualize os pacotes: conecte-se à VPS com ssh root@your-server-ip e execute sudo apt update && sudo apt upgrade -y.
   
4. Instale as dependências: execute sudo apt install -y curl openssh-server ca-certificates perl postfix. O pacote postfix é um servidor de e-mail que cuida das mensagens enviadas, para que o GitLab possa mandar notificações de merge requests e redefinições de senha.
   Quando o instalador perguntar sobre a configuração de e-mail, escolha Internet Site e use seu domínio. Assim, o GitLab já começa a enviar e-mails imediatamente.
   Para produção: dispense o postfix local e configure um relay SMTP no gitlab.rb. IPs de VPS aparecem com frequência em listas de bloqueio de spam, e e-mails de redefinição de senha enviados pelo postfix local muitas vezes caem no spam. SendGrid, Mailgun e relays SMTP semelhantes funcionam bem. Consulte a documentação de configuração SMTP do GitLab.
   
5. Abra as portas certas: configure um firewall com o UFW (a ferramenta de firewall nativa do Ubuntu) e libere as portas 80, 443 e 22.

sudo ufw allow http
sudo ufw allow https
sudo ufw allow ssh
sudo ufw enable

Como instalar o GitLab CE no Ubuntu com o pacote Omnibus?

Adicione o repositório do GitLab CE:

curl -sSL https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

Em seguida, instale o GitLab CE definindo seu domínio como URL externa:

sudo EXTERNAL_URL="https://gitlab.example.com" apt install gitlab-ce

Definir https:// aqui faz o GitLab solicitar automaticamente um certificado Let’s Encrypt durante a instalação. Para isso, as portas 80 e 443 precisam estar abertas e o DNS precisa estar apontado corretamente. Se algum desses itens não estiver pronto, a instalação termina, mas o SSL falha. Aí você passa os próximos trinta minutos tentando resolver algo que nem está quebrado de verdade.

Depois, aguarde a etapa de reconfiguração.

O GitLab executa gitlab-ctl reconfigure (o comando que aplica qualquer alteração na configuração do GitLab) automaticamente no fim da instalação. Isso leva de cinco a 10 minutos. E sim, a etapa de reconfiguração realmente demora tudo isso.

Obtenha a senha inicial de root:

sudo cat /etc/gitlab/initial_root_password

Esse arquivo é gerado automaticamente e excluído em 24 horas, então copie a senha e faça login. Acesse seu domínio no navegador, entre como root e troque a senha imediatamente.

Por fim, verifique a instalação.

Na tela de boas-vindas do GitLab, crie um projeto de teste. Envie um commit para ele a partir da sua máquina local. Se o push funcionar e o arquivo aparecer na interface web, a instalação está saudável.

Se a etapa de reconfiguração travar, confira tail -f /var/log/gitlab/reconfigure/*.log. É ali que está o erro de verdade.

Como proteger uma instância auto-hospedada do GitLab?

O GitLab vem com padrões razoáveis, mas eles são ajustados para um servidor comunitário aberto, não para a instância privada da sua equipe. Reserve uma hora para isto.

1. Desative o cadastro aberto. O cadastro aberto vem ativado por padrão. Na Admin Area, acesse Settings > General > Sign-up restrictions e desmarque a caixa Sign-up enabled. Caso contrário, qualquer pessoa com a URL pode criar uma conta.
2. Ative a autenticação de dois fatores. Acesse Admin Area > Settings > General > Sign-in restrictions e exija 2FA para todos os usuários. Reduza o período de carência do padrão de 48 horas para 8 horas.
3. Restrinja a criação de projetos. Defina Default Project Creation como Maintainers ou No one, dependendo do nível de restrição que você quer.
4. Verifique a renovação do SSL. Por padrão, o GitLab renova automaticamente os certificados Let’s Encrypt. Para confirmar, execute sudo gitlab-ctl renew-le-certs uma vez e confira a saída.
5. Proteja o SSH na própria VPS. Desative o login de root com senha, permita apenas autenticação por chave SSH e (se der) tire o SSH da porta 22. Um servidor Git auto-hospedado só é tão seguro quanto a máquina em que ele roda.

Para uma versão mais aprofundada, o GitLab publicou um guia de reforço de segurança que cobre autenticação, criptografia e configurações da instância. Leia uma vez, aplique o que se encaixa no seu modelo de ameaças e siga em frente.

Como fazer backup e restaurar uma instância auto-hospedada do GitLab?

O GitLab inclui uma ferramenta de backup nativa. Na primeira vez que precisar dela, você vai ficar feliz por tê-la configurado.

Crie um backup:

sudo gitlab-backup create

Isso gera um arquivo tarball em /var/opt/gitlab/backups. Agende a execução diária via cron com retenção de sete dias. Execute sudo crontab -e e adicione estas duas linhas:

0 2 * * * /opt/gitlab/bin/gitlab-backup create CRON=1
0 3 * * * find /var/opt/gitlab/backups -name "*.tar" -mtime +7 -delete

A flag CRON=1 suprime a saída de progresso para não lotar os logs do cron.

Dica: o backup de dados não inclui /etc/gitlab/gitlab-secrets.json nem /etc/gitlab/gitlab.rb.

Esses arquivos guardam a chave de criptografia do banco de dados, as sementes da autenticação de dois fatores e as variáveis de CI/CD. Os segredos de configuração não fazem parte do backup normal e precisam ser salvos separadamente. Se você restaurar os dados sem o arquivo de segredos, as contas com dois fatores deixam de funcionar e as variáveis criptografadas viram lixo. E você passa uma longa noite tentando descobrir o porquê.

Adicione isto ao mesmo cron job:

sudo cp /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab.rb /var/opt/gitlab/backups/

Um backup só pode ser restaurado na mesma versão e edição (CE para CE, não CE para EE) do GitLab em que foi criado.

Atualize com cuidado: não restaure um backup antigo em um GitLab recém-instalado sem antes fazer o downgrade da instalação para a versão correspondente.

Teste o processo de restauração pelo menos uma vez. Um backup que nunca foi testado é só um arquivo.

Auto-hospedar o GitLab realmente vale a pena para sua equipe?

Para a maioria das equipes, auto-hospedar o GitLab é uma decisão de controle. Às vezes a conta fecha, mas o motivo pelo qual as pessoas continuam com a auto-hospedagem raramente é o item no orçamento.

Veja o custo de tempo mensal real de uma instalação para uma equipe pequena:

• ~30 minutos de atualizações – upgrades via apt, versões secundárias do GitLab
• ~15 minutos de verificação de backup – não confie em um backup que você não restaurou
• ~15 minutos de verificação de capacidade – uso de disco, folga de RAM
• ~2x se o CI/CD rodar na mesma máquina – um runner movimentado pode dobrar a carga

Isso dá cerca de uma hora por mês em uma semana tranquila, ou duas em uma semana agitada.

A cerca de US$ 150 por hora, 12 horas de tempo operacional custam cerca de US$ 1.800, o equivalente a umas cinco licenças Premium do GitLab.com.

Um estudo de caso prático da Mad Devs mostra como a equipe deles economiza mais de US$ 10.000 por ano rodando o GitLab CE auto-hospedado em vez de pagar por licenças Premium. A economia só aparece quando a equipe é grande o bastante para que as licenças por usuário dominem o orçamento.

Dito isso, auto-hospedar é a escolha errada para:

• Equipes de duas ou três pessoas sem exigências de conformidade. O GitLab.com Free atende você. O tempo operacional custa mais do que você economiza.
• Equipes sem ninguém à vontade na linha de comando. À vontade não significa nível de sysadmin. Significa conseguir ler erros de /var/log/gitlab sem entrar em pânico.
• Equipes cujo maior gargalo é contratar, não as ferramentas. A auto-hospedagem tira a atenção do produto. Se o limite é a velocidade de desenvolvimento do produto, a versão hospedada é a escolha certa.

Então, quando a auto-hospedagem faz sentido? Veja alguns cenários:

• Setores regulamentados com requisitos explícitos de residência de dados ou de cadeia de custódia
• Equipes da UE/Reino Unido preocupadas com a soberania de código hospedado nos EUA
• Equipes com mais de 30 pessoas em que as licenças por usuário dominam o orçamento
• Contratos com clientes que proíbem SaaS de terceiros para o código-fonte

Se o seu motivo é o GitHub cobra por usuário, você provavelmente vai sair ganhando. Se o seu motivo é quero me sentir no controle, talvez a realidade operacional seja menos romântica do que você imagina.

Você deve rodar os runners de CI/CD do GitLab na mesma VPS?

Para avaliação, sim. Para produção, não.

Um runner de CI na mesma máquina rouba memória e CPU da interface do GitLab. O sintoma clássico é o GitLab ficar lento às 9h, o que geralmente acontece porque um build dispara o primeiro pipeline da manhã e deixa o frontend web sem recursos. A configuração mais limpa é uma VPS separada para o runner (um Stack 8 por runner), registrada na instância do GitLab pela rede.

Se você precisar manter os runners na mesma máquina, use o Stack 32 e deixe espaço para os jobs.

De acordo com os requisitos de sistema do runner do GitLab, o processo do runner em si é leve. Já as cargas de trabalho que ele executa não são, e elas dividem a CPU e o disco da máquina com tudo o mais que o GitLab está fazendo.

Pronto para fazer a mudança?

De volta ao chat da equipe na sexta à tarde.

Se o status do GitHub ficar amarelo e sua equipe rir disso de novo e for tomar um café, tudo bem.

Mas e se a queda do GitHub começar a parecer algo sério?

Talvez esteja ameaçando um contrato com um cliente? Apareceu em uma auditoria de conformidade? Ou a conta das licenças por usuário finalmente passou do limite?

Auto-hospedar o GitLab CE passa a ser uma opção totalmente razoável. Basta uma VPS, um domínio, uma instalação Omnibus e uma hora de reforço de segurança.

Na próxima vez que a página de status do GitHub acender, seus pushes vão continuar funcionando normalmente.

Perguntas frequentes sobre auto-hospedar o GitLab