Gitea Self-Hosted: Deploy Sua Plataforma Git em VPS

Como Implantar Gitea em um Servidor VPS: Guia Completo

Implantar o Gitea em seu próprio servidor VPS permite que você tenha controle total sobre seu código-fonte, dados e ambiente de desenvolvimento, evitando as limitações e custos recorrentes de plataformas de nuvem. Este guia aborda a instalação do Gitea utilizando Docker e Docker Compose em um VPS Linux com Ubuntu 22.04 LTS, que oferece um ambiente estável e amplamente suportado. Para um ambiente de produção com até 10 usuários e repositórios moderados, o Gitea, juntamente com um banco de dados PostgreSQL, pode operar confortavelmente com 2GB de RAM e 1 vCPU, utilizando a porta 3000 para a interface web e 22 para SSH/Git. O objetivo é ter sua própria plataforma Git funcionando em aproximadamente 20 a 30 minutos.

Por Que Escolher o Gitea para Self-Hosting?

O Gitea é uma solução de hospedagem Git leve, auto-hospedada e de código aberto, projetada para ser rápida e fácil de usar. Diferente de alternativas mais robustas como GitLab, o Gitea foca na simplicidade e eficiência, sendo ideal para equipes pequenas a médias ou projetos pessoais. Ele oferece a maioria dos recursos esperados de um serviço Git moderno, como repositórios, wikis, rastreamento de issues, CI/CD básico e gestão de usuários, tudo isso com um footprint de recursos muito menor. Optar por self-hosting com Gitea significa liberdade de personalização, segurança aprimorada pelo controle direto dos seus dados e a eliminação de custos recorrentes baseados no número de usuários ou repositórios, transformando-os em um custo fixo previsível pela sua infraestrutura própria.

Controle Total sobre Seus Dados

Uma das maiores vantagens do Gitea self-hosted é o controle de dados completo. Seus repositórios, issues, wikis e informações de usuário residem exclusivamente em seu servidor, sem depender de terceiros. Isso é crucial para projetos com requisitos de conformidade rigorosos ou para quem simplesmente não confia seus ativos mais valiosos a provedores externos.

Leveza e Eficiência de Recursos

O Gitea é escrito em Go, o que o torna extremamente eficiente em termos de recursos. Em comparação com o GitLab, que pode exigir 4GB ou mais de RAM para começar, o Gitea opera confortavelmente com 2GB de RAM para uma instalação com banco de dados PostgreSQL e um número razoável de usuários. Essa eficiência o torna uma excelente escolha para quem busca otimizar o uso de recursos em um VPS.

Requisitos de Servidor para Gitea em Produção

Para garantir que seu Gitea opere de forma estável e responsiva em produção, é crucial atender aos requisitos mínimos de hardware. Baseado na minha experiência ajudando clientes, uma configuração robusta para começar é essencial.

Hardware Recomendado

• RAM: Mínimo de 2GB. Para equipes de até 10 desenvolvedores ativos e em uso moderado, 2GB é um bom ponto de partida, considerando o Gitea e o banco de dados PostgreSQL. Se planeja usar CI/CD integrado ou ter mais usuários, 4GB são recomendados.
• vCPU: 1 vCPU é suficiente para cargas de trabalho leves a moderadas. Para maior performance em compilações ou operações intensivas, 2 vCPUs proporcionarão melhor responsividade.
• Armazenamento: 20GB de espaço em disco NVMe são o mínimo para o sistema operacional, Docker e iniciais repositórios. Recomendo 40GB a 60GB para ter margem para crescimento dos repositórios e backups.

Esses requisitos garantem que o Gitea e seu banco de dados (geralmente PostgreSQL ou MySQL) tenham recursos suficientes para operar sem gargalos. Em um cenário real com um pequeno time, o Gitea consumirá cerca de 200-300MB de RAM, e o PostgreSQL outros 100-200MB em repouso, totalizando menos de 500MB, deixando bastante folga nos 2GB.

Software Necessário

• Sistema Operacional: Ubuntu 22.04 LTS (ou versão mais recente) é uma escolha sólida pela sua estabilidade e vasta documentação.
• Docker e Docker Compose: Essenciais para a orquestração do Gitea e seu banco de dados em contêineres, facilitando a implantação e o gerenciamento.
• Nginx (ou Caddy): Para atuar como proxy reverso, gerenciando certificados SSL (HTTPS), roteamento de tráfego e servindo o Gitea de forma segura na web.

Passo a Passo: Instalação do Gitea com Docker Compose no VPS

Vamos detalhar o processo de instalação do Gitea em seu VPS, utilizando Docker Compose para uma configuração robusta e fácil de manter. Este tutorial assume que você já tem um VPS Linux com acesso SSH.

