Gitea com Docker em VPS: domínio, SSL, backup e runner

Gitea com Docker cabe em uma VPS pequena para uma equipe pequena. A documentação do projeto cita 2 CPUs e 1 GB de RAM como referência típica para pequenos times e projetos. Isso não transforma esse porte em promessa para banco, LFS, cópias ou CI. O ponto decisivo é o Custo de Recuperação: ter uma VPS é fácil; recuperar dados, acesso e URLs após uma falha é a parte que torna a forge utilizável.

Este guia organiza a instalação como operação. Você vai definir arquitetura, persistência, domínio, TLS, SSH, backup, restore e a decisão sobre runner. Não há saída de terminal de teste próprio neste artigo. Portanto, os tempos, os custos e os erros do seu ambiente ainda precisam ser medidos por você.

Para instalar Gitea com Docker em uma VPS, tenha domínio ou subdomínio, acesso SSH, Docker Compose, proxy com TLS e armazenamento para cópia externa. Configure volume persistente, banco interno, DNS, ROOT_URL e SSH antes de convidar usuários. Este guia não traz teste próprio: tempo e custo variam conforme a VPS, o backup e a carga.

Vale hospedar Gitea em VPS?

Gitea faz sentido quando você quer controlar repositórios, issues, wiki, pacotes ou integrações e aceita administrar a infraestrutura. Isso inclui atualizar imagens, proteger o acesso SSH, acompanhar espaço em disco e testar a recuperação. Não é automaticamente mais seguro ou mais privado do que um serviço SaaS. O resultado depende de patching, firewall, segredos, backups e de quem tem acesso à máquina.

Antes de escolher uma VPS, decida também se alguém terá disponibilidade para restaurar a instância. Se essa resposta for “não”, um serviço Git hospedado pode ser a escolha mais responsável. A economia aparente de uma VPS deixa de importar quando ninguém sabe recuperar um banco ou corrigir uma URL pública quebrada.

GitLab Self-Managed é uma comparação útil de porte, não um substituto direto. A documentação do GitLab lista baseline de nó único de 8 vCPU e 16 GB de RAM, com ao menos 8 GB em ambiente limitado por memória. Já o Gitea tem uma referência oficial menor para carga pequena. Essa diferença reforça que você deve escolher a ferramenta pelo trabalho que precisa executar, não pelo nome mais conhecido.

A arquitetura mínima: o que fica dentro e fora do container

A arquitetura enxuta tem uma VPS, um proxy reverso com TLS, o Gitea em rede interna, dados persistentes e uma cópia externa. A interface HTTP do Gitea pode ficar atrás do proxy; o banco não precisa ser público. O SSH para Git deve usar a porta que você definiu e documentou para sua equipe.

A documentação oficial de instalação com Docker usa Docker Compose, imagem do Gitea e volume persistente. Ela também oferece variantes com MySQL e PostgreSQL. Use esse material como base do arquivo Compose, em vez de copiar um exemplo aleatório de fórum.

A aplicação, o banco e os dados não são a mesma coisa. Repositórios, anexos, avatares, LFS, indexadores e o banco mudam durante o uso. Cada camada precisa de persistência planejada. Se o container for recriado sem os volumes corretos, a tela pode voltar, mas os dados podem não acompanhar.

Volume persistente não é backup

Um volume preserva dados quando o container é recriado no mesmo host. Ele não protege contra exclusão acidental, falha do disco, acesso indevido ou perda completa da VPS. Trate-o como requisito de funcionamento, não como plano de recuperação.

O mesmo raciocínio vale para snapshots de VPS. Eles podem complementar a estratégia, mas não substituem um export do banco e uma restauração testada. Uma cópia só ganha valor operacional quando você sabe restaurá-la em um ambiente separado.

Banco, repositórios, LFS e anexos

Escolha o banco com base no caminho de operação que você consegue sustentar. A documentação oficial mostra opções com MySQL e PostgreSQL. Para ambientes pequenos, a referência de recursos do Gitea não deve ser lida como capacidade garantida para tudo ao redor dele.

Disco e I/O passam a importar conforme entram repositórios maiores, LFS, anexos, pacotes, cópias e imagens de CI. Por isso, não há uma VPS universal para “Gitea em produção”. Comece pelo escopo real, acompanhe consumo e separe o runner quando CI deixar de ser uma tarefa leve.

Suba o Gitea com Docker Compose e versões fixadas

Comece pela estrutura oficial de Compose e fixe a versão da imagem que sua operação vai revisar. Evite usar uma tag mutável sem uma janela de atualização. Uma mudança de imagem não é só manutenção do container; ela afeta banco, configuração e a possibilidade de voltar atrás.

Mantenha variáveis e segredos fora do texto público do seu repositório. Senhas de banco, chaves, tokens e endereços privados não pertencem a um tutorial, a uma issue ou a uma captura. Restrinja permissões dos arquivos de configuração e defina quem pode ler esses valores.

Antes de iniciar a stack, valide quatro pontos:

1. Os dados do Gitea vão para um volume persistente definido.
2. O banco não está exposto diretamente à internet.
3. O proxy é o único componente que recebe o tráfego HTTP e HTTPS público.
4. Você sabe onde ficará a cópia externa antes de criar o primeiro repositório importante.

Também planeje a atualização antes da primeira instalação. Leia as notas da versão pretendida, faça backup consistente, registre a versão em uso e atualize em uma janela em que seja possível testar login, clone e acesso à interface. Sem cópia e sem teste, “rollback” vira apenas uma esperança.

Configure domínio, SSL, URL pública e SSH antes de convidar alguém

Use um subdomínio dedicado, como git.exemplo.com, no caminho principal. Ele simplifica a identificação da forge e reduz a complexidade de um subcaminho. Um subpath é possível, mas pede uma ROOT_URL rigorosamente alinhada ao endereço público.

Crie o registro DNS para o IP público da VPS e configure TLS no proxy reverso. A documentação do Gitea informa que, atrás de proxy, ROOT_URL deve corresponder à URL pública. Também requer os headers Host e X-Forwarded-Proto corretos. Confira essas exigências no guia oficial de proxy reverso antes de expor a instância.

O TLS pode terminar no proxy. A documentação de HTTPS do projeto orienta consultar o guia de proxy reverso quando Apache ou Nginx é usado. O objetivo é simples: o navegador acessa o domínio público em HTTPS, enquanto a aplicação recebe os encaminhamentos consistentes dentro da arquitetura.

Para Git por SSH, defina a porta escolhida e tenha certeza de que firewall, serviço SSH e URL apresentada pelo Gitea estão coerentes. Não publique a interface, o banco e um painel de Docker como se todos fossem necessários. Exponha somente o que a arquitetura realmente usa.

Faça a validação antes de convidar outras pessoas: abra a URL HTTPS, confirme que ela é a URL pública esperada e teste um clone por HTTPS e por SSH com um repositório sem dados sensíveis. Essa etapa reduz o risco de distribuir endereços errados e depois alterar clones já configurados.

Backup que serve para recuperar: cópia, retenção e teste

Backup não é uma linha de comando isolada. O Gitea reúne banco, arquivos e repositórios que podem mudar enquanto a instância está ativa. A documentação recomenda parar a instância durante o backup para evitar condições de corrida. Isso é uma orientação de consistência, não uma garantia de que qualquer arquivo copiado será recuperável.

A rotina precisa prever uma cópia externa, retenção definida pela sua necessidade e uma restauração periódica. O requisito não é ter apenas um arquivo salvo. É conseguir iniciar uma instância temporária e verificar que os elementos importantes voltaram.

O gitea dump pode fazer parte do processo, mas não deve ser tratado como resposta universal. A documentação explica que o SQL gerado usa XORM e sugere que administradores considerem ferramentas nativas de MySQL ou PostgreSQL, devido a problemas abertos de restauração. A decisão editorial aqui é direta: use o método que você consegue restaurar e provar.

Monte um ambiente temporário para ensaiar o retorno. Pare a instância conforme a orientação oficial, execute o processo de cópia escolhido, restaure os dados e valide login, clone, issue, anexo e LFS. Se você usa um runner, valide também seu estado. Registre o procedimento sem salvar token, IP, e-mail ou segredo em logs compartilhados.

Esse ensaio materializa o Custo de Recuperação. O custo não é só armazenamento externo. Inclui tempo, conhecimento e acesso para devolver o serviço quando alguma camada falhar.

Gitea Actions e Runner: instale só quando houver trabalho de CI

Não instale um runner apenas porque ele existe. Para um solo builder que quer Git, issues e wiki, começar sem Actions diminui superfície operacional e consumo de recursos. Adicione CI quando houver uma tarefa repetitiva clara, uma equipe que mantenha workflows e uma razão para administrar mais uma peça.

A documentação de Gitea Actions exige Gitea Runner e recomenda rodar runners em máquinas separadas. O motivo é evitar que o consumo dos jobs afete a instância do Gitea. Na prática, isso cria três níveis úteis:

• Sem CI: Git, issues e wiki sem runner.
• Runner na mesma VPS: compromisso de custo para jobs leves e confiáveis.
• Runner separado: escolha mais prudente quando jobs, dependências ou repositórios não devem tocar o host da forge.

O socket Docker merece atenção especial. A documentação alerta que jobs que alcançam esse socket compartilham o daemon do host. Ela também observa que o token de registro pode ser lido com docker inspect. Não trate a montagem do socket como isolamento. Ela é uma decisão de privilégio que exige confiança no workload.

No runner em Docker, /data preserva o arquivo .runner. A documentação informa que, quando ele não existe, o registro e o daemon são iniciados no primeiro start. Sem essa persistência, recriar o container pode deixar um runner obsoleto no Gitea. Inclua esse item no backup e no teste de recuperação.

Gitea ou Forgejo?

