Base de Conhecimento

Gitea na VPS: seu servidor Git próprio com Docker

  • gitea, git, docker, vps, docker compose
  • Usuários acharam útil: 0

Veja como instalar o Gitea numa VPS com Docker Compose: requisitos, MySQL, cadastro fechado, portas web e SSH, backup com gitea dump e atualização da imagem.

Por Redação Eleven Host · @robson.direitodigital · 2 de novembro de 2026 · 9 min de leitura

Arte da Eleven Host: janela de terminal com o título: Gitea na VPS: seu servidor Git próprio com Docker

Capa da Redação Eleven Host para o guia: Gitea na VPS: seu servidor Git próprio com Docker Arte: Eleven Host

Gitea na VPS é uma forma de ter o seu próprio servidor Git, com os repositórios do seu código num servidor que você controla. O Gitea roda em Docker com um arquivo Compose e poucos comandos.

Neste guia você vê o que é o Gitea, o que a licença traz e o que a documentação pede de requisitos. Depois, como subir com Docker Compose, trocar o banco por MySQL, fechar o cadastro de novos usuários, ajustar as portas, fazer backup e atualizar. Se você ainda não conhece o servidor VPS, comece por O que é servidor VPS: guia simples para iniciantes. Os exemplos partem de uma VPS com Docker e Docker Compose já instalados.

O que é o Gitea

A documentação oficial define o Gitea como um serviço de desenvolvimento de software completo, simples de instalar e que você hospeda por conta própria (self-hosted).

Na versão 28.3.0, segundo a página de releases do projeto no GitHub, que a marca como Latest, o changelog tem a data de 1 de novembro de 2026. A documentação de Docker usa a mesma tag de imagem, 28.3.0, e é a que os exemplos abaixo usam.

Licença do Gitea

O arquivo LICENSE do repositório traz os direitos autorais de The Gitea Authors (2016) e de The Gogs Authors (2015) e o texto padrão da licença MIT, que concede permissão, sem custo, a quem obtiver uma cópia do software e dos arquivos de documentação associados.

O Gitea é distribuído sob a licença MIT, segundo o arquivo LICENSE do repositório. Em caso de dúvida sobre uso comercial, consulte um profissional.

Requisitos segundo a documentação

A documentação diz que um Raspberry Pi 3 tem força para rodar o Gitea em cargas pequenas. Para equipes e projetos pequenos, ela cita 2 núcleos de CPU e 1 GB de RAM como suficientes.

A página também diz que, em sistemas do tipo UNIX, o Gitea deve rodar com uma conta de sistema dedicada, sem privilégios de administrador, e que o Git precisa estar na versão 2.0.0 ou superior. No exemplo de Docker, o USER_UID e o USER_GID aparecem nas variáveis do Compose.

Está comparando planos de servidor? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver os planos de VPS

Subir o Gitea com Docker Compose

A documentação afirma que o Gitea oferece imagens Docker atualizadas automaticamente dentro da sua organização no Docker Hub. O arquivo básico usa SQLite, ou seja, não precisa de um serviço de banco separado. Crie uma pasta, salve o conteúdo abaixo como docker-compose.yml e mantenha a indentação:

networks:

  gitea:

    external: false

services:

  server:

    image: docker.gitea.com/gitea:28.3.0

    container_name: gitea

    environment:

      - USER_UID=1000

      - USER_GID=1000

    restart: always

    networks:

      - gitea

    volumes:

      - ./gitea:/data

      - /etc/timezone:/etc/timezone:ro

      - /etc/localtime:/etc/localtime:ro

    ports:

      - "3000:3000"

      - "222:22"

Depois, rode os comandos da documentação. O primeiro sobe os serviços em segundo plano e o segundo confere se estão de pé:

docker compose up -d

docker compose ps

Para ver os registros, use docker compose logs. Para parar, use docker compose down: os volumes ficam, e os dados em ./gitea continuam no servidor.

Trocar o SQLite pelo MySQL

A mesma página mostra como usar um banco separado. Para o MySQL, entram estas variáveis no serviço server:

      - GITEA__database__DB_TYPE=mysql

      - GITEA__database__HOST=db:3306

      - GITEA__database__NAME=gitea

      - GITEA__database__USER=gitea

      - GITEA__database__PASSWD=SENHA_DO_BANCO

E o serviço db, no mesmo arquivo, com a imagem docker.io/library/mysql:8. O serviço server ganha também um depends_on apontando para db:

    depends_on:

      - db

  db:

    image: docker.io/library/mysql:8

    restart: always

    environment:

      - MYSQL_ROOT_PASSWORD=SENHA_ROOT_DO_BANCO

      - MYSQL_USER=gitea

      - MYSQL_PASSWORD=SENHA_DO_BANCO

      - MYSQL_DATABASE=gitea

    networks:

      - gitea

    volumes:

      - ./mysql:/var/lib/mysql

No exemplo da documentação, as senhas do banco são a palavra gitea, valor de demonstração. Troque por senhas suas, e a do GITEA__database__PASSWD tem de ser igual à de MYSQL_PASSWORD. Para PostgreSQL, a página usa a imagem docker.io/library/postgres:18, o host db:5432 e o volume ./postgres:/var/lib/postgresql, e avisa que o PostgreSQL não atualiza a pasta de dados sozinho entre versões principais.

Primeiro acesso e configuração

Segundo a documentação, depois de subir o Compose você visita http://IP-DO-SERVIDOR:3000 e segue o assistente de instalação. Se o banco estiver no Compose, use db como host do banco. Os dados ficam em /data dentro do contêiner, que o exemplo mapeia para ./gitea no servidor, e o arquivo de configuração é salvo em /data/gitea/conf/app.ini depois da instalação.

