Base de Conhecimento

Forgejo na VPS: repositórios Git da equipe

  • forgejo, git, docker, vps, repositórios
  • Usuários acharam útil: 0

Forgejo na LTS v15.0.11 com Docker Compose: o cadastro vem aberto e é desligado antes de divulgar; depois banco, ROOT_URL com HTTPS, SSH na porta 222, Actions e backup.

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

Arte da Eleven Host: janela de terminal com o título: Forgejo na VPS: repositórios Git da equipe

Capa da Redação Eleven Host para o guia: Forgejo na VPS: repositórios Git da equipe Arte: Eleven Host

Forgejo na VPS é uma forja Git de código aberto: repositórios, issues e pull requests num servidor seu, para a equipe guardar e revisar o código em um só lugar. Veja a versão, a instalação, o cadastro, o HTTPS, o SSH e o backup.

Atualizado em 15/11/2026. Para entender o que é uma VPS antes de instalar, veja O que é servidor VPS: guia simples para iniciantes.

O que é o Forgejo

O Forgejo reúne, numa só interface web, repositórios Git, controle de issues e pull requests. O nome vem de forĝejo, palavra do esperanto para forja. O projeto nasceu a partir do código do Gitea e aceita migração a partir dele.

A licença é a GPL v3 ou posterior desde a v9.0; até a v8.0, inclusive, era MIT. É software livre.

O cadastro de usuários do Forgejo vem aberto. Crie a conta de administrador na tela de instalação e desligue o cadastro (DISABLE_REGISTRATION) antes de divulgar o endereço da instância.

Qual versão usar em 15/11/2026

Em 15/11/2026, a versão estável mais nova é a v17.0.1, com suporte até 28/01/2027. A LTS é a v15.0.11, com suporte até 15/07/2027. Ambas saíram em 26/10/2026, e as estáveis seguem um calendário fixo, a cada trimestre.

A v17.0.0 tem um aviso oficial para não atualizar: segundo as notas dela, um problema em investigação impede push, merge e outras operações de código em alguns casos, e o projeto pede que quem ainda não atualizou espere. Já a v16 ficou sem suporte em 29/10/2026. Por isso o exemplo usa a LTS 15. Antes de instalar, confira a página de releases do Forgejo, porque esse retrato muda.

As versões de 26/10/2026 (15.0.11 e 17.0.1, além da 16.0.7) trazem correções de segurança, entre elas a de ações pull_request_review que podiam rodar como confiáveis a partir de commits arbitrários e a de tokens nuget que ignoravam os escopos. As notas não informam gravidade. O projeto publica as correções nas versões de manutenção, então recomendamos manter a instância atualizada.

Banco de dados: SQLite ou PostgreSQL

O SQLite é o padrão e não exige nenhuma configuração extra. A documentação de instalação comenta, em tom informal, que ele parece ser suficiente para pelo menos 10 usuários, o que não é uma medida de capacidade. Para mais carga, a própria documentação aponta MySQL/MariaDB ou PostgreSQL; o parâmetro DB_TYPE aceita mysql, postgres e sqlite3.

Para uma equipe pequena, o SQLite simplifica a instalação, e é o que o exemplo abaixo usa. Se escolher PostgreSQL, a página de instalação com Docker traz uma variante do compose com um serviço db; copie o trecho dela.

Quem ainda não tem servidor encontra as VPS por plano na loja. VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver as VPS

Instalação com Docker Compose

Há dois caminhos oficiais, o binário com serviço do systemd e o Docker. O exemplo segue o Docker Compose, numa VPS com Docker e o plugin Compose já instalados. Primeiro, uma pasta para os dados. O volume precisa pertencer ao UID e GID 1000 configurados no compose; senão, o contêiner pode não subir. Um exemplo, não testado, que você deve conferir no próprio servidor:

mkdir -p ~/forgejo/forgejo

cd ~/forgejo

sudo chown 1000:1000 forgejo

Em seguida, crie o arquivo docker-compose.yml nessa pasta. Um exemplo, baseado no compose básico da documentação oficial de instalação com Docker e com a tag trocada pela da LTS. A indentação do YAML usa dois espaços por nível, como na documentação. A tag 18, que aparece na documentação em desenvolvimento, é versão em construção e não deve ser copiada.

networks:

forgejo:

external: false

services:

server:

image: codeberg.org/forgejo/forgejo:15

container_name: forgejo

environment:

- USER_UID=1000

- USER_GID=1000

restart: always

networks:

- forgejo

volumes:

- ./forgejo:/data

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

ports:

- '3000:3000'

- '222:22'

A porta 3000 é a da interface web, e a 222 do servidor leva ao SSH do contêiner, que escuta na 22. Para subir, um exemplo de comando, também não testado:

docker compose up -d

Só depois que o proxy reverso das seções abaixo estiver funcionando, vale publicar a porta web só no próprio servidor (até lá, o primeiro acesso da próxima seção usa a porta 3000), trocando '3000:3000' por '127.0.0.1:3000:3000'. Essa troca é uma sugestão, não testada. A documentação tem ainda uma variante rootless, com SSH na porta interna 2222.

O Forgejo lê configuração por variáveis no formato FORGEJO__SEÇÃO__CHAVE e cria o app.ini sozinho se ele não existir. Para acompanhar o servidor depois, veja Netdata na VPS: monitore o servidor em tempo real.

Primeiro acesso e tela de instalação

