Há algum tempo publiquei um vídeo explicando o que é o InsForge, a alternativa open source ao Supabase que tem o seu próprio MCP, um gateway com todos os modelos de inteligência artificial e que nos permite criar aplicações completas com backend, autenticação e base de dados diretamente do IDE com um simples prompt. E bem, o vídeo foi bastante bem recebido. Mas nos comentários havia uma coisa que se repetia constantemente: que ensinasse como instalá-lo no vosso próprio servidor.
E faz todo o sentido. É open source, ou seja, é possível. E se o hospedar você mesmo, é gratuito. Sem pagar nenhuma subscrição mensal. É disso que trata este post: instalar o InsForge no teu próprio servidor, passo a passo, sem omitir nada. E quando digo sem omitir nada, incluo tudo o que ninguém explica bem nestes tutoriais: as variáveis de ambiente, o login com Google, o login com GitHub… tudo.
Antes de mais: onde o instalar?
Isto é bastante flexível. O InsForge é implementado com Docker, por isso podes instalá-lo onde quiseres: no teu computador, num VPS, num Raspberry Pi… a máquina não importa.
Dito isto, se o vais usar para aplicações reais que outras pessoas vão utilizar, o teu computador pessoal não é a melhor ideia. Pensa bem: o InsForge vai ser a tua base de dados e todo o backend da tua aplicação. Se desligares o computador, tudo cai. Por isso, para algo a sério, o ideal é um VPS.
Para este tutorial vou usar um da Hostinger, mas sinceramente usem o que quiserem. Se tiverem um servidor Oracle Cloud dos gratuitos, esses também funcionam perfeitamente. Expliquei noutro vídeo como conseguir um gratuitamente com 4 cores, 24GB de RAM e 200GB de disco. Se não o viram, está no canal. Atenção, a arquitetura desse servidor é ARM e pode dar problemas. Ficaram avisados!
O mínimo que precisas é uma máquina com 2GB de RAM. Com isso já chegará para começar.
🎁 Oferta exclusiva: Para acederes ao teu servidor na Hostinger, vai a hostinger.es/devknives e usa o código DEVKNIVES para obter um desconto de 10%.
Passo 1: Liga-te ao teu servidor e instala o Docker
Parto do princípio que já sabes conectar-te por SSH ao teu servidor. Se não, é tão simples como abrir o terminal e executar:
ssh utilizador@ip_do_teu_servidorUma vez dentro, a primeira coisa é instalar o Docker. Copia e cola este bloco de comandos e executa-os todos de uma vez:
sudo apt update && sudo apt upgrade -y
sudo apt install ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-pluginPara verificar que está corretamente instalado:
docker --versionSe devolver a versão, perfeito. Continuamos.
Passo 2: Clona o repositório do InsForge
O repositório do InsForge é público. Basta cloná-lo no teu servidor:
git clone https://github.com/InsForge/InsForge.git
cd insforgePasso 3: Configura as variáveis de ambiente
Aqui está a parte essencial. O repositório inclui um ficheiro de exemplo com todas as variáveis. O que tens de fazer é copiá-lo e começar a preenchê-lo:
cp .env.example .envAbre-o com o nano para editá-lo diretamente a partir do servidor:
nano .envOu se tens acesso com VS Code Remote SSH, abre-o assim pois é mais fácil de ler. Em qualquer caso, vamos percorrer cada variável porque sem isto a aplicação simplesmente não arranca.
Porta
PORT=7130Deixa como está. Antes de arrancar, certifica-te de que não tens nada a correr nessa porta. Num servidor novo não terás, mas por precaução podes verificar com sudo lsof -i :7130.
PostgreSQL
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=insforgePor favor muda isto. Por defeito vem com “postgres” e “postgres” que é a primeira coisa que tentariam num ataque. Gera algo aleatório. Podes usar este comando para gerar uma palavra-passe segura:
openssl rand -base64 32Copia o que devolver e usa-o como utilizador ou palavra-passe. Cada vez que executas o comando gera um diferente, por isso sem receio.
URLs base
API_BASE_URL=http://localhost:7130
VITE_API_BASE_URL=http://localhost:7130Deixa-as como estão por agora. Quando tiveres o teu domínio configurado, muda para o teu URL. (Por exemplo https://db.teudominio.com) Mas para a primeira instalação e teste, localhost está bem.
JWT Secret
JWT_SECRET=o-teu-hash-aquiEste é o segredo com que se cifram os tokens de autenticação. Tem de ser um hash longo e aleatório. Para gerá-lo:
openssl rand -base64 64Copia o resultado e cola-o aí. Quanto mais longo, mais difícil de quebrar.
Admin
ADMIN_EMAIL=tu@email.com
ADMIN_PASSWORD=palavra-passe-muito-seguraEste é o acesso ao painel de administração do InsForge. O email não precisa de existir de facto, mas usa um que te vás lembrar. E a palavra-passe: gera outro hash com o mesmo comando e usa-o como palavra-passe. Assim tenho a certeza que nunca se repetem e que são impossíveis de adivinhar.
Encryption Key
ENCRYPTION_KEY=outro-hash-diferenteTecnicamente poderia usar o mesmo valor que JWT_SECRET, mas o correto é ter uma chave diferente para cada coisa. Gera um novo com o mesmo comando e pronto.
Access API Key
ACCESS_API_KEY=ik_o-teu-hash-aquiMais um hash. Mas atenção a isto: tem de começar obrigatoriamente por ik_. Se não começar por ik_, não vai funcionar. Por isso geras o hash, copias, e no início colocas ik_:
# Assim o geras
openssl rand -base64 32
# E colas como: ik_HASH_GERADOCloud API Host
CLOUD_API_HOST=Deixa vazio. Isto é para a versão cloud do InsForge mas nós fazemos self-hosted, não precisamos.
Armazenamento com Cloudflare R2
Agora vem o armazenamento de ficheiros. Por defeito o ficheiro de exemplo está configurado para AWS S3, e podem usá-lo se quiserem. Mas pessoalmente prefiro o Cloudflare R2 porque tem uma camada gratuita muito generosa e já há algum tempo que o uso em vários projetos sem pagar nada.
A camada gratuita do R2 inclui 10GB de armazenamento, 1 milhão de operações de escrita e 10 milhões de operações de leitura por mês. Para a maioria dos projetos isso é mais do que suficiente sem gastar um cêntimo.
A boa notícia é que o R2 é compatível com a API S3, por isso mesmo que as variáveis se chamem S3_*, funcionam perfeitamente com o Cloudflare. Mesma API, fornecedor diferente, e gratuito.
Como criar o bucket e as credenciais passo a passo
1. Entra no teu painel do Cloudflare (dash.cloudflare.com) e no menu lateral procura R2 Object Storage. Se é a primeira vez pode pedir-te para ativar o serviço, basta clicar em ativar.
2. Cria um novo bucket. Clica em Create bucket, dá-lhe um nome (por exemplo insforge-storage) e seleciona a região mais próxima de ti. Na Europa o mais habitual é WEUR (Europa Ocidental). Clica em Create bucket e já está.
3. Obtém o endpoint URL. Uma vez criado o bucket, entra nele e no topo verás algo assim:
Endpoint: https://abc123def456.r2.cloudflarestorage.comEsse abc123def456 é o teu Account ID do Cloudflare. Copia-o, é o que vais colocar em S3_ENDPOINT_URL.
4. Gera as credenciais de API. Volta à página principal do R2 e no canto superior direito tens o botão Manage R2 API tokens. Clica aí e depois em Create API token.
- Dá-lhe um nome descritivo, por exemplo
insforge-token - Nas permissões seleciona Object Read & Write (leitura e escrita)
- Em Specify bucket seleciona o bucket que acabaste de criar
- Clica em Create API Token
Vai mostrar-te as credenciais apenas uma vez. Não feches esse ecrã sem as teres copiado.
Agora já tens tudo para preencher as três variáveis:
S3_ACCESS_KEY_ID=o-access-key-id-que-o-cloudflare-te-deu
S3_SECRET_ACCESS_KEY=o-secret-access-key-que-o-cloudflare-te-deu
S3_ENDPOINT_URL=https://O_TEU_ACCOUNT_ID.r2.cloudflarestorage.comImportante: O endpoint não leva o nome do bucket no final, apenas o Account ID. E saibam também que têm de deixar
AWS_S3_BUCKETcom o nome do bucket que criaram:
AWS_S3_BUCKET=insforge-storage
Logs
LOGS_DIR=Vazio. Por defeito o InsForge guarda os logs numa pasta ./logs e não é preciso tocar em nada.
OpenRouter
OPENROUTER_API_KEY=Isto é para o gateway de inteligência artificial unificado que o InsForge inclui. Se não tens planos de usá-lo, deixa vazio. Se queres usá-lo, vai a openrouter.ai, cria uma conta e gera uma API key. Com os modelos gratuitos não precisas de colocar dinheiro, e se queres os pagos é como em qualquer outra plataforma: carregas créditos e gastas.
PostHog (modo desenvolvimento)
VITE_PUBLIC_POSTHOG_KEY=Vazio. Isto só é necessário se executares o InsForge em modo desenvolvimento. Nós vamos fazer deploy em produção, por isso não nos afeta.
OAuth: login com redes sociais
E aqui chegamos à parte que toda a gente queria. O login com Google, GitHub, Microsoft, Discord, LinkedIn, X e Apple. Vou explicar como fazer cada um. O bom é que não tens de configurar todos, apenas os que te interessarem. Os que deixares vazios, simplesmente não aparecerão como opção de login.
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=Para o login com Google é preciso criar uma aplicação OAuth no Google Cloud Console. Parece intimidante mas é bastante guiado.
1. Vai ao Google Cloud Console e entra com a tua conta Google. Se é a primeira vez pode aparecer-te um ecrã de boas-vindas com um teste gratuito, pede cartão mas não cobra. Se conseguirem evitar, evitem, mas se não tiverem outra opção para entrar, sabem que não vos vai cobrar desde que não usem serviços pagos.
2. Cria um novo projeto. No canto superior esquerdo tens o seletor de projetos. Clica e depois em New Project. Dá-lhe um nome, por exemplo InsForge, e clica em Create.
3. Configura o ecrã de consentimento OAuth. No menu lateral procura APIs & Services > OAuth consent screen. Aqui é onde configuras como vai aparecer o ecrã de login para os teus utilizadores.
- Seleciona External (para que qualquer pessoa possa iniciar sessão, não apenas os da tua organização)
- Preenche o App name (por exemplo
InsForge), um email de suporte e o email do programador (pode ser o mesmo que o teu) - Em Authorized domains adiciona o teu domínio (por exemplo
teudominio.com, sem o https) - Clica em Save and continue até ao fim, o resto dos campos são opcionais
4. Cria as credenciais. Vai a APIs & Services > Credentials, clica em Create Credentials e seleciona OAuth 2.0 Client IDs.
- Em Application type seleciona Web application
- Dá-lhe um nome, por exemplo
InsForge Web - Em Authorized redirect URIs clica em Add URI e coloca exatamente isto com o teu domínio real:
https://teudominio.com/auth/callback/googleClica em Create.
Vai aparecer uma janela com o Client ID e o Client Secret. Copia-os e cola-os nas variáveis do .env.
Um aviso importante sobre o modo Testing: quando creates a app OAuth no Google, começa no modo Testing e só podes adicionar até 100 utilizadores de teste manualmente na secção Test users. Se queres que qualquer pessoa possa iniciar sessão sem restrições, tens de publicar a app indo a OAuth consent screen e clicando em Publish App.
O Google vai pedir-te que passes por um processo de verificação onde justificas para que usas o login. Para o InsForge basicamente explicas que é uma ferramenta de gestão de projetos própria. Não é complicado mas pode demorar alguns dias. Entretanto, com o modo Testing podes testá-lo adicionando o teu próprio email como utilizador de teste e funciona perfeitamente.
GitHub
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=Esta é a mais simples de todas e a que recomendo configurar de certeza porque em dois minutos está feita.
1. Entra no GitHub, vai à tua foto de perfil (canto superior direito) > Settings.
2. No menu lateral, desce até ao final e entra em Developer settings.
3. Dentro de Developer settings, entra em OAuth Apps e clica em New OAuth App.
4. Preenche o formulário:
- Application name: InsForge (ou o nome que quiseres)
- Homepage URL: o URL do teu InsForge, por exemplo
https://teudominio.com - Application description: opcional, podes deixar vazio
- Authorization callback URL: este é o importante, coloca exatamente isto:
https://teudominio.com/auth/callback/githubClica em Register application.
5. Uma vez criada a app, já vês o Client ID diretamente no ecrã. Para o Secret tens de clicar no botão Generate a client secret. Mostra-to apenas uma vez, por isso copia-o nesse momento, não o percas.
Copias os dois valores, colas-os nas variáveis do .env e pronto. Sem verificações, sem esperas, sem ninguém a rever nada. É imediato. Por isso é a que mais gosto de configurar.
Microsoft
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=Vai ao Azure Portal, a Azure Active Directory > App registrations, regista uma nova aplicação e de lá obtém o Client ID e cria um Client Secret. É um pouco mais complicado do que o GitHub porque o Azure é sempre assim, mas também não é difícil. O URL de redirecionamento seria:
https://teudominio.com/auth/callback/microsoftDiscord
DISCORD_CLIENT_ID=
DISCORD_CLIENT_SECRET=Vai ao portal de programadores do Discord, cria uma nova aplicação, entra em OAuth2 e aí tens as credenciais. Rápido e sem complicações. O callback URL:
https://teudominio.com/auth/callback/discordLINKEDIN_CLIENT_ID=
LINKEDIN_CLIENT_SECRET=Entra no portal de programadores do LinkedIn, cria uma app e dá-lhe permissões de Sign In with LinkedIn. As credenciais são dadas diretamente nas configurações da app.
X (Twitter)
X_CLIENT_ID=
X_CLIENT_SECRET=Vai ao Developer Portal do X, cria um projeto e uma app. Sempre pede que expliques para que queres a app, o que é um pouco chato, mas nada de mais. O callback URL:
https://teudominio.com/auth/callback/xApple
APPLE_CLIENT_ID=
APPLE_CLIENT_SECRET=Esta é a mais complicada de todas e digo-o com conhecimento de causa. Para usá-la precisas de uma Apple Developer Account, que por si só custa 99 dólares por ano. Depois tens de criar um Services ID, uma Key, e o APPLE_CLIENT_SECRET não é uma chave normal: tem de ser um JSON com o teamId, o keyId e a chave privada em formato PKCS#8.
Se não tens apps publicadas na App Store e não pensas tê-las, eu simplesmente não me daria ao trabalho. Deixa vazio.
Variáveis de Cloud e Deno
DEPLOYMENT_ID=
PROJECT_ID=
APP_KEY=
DENO_SUBHOSTING_TOKEN=
DENO_SUBHOSTING_ORG_ID=Todas vazias. As primeiras três são apenas para a versão cloud oficial do InsForge. As do Deno também não são necessárias porque o Docker já levanta a sua própria instância de Deno internamente.
E com isto… terminámos com as variáveis de ambiente. Sei que parece muito, mas a maioria fica vazia. O importante são as do PostgreSQL, o JWT Secret, o admin e o storage. Todo o resto é opcional consoante o que precisares.
Passo 4: Lançar o contentor
Agora sim. Com tudo configurado, vamos arrancar o InsForge. O detalhe importante aqui é que não vale um simples docker compose up. É preciso usar o ficheiro de produção especificamente:
docker compose -f docker-compose.prod.yml up -dIsto descarrega as imagens necessárias e levanta todos os serviços em segundo plano. A primeira vez pode demorar alguns minutos dependendo da tua ligação. Podes ver os logs em tempo real com:
docker compose -f docker-compose.prod.yml logs -fQuando vires que todos os serviços estão healthy, é que está tudo a funcionar.
Opção alternativa: fazer deploy com Coolify
Se tiveres o Coolify instalado no teu servidor, a instalação é ainda mais simples do que por terminal. O Coolify já vem com Traefik para gerir o HTTPS, por isso poupas a parte do domínio.
O que tens de fazer é criar um novo recurso no Coolify do tipo Git com URL pública, colocar o URL do repositório do InsForge e dizer-lhe que use o docker-compose.prod.yml como ficheiro de configuração.
Um detalhe importante: tens de converter para “file” todos os ficheiros do repositório na secção de ficheiros do Coolify, porque se não o InsForge não arranca. E depois é preciso copiar manualmente a pasta functions para o diretório da aplicação:
cp -r /caminho/para/o/repo/functions /data/coolify/applications/O_TEU_APP_ID/functionsAs variáveis de ambiente editam-se diretamente a partir do painel de variáveis do Coolify, exatamente as mesmas que vimos antes. Muito mais visual e confortável.
Passo 5: Atribuir um domínio
Aceder ao InsForge por IP e porta não é adequado para uso real. Vamos colocar-lhe um domínio.
Se usas Coolify, é muito simples. Na configuração da aplicação colocas o teu domínio ou subdomínio, e no teu gestor de DNS (por exemplo Cloudflare) crias um registo A apontando esse domínio para o IP do teu servidor. O Coolify trata do HTTPS automaticamente com o Traefik.
Se o instalaste por terminal, precisas de instalar o Caddy, que é um servidor web muito simples que gere o HTTPS automaticamente sem configuração extra:
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddyUma vez instalado, edita o Caddyfile:
sudo nano /etc/caddy/CaddyfileE coloca isto:
insforge.teudominio.com {
reverse_proxy localhost:7130
}Guarda, recarrega o Caddy:
sudo systemctl reload caddyE agora configura o DNS para que o teu domínio aponte para o servidor. Explico mesmo a seguir.
Como configurar o DNS para apontar para o servidor
Precisas saber duas coisas: o IP público do teu servidor e onde tens o DNS do teu domínio gerido (normalmente no mesmo sítio onde compraste o domínio, ou no Cloudflare se o tiveres apontado para lá).
Como saber o IP do teu servidor:
Se tens acesso por terminal ao teu servidor, executa:
curl ifconfig.meDevolve o IP público diretamente. Anota-o.
Se o compraste na Hostinger, DigitalOcean ou similar, o IP também está no painel de controlo do teu fornecedor junto à informação do teu VPS.
Configurar o registo DNS no Cloudflare:
Se geres o teu DNS no Cloudflare (que é o mais habitual e o que eu recomendo), entra em dash.cloudflare.com, seleciona o teu domínio e vai ao separador DNS > Records.
Clica em Add record e preenche assim:
| Campo | Valor |
|---|---|
| Type | A |
| Name | insforge (ou o subdomínio que quiseres) |
| IPv4 address | o IP do teu servidor |
| Proxy status | DNS only (nuvem cinzenta, não laranja) |
| TTL | Auto |
Importante: Se deixares em modo Proxied (nuvem laranja), o Cloudflare atua como intermediário e pode quebrar as ligações WebSocket que o InsForge usa para tempo real. Com cinzento vai diretamente ao teu servidor sem passar pelo Cloudflare.
Clica em Save. A propagação no Cloudflare é quase instantânea, normalmente em menos de um minuto já funciona.
Se tens o DNS noutro fornecedor (GoDaddy, Namecheap, o próprio Hostinger…) o processo é o mesmo: criar um registo do tipo A com o nome do subdomínio e o IP do teu servidor. A interface varia um pouco entre fornecedores mas é sempre a mesma coisa.
Uma vez propagado já podes recarregar o Caddy e aceder ao teu InsForge com o domínio:
Passo 6: Verificar que tudo funciona
Entra no teu domínio no navegador e deverás ver o ecrã de login do InsForge. Se algo falhar, a primeira coisa é rever os logs:
docker compose -f docker-compose.prod.yml logs appSe tudo estiver bem, acede com o email e palavra-passe de administrador que colocaste nas variáveis ADMIN_EMAIL e ADMIN_PASSWORD. E já estás dentro.
Ligar o MCP ao IDE
Uma vez dentro do dashboard, o InsForge dá-te diretamente o comando para adicionar o MCP ao teu IDE. Copia-o, cola-o na configuração do teu IDE (Cursor, Claude Desktop, VS Code com Copilot…) e já tens o agente ligado à tua própria instância.
Para testar que funciona, pergunta ao agente algo como: “o que podes fazer com o InsForge?” e deverá responder descrevendo as capacidades do MCP. Se vires que consegue aceder ao dashboard e responde com informação real, é que está tudo a funcionar.
A partir daí já podes criar tabelas, configurar autenticação, gerir funções serverless… tudo a partir do chat do teu IDE, com a tua própria instância do InsForge a correr no teu servidor. Sem pagar nada por mês.
E se preferir migrar do Supabase?
Se neste momento tens projetos no Supabase e queres passá-los para o InsForge, há formas de o fazer. Se quiserem que faça um tutorial específico de como migrar dados do Supabase para o InsForge, deixem nos comentários. Pessoalmente acho que o InsForge funciona consideravelmente melhor, especialmente na versão self-hosted, e não tive os problemas que o Supabase me dava.
Também, se quiserem uma comparação aprofundada entre os dois para vos ajudar a decidir, digam-me. Com todo o gosto.
Pronto, é tudo. Sei que parece longo assim escrito, mas o processo real é bastante rápido. O que leva tempo é a primeira vez que preenchem todas as variáveis de ambiente e percebem o que cada uma faz. A partir daí, a instalação em si é questão de minutos.
Se vos foi útil, dêem um like no vídeo que não custa nada e subscrevam se ainda não o fizeram. E qualquer dúvida que tenham, deixem nos comentários que tento responder a tudo.
O que você achou?
Deixe sua opinião, pergunta ou sugestão. Os comentários são sincronizados com GitHub Discussions .