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

**Autor:** Maicon Ramos
**Categoria:** Hospedagem & VPS
**Publicado:** 2026-09-27
**Atualizado:** 2026-09-27
**Canonical:** https://runzos.com/como-instalar-gitea-docker-vps-2026/

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. Perfil Gitea em uma VPS Gitea + runner separado SaaS Git Condição de escolha Solo dev Bom ponto de partida Somente se CI crescer Alternativa simples Escolha Gitea se você mantiver backup e atualização. Agência pequena Possível para Git e colaboração Preferível quando jobs consumirem recursos Útil se a equipe não opera servidores Separe capacidade de CI da forge quando necessário. Equipe com compliance Exige controles próprios Ajuda a separar cargas Depende do fornecedor e da política interna Modele acesso, retenção e recuperação antes da ferramenta. Projeto open source Funciona se houver operação contínua Indicado para automações confiáveis Reduz carga operacional Considere quem sustenta suporte e manutenção. 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: Os dados do Gitea vão para um volume persistente definido. O banco não está exposto diretamente à internet. O proxy é o único componente que recebe o tráfego HTTP e HTTPS público. 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. Item Por que copiar Referência operacional Teste de recuperação Banco Guarda dados da aplicação Prefira ferramentas nativas de MySQL ou PostgreSQL quando aplicável. Restaure em ambiente temporário e confirme acesso aos dados. Repositórios São o código e o histórico Git Entram no conjunto que precisa permanecer consistente. Faça clone de validação após o restore. LFS e anexos Podem conter ativos fora do fluxo Git comum O diretório de dados do dump inclui LFS, anexos e outros arquivos. Abra issue, anexo e arquivo LFS restaurados. `app.ini` e segredos Reconstituem configuração e acesso Proteja cópias e permissões. Valide URL pública e autenticação sem expor valores. `.runner` Preserva o registro do runner O diretório `/data` guarda esse arquivo no runner Docker. Confirme que o runner não ficou obsoleto. 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.

## Leia também

- [Como criar um agente de IA com LangChain, Qdrant e Docker em VPS](https://runzos.com/como-criar-agente-ia-langchain-qdrant-docker-vps/)
- [LangChain vs LlamaIndex vs n8n: stack para agentes de IA em 2026](https://runzos.com/langchain-vs-llamaindex-n8n-agentes-ia-2026/)
- [LangChain em VPS: vale a pena para agentes de IA e RAG em 2026?](https://runzos.com/langchain-vps-agentes-rag-ia-2026/)
- [Como rodar Qdrant com Docker em VPS: backup, SSL e custo](https://runzos.com/como-rodar-qdrant-docker-vps-2026/)