Abra a porta 3000 no navegador, pelo IP do servidor (por exemplo, http://203.0.113.10:3000/) ou, se estiver na própria máquina, http://localhost:3000/. Deve aparecer a tela de configuração inicial. A documentação diz que pode fazer sentido criar a conta de administrador já ali; se você pular essa etapa, cai na tela de login e cadastro. Por isso, crie a conta de administrador na própria tela de instalação.

A chave ROOT_URL substitui a URL pública gerada automaticamente. Como o proxy com HTTPS só entra nas seções abaixo, informe por ora o endereço pelo qual você está acessando, como http://203.0.113.10:3000/, e troque para o endereço com https://, por exemplo https://git.exemplo.com.br/, quando o proxy estiver no ar.

Até desligar o cadastro, a instância é aberta

Enquanto o cadastro estiver ligado, quem alcançar a página pode criar uma conta. Termine a instalação e desligue o cadastro antes de colocar o domínio no ar ou de passar o endereço à equipe.

Desligar o cadastro de usuários

A chave DISABLE_REGISTRATION, na seção [service], vem como false. Com true, só o administrador cria contas. Como o caminho do app.ini dentro do contêiner não é o foco aqui, o exemplo usa a variável de ambiente, que entra no bloco environment do compose depois de criar o administrador:

- FORGEJO__service__DISABLE_REGISTRATION=true

Essa linha é um exemplo, não testado. Aplique com docker compose up -d, que recria o contêiner, e abra a página de cadastro para ver se o cadastro de fato sumiu. Em instalação por binário, a mesma chave vai no /etc/forgejo/app.ini.

Outras duas chaves merecem atenção. REQUIRE_SIGNIN_VIEW vem como false; com true, toda página e a API passam a exigir login. Já INSTALL_LOCK em true deixa a página de instalação inacessível.

Domínio e HTTPS com proxy reverso

O Forgejo consegue servir HTTPS sozinho, mas, segundo a documentação, com um proxy reverso geralmente é mais fácil deixar o proxy cuidar do HTTPS. O domínio precisa apontar para o IP da VPS antes.

Com o Nginx, a página de proxy reverso mostra linhas como proxy_pass http://127.0.0.1:3000;, client_max_body_size 512M; e merge_slashes off, esta última necessária para tratar barras codificadas na URL. O bloco também repassa cabeçalhos como Host e X-Forwarded-Proto, e o HTTPS vem do Certbot ou de configuração manual. Copie o bloco completo da documentação.

Com o Caddy, o bloco do domínio aponta para a porta local, e o Caddy obtém os certificados do domínio automaticamente, de acordo com a documentação. Um exemplo, não testado, com o domínio de exemplo trocado pelo seu:

git.exemplo.com.br {

reverse_proxy 127.0.0.1:3000

}

Depois do proxy, ajuste o ROOT_URL para o endereço com https, por exemplo pela variável FORGEJO__server__ROOT_URL, e recrie o contêiner. A documentação cita a mudança do ROOT_URL para o protocolo HTTPS justamente para isso.

SSH para clonar e enviar código

No compose acima, o SSH do contêiner fica na porta 22 dele e é publicado na 222 do servidor. A chave SSH_PORT, por padrão 22, define a porta mostrada nas URLs de clone, então, com este compose, o valor deve ser 222. Um exemplo, não testado:

- FORGEJO__server__SSH_PORT=222

Para testar, cadastre antes a sua chave pública SSH nas configurações da conta no Forgejo. A documentação traz um comando de conexão, aqui com o domínio de exemplo; confira o que o seu servidor responde:

ssh -F /dev/null git@git.exemplo.com.br -p 222

No modo rootless, a porta interna é a 2222, e o compose publica 222:2222.

Actions e runner

O Forgejo Actions oferece integração contínua a partir de arquivos do repositório, e o runner é instalado e configurado à parte, fora do Forgejo. A documentação alerta que o runner executa código e representa riscos importantes de segurança para o servidor e a rede onde roda, então mantenha-o isolado ou em outra máquina.

Backup e atualização

O comando forgejo dump compacta, num arquivo zip, os arquivos e o banco: repositórios, banco de dados, pasta custom, LFS, anexos e pacotes. As opções incluem --file para o nome do arquivo e --type para o formato. A página de comandos descreve a restauração só de repositório, com restore-repo; por isso recomendamos ensaiar a restauração completa num servidor de teste antes de depender da cópia.

No Docker, um exemplo seria rodar o comando dentro do contêiner, mas o usuário e o caminho de saída precisam ser conferidos, e este exemplo não foi testado:

docker exec -u git forgejo forgejo dump

Recomendamos guardar a cópia fora da VPS. Para automatizar a cópia, veja Restic na VPS: backup automático do servidor.

Na atualização, a documentação recomenda fortemente um backup completo antes e a leitura atenta da seção de mudanças incompatíveis das notas de versão. Atualizar é trocar o binário ou a imagem; depois, rode forgejo doctor check --all --log-file /tmp/doctor.log e teste no navegador. Não existe volta: uma versão mais antiga se recusa a iniciar para não danificar o banco.

Um endereço próprio para a instância

O endereço do Forgejo é um domínio ou subdomínio que aponta para o servidor e aparece nas URLs de clone.

Primeiro passo do endereço próprio: a busca de domínio, com centenas de extensões. Buscar domínio

Perguntas frequentes

O Forgejo é gratuito?

É software livre, sob a GPL v3 ou posterior desde a v9.0. Para rodá-lo, é preciso um servidor, que tem custo.

Qual versão do Forgejo instalar?

O exemplo usa a LTS v15.0.11, com suporte até 15/07/2027. A estável v17.0.1 tem suporte até 28/01/2027, e a v17.0.0 tem aviso oficial para não atualizar. Confira a página de releases antes de instalar.

Preciso desligar o cadastro?

Recomendamos que sim, antes de divulgar o endereço. O cadastro vem aberto, e DISABLE_REGISTRATION=true deixa só o administrador criar contas.

Esta resposta lhe foi útil?

Artigos Relacionados