Hospede o Gitea e tenha seu próprio servidor Git

Você quer seus repositórios numa máquina que você controla: código privado que nunca sai da sua infraestrutura, sem cobrança por usuário e uma interface web que a sua equipe já sabe usar. O Gitea te dá isso num único container: navegação de repositórios, pull requests, issues, um registro de pacotes e Git por HTTPS e SSH. Este guia leva você de um servidor vazio ao Gitea no seu próprio domínio, com HTTPS via Caddy, pushes por SSH numa porta própria e um backup que você já restaurou pelo menos uma vez. A última parte mostra a versão de um clique no Railyard.

Este guia usa o Gitea 28.2.0, a versão atual, direto do registro próprio do Gitea em docker.gitea.com. O Gitea saiu da numeração 1.x para 28.0.0 em setembro de 2026, então uma tag “28” é a versão mais nova, não um erro de digitação.

O que você vai precisar

• Um servidor. O Gitea é leve. Um Hetzner CX23 (2 vCPUs, 4 GB de RAM, 40 GB NVMe) custa €5,99/mês sem VAT e é mais que suficiente para uma equipe pequena. Os repositórios crescem, então fique de olho no disco.
• Um domínio ou subdomínio que você possa apontar para o servidor. Este guia usa git.example.com.
• Acesso SSH como root ou um usuário com sudo.
• Uma porta livre no host para o Git sobre SSH. O SSH do próprio servidor fica na porta 22, então o servidor SSH do Gitea usa a porta 222, o mapeamento que a documentação do Gitea usa.

Etapa 1: Aponte o DNS para o servidor e atualize-o

Crie o servidor e adicione um registro A para git.example.com apontando para o IPv4 público dele. Faça isso primeiro: o Caddy só consegue obter um certificado depois que o nome resolver para o seu servidor.

ssh root@203.0.113.20
apt update && apt upgrade -y

Na sua própria máquina, confira o registro:

dig +short git.example.com

Você deve ver o IP do seu servidor. Se ainda não aparecer, continue e verifique de novo antes da Etapa 5.

Etapa 2: Instale o Docker

O Gitea e o Caddy rodam como containers, então o Docker Engine com o plugin Compose é tudo que você precisa:

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
docker compose version

Você deve ver uma linha Docker Compose version.

Etapa 3: Escreva o arquivo Compose

O Gitea roda em SQLite a menos que você aponte para outro banco de dados. O SQLite guarda tudo num único volume e funciona bem para uma equipe pequena, então este guia usa ele (o FAQ cobre o Postgres). Crie o diretório:

mkdir -p /opt/gitea/backups
cd /opt/gitea

Salve isto como /opt/gitea/compose.yaml, com o seu próprio domínio:

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    depends_on:
      - gitea

  gitea:
    image: docker.gitea.com/gitea:28.2.0
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      GITEA__server__DOMAIN: git.example.com
      GITEA__server__ROOT_URL: https://git.example.com/
      GITEA__server__SSH_DOMAIN: git.example.com
      GITEA__server__SSH_PORT: "222"
    volumes:
      - gitea-data:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "222:22"

volumes:
  gitea-data:
  caddy-data:
  caddy-config:

O que isso faz:

• A imagem, USER_UID/USER_GID, os mounts de time zone e o mapeamento 222:22 vêm direto da documentação Docker do Gitea. Dentro do container, um servidor SSH escuta na porta 22 para o Git; o host expõe isso como 222.
• As variáveis GITEA__section__KEY definem valores no app.ini do Gitea. ROOT_URL faz o Gitea construir links HTTPS, e SSH_PORT faz as URLs de clone mostradas usarem 222. Elas também pré-preenchem o assistente de configuração.
• A porta web do Gitea, 3000, não é publicada. O Caddy acessa ela pela rede do Compose, então a única entrada pela web é via HTTPS.
• Tudo que o Gitea guarda (repositórios, o banco SQLite, uploads e o app.ini) vive no volume gitea-data. Um volume nomeado também cuida da propriedade dos arquivos para você.

Etapa 4: Escreva o Caddyfile

Salve isto como /opt/gitea/Caddyfile:

git.example.com {
	encode zstd gzip
	reverse_proxy gitea:3000
}

O Caddy obtém um certificado Let’s Encrypt para o domínio, redireciona HTTP para HTTPS e faz proxy da interface web e do Git sobre HTTPS para o Gitea. O Git sobre SSH não passa pelo Caddy: ele vai direto para a porta 222. Confira os dois arquivos:

docker compose config --quiet && echo "compose ok"
docker compose run --rm --no-deps caddy caddy validate --config /etc/caddy/Caddyfile

Você deve ver compose ok, depois Valid configuration.

Etapa 5: Abra as portas e inicie

Libere as portas 80, 443 e 222 no firewall do seu provedor de nuvem. Depois inicie a stack:

docker compose up -d
docker compose ps
docker compose logs -f caddy

Você deve ver caddy e gitea com status Up, e o Caddy registrando nos logs que obteve um certificado para git.example.com. Pressione Ctrl+C e abra https://git.example.com. Você deve ver a página de instalação do Gitea.

Etapa 6: Termine o assistente de configuração

O Gitea não vem com nenhuma conta padrão: a primeira visita abre uma página de instalação que só aparece uma vez. Confira os valores, a maioria já preenchida pelas variáveis de ambiente:

• Database Type: SQLite3, com o caminho /data/gitea/gitea.db.
• SSH Server Port 222 e Gitea Website URL https://git.example.com/. A caixa Environment Configuration no final da página lista as variáveis GITEA__ que serão gravadas em /data/gitea/conf/app.ini.
• Only administrators can create user accounts (no self-registration): marque essa opção se só a sua equipe deve ter contas.
• Administrator Account Settings, em Optional Settings: defina um usuário, e-mail e senha. A própria página avisa: se você pular isso, o primeiro usuário a se registrar se torna administrador.

Clique em Install Gitea. Você deve cair no seu painel, já logado como administrador.

Agora teste as duas formas de dar push. Adicione sua chave pública em Settings → SSH / GPG Keys, crie um repositório chamado test-repo e, na sua máquina:

git clone ssh://git@git.example.com:222/youradmin/test-repo.git
git clone https://git.example.com/youradmin/test-repo.git test-repo-https

Os dois clones devem funcionar. Use a forma ssh:// com a porta explícita: a forma curta git@host:owner/repo sempre usa a porta 22.

Etapa 7: Faça backup do Gitea

O gitea dump escreve repositórios, o banco de dados, o app.ini e os arquivos enviados em um único arquivo compactado. Ele precisa rodar como usuário git, porque o Gitea se recusa a rodar como root. Salve isto como /opt/gitea/backup.sh:

#!/usr/bin/env bash
set -euo pipefail
cd /opt/gitea
docker compose exec -T -u git -w /tmp gitea gitea dump -c /data/gitea/conf/app.ini --file - > "backups/gitea-$(date +%F).zip"
find backups -name 'gitea-*.zip' -mtime +14 -delete

--file - transmite o arquivo direto para a saída padrão, então ele cai no host diretamente. Torne executável, rode uma vez e agende para as 03:00 com crontab -e:

chmod +x /opt/gitea/backup.sh
/opt/gitea/backup.sh
unzip -l /opt/gitea/backups/gitea-$(date +%F).zip | tail -3

0 3 * * * /opt/gitea/backup.sh

Você deve ver uma lista de arquivos terminando num total. Copie os arquivos para fora do servidor também, por exemplo com rsync para outra máquina.

Para restaurar numa instalação nova, suba o Gitea com um volume vazio, copie o arquivo para dentro e coloque cada parte de volta no seu lugar:

docker compose up -d gitea
docker compose cp backups/gitea-2026-05-25.zip gitea:/tmp/restore.zip
docker compose exec gitea sh -c 'mkdir -p /tmp/r && cd /tmp/r && unzip -q /tmp/restore.zip && mkdir -p /data/gitea/conf /data/git/repositories && cp app.ini /data/gitea/conf/app.ini && cp -a data/. /data/gitea/ && cp -a repos/. /data/git/repositories/ && chown -R git:git /data/gitea /data/git'
docker compose restart gitea
docker compose exec -u git gitea gitea -c /data/gitea/conf/app.ini admin regenerate hooks

Isso segue os passos de restauração da própria documentação de backup do Gitea para Docker. Você deve ver seus repositórios e seu login de administrador de volta, sem a página de instalação.

Etapa 8: Faça upgrade

O Gitea roda suas migrações de banco de dados quando inicia. Leia as release notes, faça um backup, troque a tag da imagem em compose.yaml e então:

/opt/gitea/backup.sh
docker compose pull gitea
docker compose up -d gitea
docker compose logs -f gitea

Você deve ver o Gitea iniciar e voltar a atender requisições. Se ele falhar ao iniciar, o log indica a configuração ou migração com problema; volte para a tag antiga e restaure o backup se precisar fazer rollback.

O caminho curto: faça com o Railyard