1. Preparar o Ambiente no VPS

Primeiro, conecte-se ao seu VPS via SSH e atualize os pacotes do sistema. Em seguida, instale o Docker e o Docker Compose. Se você ainda não configurou o proxy reverso Nginx e a certificação SSL, considere seguir um guia como este para Uptime Kuma, que inclui passos similares para configurar Nginx com Let's Encrypt.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl gnupg2 software-properties-common apt-transport-https ca-certificates

# Instalar Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Adicionar seu usuário ao grupo docker para não precisar de sudo
sudo usermod -aG docker $USER
newgrp docker

2. Criar Diretórios e Configurar o Docker Compose

Crie um diretório para o Gitea e dentro dele, crie um arquivo docker-compose.yml. Este arquivo definirá o serviço Gitea e um banco de dados PostgreSQL.

mkdir -p ~/gitea
cd ~/gitea
nano docker-compose.yml

Cole o seguinte conteúdo no arquivo docker-compose.yml. Lembre-se de substituir <SENHA_SEGURA_DO_POSTGRES> por uma senha forte e única. A porta 3000 é a porta interna do Gitea para a interface web e 2222 para SSH/Git, que será mapeada para a porta interna do container.

version: "3.8"

services:
  gitea:
    image: gitea/gitea:1.21.9
    container_name: gitea
    restart: always
    ports:
      - "3000:3000"  # HTTP/HTTPS
      - "2222:22"    # SSH/Git
    volumes:
      - ./gitea_data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    environment:
      - DB_TYPE=postgres
      - DB_HOST=db:5432
      - DB_NAME=gitea
      - DB_USER=gitea
      - DB_PASS=<SENHA_SEGURA_DO_POSTGRES>
      - GITEA__database__DB_TYPE=postgres
      - GITEA__database__HOST=db:5432
      - GITEA__database__NAME=gitea
      - GITEA__database__USER=gitea
      - GITEA__database__PASS=<SENHA_SEGURA_DO_POSTGRES>
      - GITEA__server__ROOT_URL=https://git.seusite.com.br/
      - GITEA__server__SSH_DOMAIN=git.seusite.com.br
      - GITEA__server__SSH_PORT=2222
      - GITEA__server__HTTP_PORT=3000
    depends_on:
      - db

  db:
    image: postgres:15
    container_name: gitea_db
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=<SENHA_SEGURA_DO_POSTGRES>
      - POSTGRES_DB=gitea
    volumes:
      - ./postgres_data:/var/lib/postgresql/data

volumes:
  gitea_data:
  postgres_data:

3. Iniciar os Serviços Gitea e PostgreSQL

Com o arquivo docker-compose.yml salvo, inicie os serviços:

docker compose up -d

Aguarde alguns minutos para que os contêineres sejam baixados e inicializados. Você pode verificar o status com docker compose ps.

4. Configurar o Proxy Reverso Nginx

Para acessar o Gitea pelo seu domínio (ex: git.seusite.com.br) com HTTPS, configure o Nginx. Crie um arquivo de configuração para o seu subdomínio.

sudo nano /etc/nginx/sites-available/gitea.conf

Cole o seguinte conteúdo, substituindo git.seusite.com.br pelo seu domínio e ajustando os caminhos dos certificados SSL (que devem ser gerados com Certbot, por exemplo).

server {
    listen 80;
    server_name git.seusite.com.br;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name git.seusite.com.br;

    ssl_certificate /etc/letsencrypt/live/git.seusite.com.br/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.seusite.com.br/privkey.pem;
    ssl_trusted_certificate /etc/letsencrypt/live/git.seusite.com.br/chain.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $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;
    }

    # Configuração para SSH Git via HTTP/HTTPS se necessário
    location /ssh/ {
        proxy_pass http://localhost:2222;
        proxy_set_header Host $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;
    }
}

Crie um link simbólico para ativar a configuração e teste o Nginx:

sudo ln -s /etc/nginx/sites-available/gitea.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Agora você pode acessar o Gitea pelo seu domínio (ex: https://git.seusite.com.br) e seguir as instruções de configuração inicial na interface web. Caso necessite de mais detalhes sobre a configuração de Nginx e SSL, um recurso útil pode ser este guia sobre como instalar o N8N, que também aborda a configuração de proxy reverso com HTTPS.

Gitea vs. GitHub/GitLab: Uma Comparação Detalhada

Escolher a plataforma Git certa é crucial para o fluxo de trabalho da sua equipe. Gitea, GitHub e GitLab oferecem diferentes abordagens e recursos. Abaixo, uma comparação para ajudar na sua decisão.

Comparativo de Plataformas Git

Erros Comuns na Implantação do Gitea e Como Evitá-los

Mesmo com um guia detalhado, alguns problemas podem surgir durante a instalação. Aqui estão os mais comuns e como resolvê-los.

1. Permissões de Volume Incorretas

Problema: O Gitea não consegue escrever nos volumes de dados (gitea_data, postgres_data), resultando em erros de inicialização ou falhas ao salvar dados.
Solução: Garanta que o usuário do Docker (ou o usuário que executa o docker compose) tenha permissões de escrita nos diretórios mapeados. O Docker geralmente cria o volume com as permissões corretas, mas se você mover ou copiar os diretórios manualmente, pode precisar ajustar as permissões com sudo chown -R 1000:1000 gitea_data postgres_data, onde 1000 é o UID/GID padrão do usuário git dentro do contêiner Gitea.

2. Configuração de URL Raiz Incorreta

Problema: Redirecionamentos quebrados ou links internos do Gitea apontando para o endereço IP ou porta errada.
Solução: Verifique se a variável de ambiente GITEA__server__ROOT_URL no seu docker-compose.yml está configurada corretamente para o seu domínio completo com HTTPS (ex: https://git.seusite.com.br/). Isso é crucial para que o Gitea gere URLs corretas.

3. Conflitos de Porta

Problema: O Gitea não inicia ou o Nginx não consegue se conectar porque as portas 3000 ou 2222 já estão em uso por outro serviço.
Solução: Use sudo netstat -tulnp | grep 3000 (ou 2222) para verificar qual processo está usando a porta. Se for outro serviço seu, altere a porta no docker-compose.yml (ex: 3001:3000) e no Nginx. Para evitar isso, sempre use portas não-padrão ou certifique-se de que as portas escolhidas estão livres.

4. Erros de Configuração do Nginx/SSL

Problema: O site não carrega via HTTPS ou exibe erros de certificado.
Solução: Verifique a sintaxe do seu arquivo Nginx com sudo nginx -t. Certifique-se de que os caminhos para ssl_certificate e ssl_certificate_key estão corretos e que os certificados foram gerados e são válidos. Se estiver usando Certbot, renove os certificados se estiverem expirados.

Perguntas Relacionadas sobre Gitea Self-Hosted

O Gitea suporta autenticação LDAP/Active Directory?

Sim, o Gitea possui suporte nativo para autenticação via LDAP e Active Directory, o que facilita a integração em ambientes corporativos. Você pode configurar isso através da interface de administração do Gitea após a instalação inicial, permitindo que os usuários façam login com suas credenciais existentes da rede.

É possível usar o Gitea para CI/CD?

O Gitea oferece integração com soluções de CI/CD. Embora não possua um CI/CD nativo tão robusto quanto o GitLab, ele pode ser facilmente integrado com ferramentas como Drone CI, Jenkins ou GitHub Actions (via Gitea Actions). Isso permite automatizar testes, builds e deploys diretamente de seus repositórios Gitea.

Como faço backup do Gitea?

Fazer backup do Gitea envolve duas partes principais: o banco de dados e os volumes de dados do Gitea (repositórios, anexos, etc.). Para o banco de dados PostgreSQL, use pg_dump. Para os volumes, basta copiar o conteúdo do diretório ./gitea_data e ./postgres_data que foram mapeados no docker-compose.yml. É recomendável parar o Gitea temporariamente durante o backup para garantir a consistência dos dados, ou usar snapshots do VPS se o seu provedor oferecer.

Quais são as alternativas ao Gitea para self-hosting?

As principais alternativas self-hosted ao Gitea incluem GitLab Community Edition, que é mais robusto e rico em recursos, mas também exige mais recursos de hardware. Outra opção é o GitBucket, um servidor Git leve escrito em Scala. A escolha depende das suas necessidades de recursos, funcionalidades e facilidade de gerenciamento.

Conclusão: Sua Plataforma Git Sob Controle com Gitea

A implantação do Gitea em seu próprio VPS é um passo estratégico para quem busca total controle de dados, privacidade e a eficiência de um custo fixo. Com este guia detalhado, você tem todas as ferramentas para configurar sua própria plataforma Git, aproveitando a leveza e a robustez do Gitea. A capacidade de hospedar sua infraestrutura própria garante que seus projetos estejam sempre sob seu domínio, sem surpresas de custos ou preocupações com a privacidade de dados.

Para hospedar seu Gitea com performance e estabilidade, a Host You Secure oferece planos de VPS otimizados. Nossos clientes rodam essa mesma stack em uma VPS Brasil Starter. Recomendamos o plano VPS Brasil Starter por apenas R$ 49/mês, que, com 2GB de RAM e 2 vCPUs, é perfeitamente adequado para executar o Gitea e seu banco de dados PostgreSQL, oferecendo uma base sólida e confiável para sua plataforma Git.