GitHub Enterprise Server em VPS Linux: Guia de Instalação

Você precisa de controle total sobre seus dados de código-fonte, mas os repositórios públicos do GitHub padrão expõem sua propriedade intelectual a riscos de conformidade e latência? Neste tutorial, vamos instalar o GitHub Enterprise Server (GHE) em uma VPS Linux dedicada, entregando você a uma infraestrutura Git privada, segura e sob sua administração direta.

O GitHub Enterprise Server não é apenas uma ferramenta de versionamento; é o coração da sua estratégia DevOps quando a soberania de dados é crítica. Diferente das edições Cloud ou do GitHub Free, a versão "Appliance" roda em seu próprio ambiente, exigindo configuração manual de hardware e software. Para profissionais de TI e sysadmins no Brasil, isso significa eliminar a latência de servidores externos e garantir que o histórico de commits nunca saia do seu datacenter ou provedor de cloud preferido.

Abaixo, detalhamos o processo técnico para provisionar essa solução robusta em um ambiente Linux moderno. O foco aqui é a instalação via ISO ou imagem oficial em hardware virtualizado (VPS) ou dedicado.

Pré-requisitos de Infraestrutura

Antes de baixar qualquer arquivo, você precisa garantir que o ambiente de destino atenda aos requisitos mínimos de hardware. O GitHub Enterprise Server é uma aplicação pesada que consome recursos significativos de CPU, RAM e disco para indexação e processamento de dados. Instalar em um servidor subdimensionado resultará em instabilidade e lentidão extrema na interface web e no clone de repositórios.

A tabela abaixo resume as especificações técnicas recomendadas pela documentação oficial para uma instalação padrão de produção:

Além do hardware, você precisa ter acesso root ou sudo completo à sua VPS Linux. A instalação exige a criação de usuários específicos e o ajuste de configurações de kernel (sysctl) que usuários comuns não podem modificar. Certifique-se também de que o firewall da sua VPS permita as portas 22 (SSH), 80 (HTTP), 443 (HTTPS) e 8443 (Admin Console) para a máquina de destino.

Outro ponto crucial é o nome de domínio (DNS). O GHE não funciona bem com IPs públicos diretos sem configuração complexa de certificados SSL autoassinados. Você deve ter um subdomínio registrado e apontando para o IP da sua VPS, por exemplo: git.suaempresa.com.br. A certificação SSL é automática após a instalação, mas depende de um DNS funcional.

Passo a passo da instalação

A instalação do GitHub Enterprise Server segue uma lógica sequencial: download da imagem, provisionamento do sistema base, configuração inicial via console administrativo e aplicação de licenças. Vamos dividir este processo em etapas claras para evitar erros comuns de configuração.

1. Preparação do Ambiente Linux

A primeira etapa é garantir que o SO esteja limpo e atualizado. O GHE vem em uma ISO proprietária, mas se você estiver usando uma imagem personalizada ou um appliance pré-compilado, a base precisa estar estável. Para este tutorial, assumiremos que você já fez o upload da ISO oficial do GitHub Enterprise Server no seu hipervisor (Proxmox, VMware, KVM) e inicializou a VM.

No entanto, se você estiver configurando o servidor de suporte (backup server) ou preparando o disco, os comandos abaixo são essenciais para otimizar o Linux para bancos de dados e sistemas de arquivos:

# Atualize o sistema operacional
sudo apt update && sudo apt upgrade -y

# Instale dependências básicas caso precise compilar módulos ou usar scripts auxiliares
sudo apt install -y curl wget git unzip rsync

Se estiver em um ambiente RHEL/CentOS, substitua apt por yum ou dnf. A prioridade agora é garantir que o disco tenha a montagem correta. O GHE exige sistemas de arquivos que suportem extensões de atributos estendidos (xattrs) para funcionalidades de segurança e cache.

2. Configuração Inicial via Console Web

Após inicializar a VM com a ISO do GitHub Enterprise Server, o sistema irá iniciar um serviço web local na porta 8443. Acesse https://<IP-DA-VPS>:8443 pelo navegador. Você verá um aviso de certificado SSL inválido (pois é autoassinado inicialmente). Aceite o risco e prossiga.

O assistente de configuração inicial pedirá informações básicas:

• Hostname: Defina o FQDN que você configurou no DNS (ex: git.seudominio.com).
• Senha do Administrador: Crie uma senha forte e única. Esta será a credencial da conta admin.
• Tipo de Instalação: Escolha entre "Single Node" (nó único) ou "High Availability" (HA). Para a maioria das VPSs individuais, selecione Single Node.

Após confirmar, o sistema aplicará as configurações de rede e reiniciará os serviços de rede. Isso pode levar alguns minutos. Não feche a janela durante esse processo.

3. Aplicação da Licença