As opções do app.ini podem ser definidas ou sobrescritas por variável de ambiente, no formato GITEA__secao__NOME_DA_CHAVE=valor. A documentação diz que essas variáveis são aplicadas a cada vez que o contêiner inicia, pelo comando environment-to-ini. A forma GITEA__secao__NOME_DA_CHAVE__FILE lê o valor de um arquivo.

Portas web e SSH

No exemplo, a interface web usa a porta 3000. O SSH do contêiner escuta na 22 e é publicado no servidor como 222 ("222:22"), e não na 22 do próprio servidor. A documentação diz que, para mudar a porta do SSH embutido e a do servidor web, você ajusta a seção de portas, e que é comum mudar só a porta do servidor e manter as portas internas do contêiner como estão. Os exemplos da página usam 2221 no servidor para o SSH.

Se a porta do HTTP não for a 3000, ajuste a URL no app.ini. Como a porta do SSH muda, as URLs de clone por SSH dependem da opção SSH_PORT, que define o número exibido na URL de clone. Para conferir o que está escutando no servidor, veja Portas abertas no Linux: como ver com ss e lsof na VPS.

Fechar o cadastro de novos usuários

Com o endereço do Gitea publicado, pense em quem pode criar contas. A referência de configuração descreve três opções, e o próprio exemplo do app.ini traz a linha DISABLE_REGISTRATION = true, comentada:

  • DISABLE_REGISTRATION: desativa o cadastro, e depois disso só o administrador cria contas para os usuários. Defina esta opção de forma explícita como true, ou marque a opção correspondente no assistente, e confira no painel se o cadastro ficou fechado.
  • REQUIRE_SIGNIN_VIEW: o padrão é false. Ativada, força o login para ver as páginas ou usar a API.
  • INSTALL_LOCK: o padrão é false. Com o valor true, a página de instalação deixa de ficar acessível.

Para definir pelo Compose, a regra das variáveis de ambiente vale. Este é um exemplo montado a partir dessa regra, para a lista environment do serviço server:

      - GITEA__service__DISABLE_REGISTRATION=true

Depois de editar o arquivo, rode docker compose up -d de novo para o contêiner reiniciar com a variável.

Atualizar o Gitea

A documentação pede, antes de tudo, que os dados estejam num volume fora do contêiner, como no exemplo. Se a versão da imagem está fixada no Compose, troque a tag pela nova e rode:

docker compose pull

docker compose up -d

O primeiro baixa a imagem e o segundo recria o contêiner com ela. Faça um backup antes, como no próximo passo.

Backup do Gitea

O comando base da documentação é o gitea dump, executado como o usuário do Gitea:

./gitea dump -c /path/to/app.ini

No Docker, a documentação combina o docker exec com o mesmo comando dentro do contêiner e exige a opção RUN_USER definida no app.ini. Um exemplo com os campos da página, usando gitea como nome do contêiner:

docker exec -u <OS_USERNAME> -it -w <TEMPDIR> gitea bash -c '/usr/local/bin/gitea dump -c /data/gitea/conf/app.ini'

O arquivo gerado traz o app.ini (se estiver fora do padrão), a pasta custom/, a data/, a repos/ (cópia completa do diretório de repositórios), o banco em gitea-db.sql e os registros em log/. A documentação também diz que a instância deve estar desligada durante o backup. Como o comando do Docker roda dentro do contêiner, recomendamos gerar o dump num horário sem uso, com os usuários avisados, e conferir a página de backup da documentação da sua versão.

Atenção ao restaurar: a documentação diz que não existe, hoje, um comando de restauração. Depois de restaurar no Docker, rode o comando abaixo para regenerar os hooks:

/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks

Se você usa o Portainer para acompanhar os contêineres, o guia Portainer na VPS: como gerenciar o Docker pelo navegador mostra como.

Checklist do Gitea na VPS

  • Docker e Docker Compose instalados na VPS.
  • docker-compose.yml com a imagem docker.gitea.com/gitea:28.3.0 e o volume ./gitea:/data.
  • Senhas do banco trocadas, se usar MySQL, e iguais nos dois serviços.
  • docker compose ps mostrando o contêiner de pé.
  • Assistente concluído em http://IP-DO-SERVIDOR:3000.
  • DISABLE_REGISTRATION definido como true e conferido no painel.
  • SSH_PORT ajustado para as URLs de clone, se o SSH usar a 222.
  • Dump do Gitea feito antes de cada atualização.

Já escolheu o servidor para o seu projeto? VPS a partir de R$ 17,00/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver os planos de VPS

Perguntas frequentes

O que é o Gitea?

É um serviço de desenvolvimento de software completo e self-hosted, segundo a documentação oficial. Você instala no seu servidor e guarda ali os repositórios Git.

Em qual porta o Gitea roda no Docker?

No exemplo da documentação, a interface web usa a porta 3000 e o SSH do contêiner é publicado no servidor como 222.

Como fechar o cadastro de novos usuários no Gitea?

Defina DISABLE_REGISTRATION como true, no app.ini ou pela variável GITEA__service__DISABLE_REGISTRATION=true. Depois disso, só o administrador cria contas.

O Gitea tem comando para restaurar backup?

Não. A documentação diz que hoje não há comando de restauração. O dump traz os arquivos e o banco.

Como atualizar o Gitea no Docker?

Com os dados num volume, troque a tag da imagem se ela estiver fixada e rode docker compose pull e depois docker compose up -d.

Esta resposta lhe foi útil?

Artigos Relacionados