As Etapas 2 a 5 são o que o template de Gitea do Railyard faz por você: faça o deploy do Gitea no Railyard. O Railyard constrói o Gitea a partir do repositório dele com seu próprio Dockerfile, roda num servidor que é seu e dá a ele um endereço HTTPS. Você pode adicionar seu próprio domínio na aba Domains do app (Domains and HTTPS). Depois você termina o mesmo assistente de configuração da Etapa 6 no endereço do app: defina Gitea Website URL como o endereço HTTPS do app e crie a conta de administrador.

Duas coisas para configurar antes de criar repositórios:

• Mantenha /data num volume. O template não anexa um automaticamente, então adicione data:/data em Volumes nas configurações do app. Os volumes são mantidos entre deploys, e você pode fazer backup de um com railyard volume:backup <app> data.
• Escolha o banco de dados. O template não anexa nenhum add-on de banco de dados, então o Gitea usa SQLite dentro de /data. Se você quiser Postgres em vez disso, adicione na aba Resources do app primeiro e informe o host, nome, usuário e senha dele na seção de banco de dados do assistente, já que mudar de banco depois que os repositórios já existem dá mais trabalho. Os backups do Postgres no Railyard estão em Databases and backups.

O Railyard publica a porta web do Gitea via HTTPS, então no Railyard você clona e dá push via HTTPS em vez de SSH. O plano Free do Railyard cobre um servidor mais um servidor de banco de dados e três apps, sem cartão. O Pro custa US$19/mês e o Team, US$49/mês, por equipe.

Solução de problemas

address already in use na porta 80, 443 ou 222. Descubra o que está escutando com ss -tlnp | grep -E ':(80|443|222)\s'. Para a 222, você pode escolher outra porta no host (2222:22, por exemplo), desde que GITEA__server__SSH_PORT corresponda a ela.

As URLs de clone mostram o host, a porta ou o http:// errados. O Gitea grava essas configurações em /data/gitea/conf/app.ini. Confira ROOT_URL, DOMAIN, SSH_DOMAIN e SSH_PORT no ambiente, recrie o container com docker compose up -d gitea e confirme que os valores em app.ini mudaram.

O Caddy não consegue obter um certificado. Confira se dig +short git.example.com retorna o IP do seu servidor e se a porta 80 está aberta no firewall do seu provedor, já que o Let’s Encrypt valida por ela. O Caddy tenta de novo por conta própria depois que o DNS estiver correto.

Permission denied (publickey) ao clonar via SSH. Confirme que a chave foi adicionada no Gitea (não no authorized_keys do próprio servidor), que você está conectando na porta 222 com a forma de URL ssh://, e que o usuário é git, não o seu nome de usuário do Gitea.

gitea dump diz que o Gitea não deve rodar como root. Você esqueceu o -u git. O docker compose exec roda como root a menos que você diga o contrário.

O servidor fica sem memória. O Gitea é pequeno em repouso, mas clonar ou dar push de um repositório muito grande pode fazer a memória disparar. Confira dmesg | grep -i "out of memory" e docker stats, e redimensione se isso acontecer de novo.

Perguntas frequentes

SQLite é suficiente, ou devo usar Postgres? SQLite funciona bem para uma equipe pequena. A documentação Docker do Gitea inclui uma variante com Postgres: adicione um serviço db e defina GITEA__database__DB_TYPE=postgres, GITEA__database__HOST=db:5432, GITEA__database__NAME, GITEA__database__USER e GITEA__database__PASSWD no serviço do Gitea. Decida antes da primeira instalação, porque o assistente grava a escolha no app.ini.

Posso trazer meus repositórios do GitHub ou GitLab? Sim. A página New Migration do Gitea tem importadores para GitHub, GitLab, Gitea e outros serviços, além de uma opção de Git puro para qualquer URL. Os importadores específicos de cada serviço podem trazer mais do que o código, como issues e releases, dependendo da origem.

O Gitea tem CI como o GitHub Actions? O Gitea Actions usa arquivos de workflow próximos da sintaxe do GitHub Actions, e os roda num runner separado que você instala por conta própria. Configurar um runner está fora do escopo deste guia.

Por que a porta 222? Para manter o login SSH do próprio servidor na porta 22. Qualquer porta livre funciona, desde que SSH_PORT corresponda ao lado do host no mapeamento.

Um servidor Git self-hosted se resume, na maior parte, a três coisas: as URLs certas no app.ini, uma porta SSH que não colide com a sua própria, e um backup que você de fato já restaurou. Acerte isso no primeiro dia e o Gitea praticamente cuida do resto por conta própria.