O GitHub Enterprise Server é um produto comercial. Sem uma licença válida, ele entrará em modo de avaliação (trial) ou será bloqueado após o período expirado. Você deve ter recebido um arquivo de licença (.ghe) da equipe de vendas do GitHub ou através da sua conta corporativa.

Depois que o servidor reiniciar e você conseguir acessar o painel administrativo novamente via seu domínio configurado, faça login com o usuário admin. No menu lateral, navegue até Settings > License.

Carregue o arquivo de licença. O sistema validará a assinatura digital e o número de usuários permitidos. Se a licença for válida, o status mudará para "Active". Sem este passo, suas equipes não poderão criar repositórios privados ou usar funcionalidades avançadas do Actions.

4. Configuração de SSL e Rede

Agora que a licença está ativa, precisamos garantir que a comunicação seja segura via HTTPS. O GHE suporta a geração automática de certificados Let's Encrypt se o servidor tiver acesso direto à internet externa na porta 80. Se sua VPS estiver atrás de um load balancer ou firewall que não repassa a verificação HTTP, você precisará fazer o upload manual dos certificados.

No painel de administração, vá em Settings > Network > SSL/TLS. Se estiver usando Let's Encrypt:

1. Marque a opção "Automatically provision certificates".
2. Insira seu email de contato.
3. Clique em "Provision" e aguarde a validação do DNS/HTTP-01 challenge.

Se você possui certificados próprios (PKI corporativa), faça o upload do arquivo .crt e da chave privada .key. Após a instalação, force a redirecionamento HTTP para HTTPS para garantir que nenhum dado trafegue em texto plano.

Verificação e Teste de Conexão

Com a instalação concluída, é hora de validar se o servidor está operando corretamente. Um sysadmin não confia apenas na interface web; ele testa a infraestrutura pelos protocolos que seu time utilizará no dia a dia.

Crie um usuário de teste ou use sua conta admin para criar um repositório vazio chamado test-repo. Anote o URL SSH e HTTPS do repositório. Geralmente, o formato SSH é:

git@git.seudominio.com.br:testuser/test-repo.git

No seu computador local (cliente), execute os seguintes comandos para verificar a latência e a integridade da conexão:

# Teste de conexão SSH
ssh -T git@git.seudominio.com.br

# Clone do repositório
git clone https://git.seudominio.com.br/testuser/test-repo.git

# Verifique o status do servidor via API (requer token admin)
curl -H "Authorization: token SEU_TOKEN_ADMIN" \
     https://git.seudominio.com.br/api/v3/admin/ping

A resposta ao comando ping da API deve ser um JSON simples indicando sucesso. Se o clone for rápido e o SSH autenticar sem erros, sua instalação está funcional. Verifique também a seção "Status" no painel administrativo para garantir que todos os serviços (Git, Gist, Packages, Actions) estão marcados como "Running".

Troubleshooting Comum

Erros na instalação do GitHub Enterprise Server podem ser frustrantes. Abaixo, listamos os problemas mais frequentes enfrentados por administradores e suas respectivas soluções.

Erro de DNS ou Indisponibilidade do Hostname

Sintoma: O servidor inicia, mas o console web não carrega ou retorna erro 502/504. O log mostra erros de resolução de nome.

Solução: Verifique se o arquivo /etc/hosts na VPS contém o mapeamento correto do IP para o hostname. O GHE é muito rigoroso com a resolução reversa (PTR) do DNS. Certifique-se de que o registro A do seu domínio aponta para o IP da VPS e que o registro PTR (reverse DNS) no painel do provedor de hospedagem está configurado para o mesmo hostname.

Falha na Geração de Certificado SSL

Sintoma: O Let's Encrypt falha ou o upload de certificado manual é rejeitado.

Solução: Verifique se a porta 80 está aberta e acessível publicamente. O Let's Encrypt precisa validar a posse do domínio através de um arquivo temporário na raiz web. Se você usa Cloudflare ou outro proxy, desative o modo "Proxy" (nuvem laranja) temporariamente para a subdomínio de verificação. Para certificados manuais, assegure-se de que a chave privada não está protegida por senha.

Alta Carga de CPU e Disk I/O

Sintoma: A interface web fica lenta para responder, clones falham com timeout.

Solução: Isso geralmente indica que o servidor está subdimensionado ou que há um processo de indexação pesado em andamento (como após a importação de repositórios grandes). Verifique o uso de disco com iostat -x 1. Se o uso de disco estiver em 100%, considere migrar para discos NVMe. Evite rodar outros serviços pesados (como bancos de dados PostgreSQL ou Docker) na mesma instância do GHE.

Falha nas Configurações de Backup

Sintoma: O job diário de backup falha ao tentar enviar para o servidor NFS/S3.

Solução: Verifique as permissões de rede e armazenamento. No painel de administração, vá em Settings > Backup. Teste a conexão com o destino de backup manualmente usando o botão "Test". Certifique-se de que o caminho do diretório NFS existe e tem permissão de escrita para o usuário do sistema GHE.