Forgejo não deve ser apresentado como “o mesmo Gitea com outro nome”. A pesquisa confirma que ele mantém documentação, guia administrativo, configuração, registro de Forgejo Runner e governança pública próprios. Isso exige consultar o caminho documental da ferramenta escolhida antes de transportar uma decisão de operação.

Gitea é o foco deste tutorial porque a instalação, proxy, backup e runner foram pesquisados em sua documentação oficial. Forgejo pode fazer sentido para quem prefere sua governança e documentação, mas compatibilidade total de workflows e extensões não deve ser prometida sem uma matriz testada no seu ambiente.

Problemas comuns e soluções

A interface abre, mas os links de clone apontam para o endereço errado

Revise ROOT_URL, o domínio público e os headers do proxy. O Gitea precisa receber a URL pública correta, Host e X-Forwarded-Proto conforme o proxy. Corrija isso antes de distribuir URLs para a equipe.

O container reiniciou e parece que os dados sumiram

Verifique se os volumes persistentes foram definidos e montados conforme a instalação oficial. Depois, confirme se o banco e o diretório de dados usados pela instância são os mesmos que sua rotina de backup cobre. Um container novo não substitui persistência.

O backup existe, mas ninguém sabe se funciona

Pare de chamar isso de plano de recuperação. Faça uma restauração em ambiente temporário e valide login, clone, issue, anexos e LFS. A documentação do Gitea trata consistência de banco, arquivos e repositórios como parte do backup.

O runner deixou a VPS lenta

Revise a carga dos jobs e considere separar o runner. A orientação oficial é usar máquinas distintas para evitar que a execução de Actions afete o Gitea. Se mantiver o mesmo host, limite o escopo a jobs leves e confiáveis.

FAQ

Gitea precisa de banco de dados separado?

A instalação oficial com Docker oferece variantes com MySQL e PostgreSQL. A escolha deve considerar o que você consegue manter, copiar e restaurar. Não exponha o banco à internet apenas para simplificar o setup.

Qual VPS é suficiente para um Gitea pequeno?

A documentação cita 2 CPUs e 1 GB de RAM como referência típica para pequenos times e projetos. Essa referência não mede banco, backups, LFS, anexos ou CI. Monitore disco, I/O e consumo ao adicionar essas cargas.

Como configurar HTTPS e domínio no Gitea Docker?

Use um subdomínio dedicado, DNS apontando para a VPS e TLS no proxy reverso. Configure ROOT_URL para o endereço público e encaminhe os headers exigidos pelo Gitea. Valide HTTPS e clones antes de convidar usuários.

O que entra no backup do Gitea?

Planeje banco, repositórios, arquivos de dados como LFS e anexos, configuração e segredos protegidos. Se usa runner Docker, inclua .runner. Snapshot de VPS complementa a estratégia, mas não substitui uma restauração ensaiada.

Posso rodar Gitea Runner na mesma VPS?

Pode ser um compromisso para jobs leves e confiáveis, mas a documentação recomenda máquinas separadas. Jobs de CI podem consumir recursos e o socket Docker compartilhado representa privilégio sobre o daemon do host.

Gitea e Forgejo usam os mesmos workflows?

Não prometa equivalência total sem teste. Forgejo possui documentação, governança e runner próprios. Verifique a documentação da ferramenta que será operada e valide workflows importantes em um repositório controlado.

Checklist final antes de colocar a instância em uso

• O diretório de dados do Gitea está em volume persistente e continua disponível após recriar o container.
• O banco não aceita conexões públicas; apenas os componentes internos autorizados conseguem acessá-lo.
• O DNS aponta para a VPS, o proxy entrega TLS e ROOT_URL corresponde exatamente ao endereço HTTPS público.
• O firewall, a porta SSH e a URL de clone exibida pelo Gitea estão coerentes; clone por HTTPS e SSH foi validado em repositório sem dados sensíveis.
• Existe uma cópia externa protegida, com retenção definida, para banco, repositórios, LFS, anexos, app.ini e segredos necessários.
• O backup é executado de forma consistente, com a parada da instância quando o procedimento escolhido exigir, e há um restore ensaiado em ambiente temporário.
• Após o restore, login, clone, issue, anexo e arquivo LFS foram verificados sem expor segredos em logs.
• Se houver Gitea Runner em Docker, o diretório /data persiste o arquivo .runner, entra na cópia e foi conferido após a recuperação.

Conclusão: compre infraestrutura só depois de desenhar a recuperação

A boa instalação de Gitea não termina no login. Ela termina quando domínio, TLS, SSH, volumes, backup externo e restore de teste formam um caminho que você entende. O runner entra depois, quando a automação justifica uma nova zona de custo e risco.

Se você já tem esse checklist e precisa de uma base para operar Git, cópias e automações leves, veja uma VPS para rodar seu servidor Git. Escolha o porte pelo que precisa recuperar e operar, não apenas pela aplicação que cabe na memória. Esse é o Custo de Recuperação em prática.