Blogue

Coolify e Claude Code: implemente um projeto no seu próprio VPS

Markdown

Instalação do Coolify, ligação ao GitHub, implementação de Next.js, domínio e HTTPS, MCP, requisitos de VPS e resolução de problemas. Preços técnicos denominados em dólares e limitações originais.

Ler o artigo completo

Documentação Ailoot — materiais de referência para trabalhar com o serviço.

Limitações da plataforma e condições de pagamento em 2026

Principal conclusão

Os planos gratuitos funcionam até ultrapassar um limite pela primeira vez; depois disso, é necessário um cartão internacional. A Heroku encerrou o seu plano gratuito para todos em 2022 e entrou em modo de manutenção em fevereiro de 2026. Com o Coolify alojado por si, o servidor é seu; não existe faturação por utilizador nem dependência do fornecedor.

Um cenário típico de vibe coder em 2026: cria um MVP no Cursor ou Claude Code numa noite, passa-o para um repositório GitHub, abre vercel.com → liga o repositório → chega ao ecrã de subscrição → introduz o cartão → recebe Transaction declined.

Isto não é um erro nem uma interrupção temporária.

Railway, Render, Heroku — a história é a mesma. A Heroku encerrou mesmo o seu plano gratuito para todos em 2022 e, em fevereiro de 2026, o projeto entrou em modo de manutenção — sem novas funcionalidades nem novos contratos Enterprise. Para um utilizador com um cartão não suportado, isto significa: «a porta está fechada; contorne-a através de um intermediário que cobra uma comissão de 20%».

Pode pagar através de cartões Visa virtuais no Cazaquistão ou de serviços de pagamento empresariais. Mas isso significa +20% ao preço, +30 minutos em cada transação e o risco de a sua conta ser bloqueada quando o processador de pagamentos detetar uma incompatibilidade entre países.

O exemplo original incluía três tentativas — na Vercel Pro, na Railway e na Render.

O que é o Coolify e como funciona uma plataforma alojada por si?

Principal conclusão

O Coolify é uma PaaS de código aberto que pode alojar por si e uma alternativa direta à Heroku, Vercel e Netlify. Instala-se com um único comando curl em qualquer VPS com Ubuntu. Nos bastidores, utiliza Docker + Traefik para encaminhamento por proxy inverso e Let's Encrypt para HTTPS. Suporta integração com o GitHub, webhooks para implementações automáticas, cópias de segurança S3 e mais de 280 serviços instaláveis com um clique (PostgreSQL, Redis, MinIO). A versão alojada por si é gratuita para sempre e sem limites. Tem 55 800 estrelas no GitHub e uma licença Apache-2.0.

O Coolify é um projeto de código aberto criado com Laravel + Docker que transforma qualquer VPS vazio numa plataforma de implementação de aplicações. Instale o Coolify uma vez e, depois, faça tudo o resto através da interface Web: ligue o GitHub, escolha um repositório e clique em Deploy.

A documentação oficial resume-o de forma breve e precisa:

O Coolify é uma alternativa de código aberto à Heroku / Netlify / Vercel, etc., que pode alojar por si.

— README do GitHub do Coolify, https://github.com/coollabsio/coolify

Nos bastidores, o Coolify é composto por quatro partes:

  1. Interface Web criada com Laravel 12 + Livewire 3 + Tailwind v4 — um painel para gerir as suas aplicações.
  2. Docker + Docker Compose — cada aplicação é executada num contentor, isolada das restantes.
  3. Proxy inverso (Traefik ou Caddy) — recebe tráfego HTTP/HTTPS e encaminha-o para os contentores.
  4. Integração com Let's Encrypt — emite e renova automaticamente certificados SSL para todos os domínios.

Funcionalidades principais que tornam o Coolify funcionalmente comparável à Vercel:

FuncionalidadeVercelCoolify
Implementação automática ao fazer git push✅✅ (através de webhook do GitHub)
HTTPS gratuito✅✅ (Let's Encrypt)
Implementações de pré-visualização de PR✅✅ (através da GitHub App)
Interface para variáveis de ambiente✅✅
Cópias de segurança de bases de dados❌ (não inclui bases de dados próprias)✅ (para armazenamento compatível com S3)
PostgreSQL / Redis / MongoDB$20+/mês cada✅ Instalação com um clique, gratuita
Tarefas agendadas (cron)❌✅ (sintaxe cron)
Faturação por utilizador$20/utilizador/mêsNenhuma
Dependência do fornecedorElevada (Edge Functions, ISR)Zero (o seu Docker)
CDN global✅❌ (apenas o seu VPS)

Uma CDN global é a única coisa que o Coolify não inclui de origem. Essa é a resposta honesta. Se o seu projeto tiver um público global e precisar de reduzir a latência para utilizadores nos EUA e na Europa, coloque a Cloudflare à frente; é gratuita para conteúdo estático.

Preço: a versão alojada por si é gratuita para sempre, sem limites quanto ao número de aplicações, servidores ou implementações. O Coolify Cloud está disponível por $5/mês para 2 servidores + $3 por cada servidor adicional — mas os próprios servidores continuam a ser seus; o Coolify Cloud limita-se a alojar o painel.

A versão mais recente é a v4.1.0, de 18 de maio de 2026. As novas funcionalidades incluem o build pack Railpack em beta, registos de auditoria, diferenças de configuração entre implementações e um endpoint MCP nativo (só de leitura). Fonte: versões no GitHub.

Que VPS deve escolher para o Coolify em 2026?

Principal conclusão

O Coolify requer, no mínimo, 2 vCPU, 2 GB de RAM, 30 GB SSD e Ubuntu LTS (20.04, 22.04 ou 24.04). Um VPS com estas características consegue executar confortavelmente 3–5 projetos criados com vibe coding em simultâneo.

Os requisitos mínimos do Coolify vêm diretamente da documentação oficial:

ParâmetroMínimoRecomendado
CPU2 núcleos2–4 núcleos
RAM2 GB4 GB (com margem para compilações)
Armazenamento30 GB50–80 GB (para imagens + bases de dados)
ArquiteturaAMD64 ou ARM64 (64 bits)AMD64
SOUbuntu LTS 20.04 / 22.04 / 24.0422.04 LTS
RootObrigatórioAtravés de chave SSH, não de palavra-passe

O mínimo — 2 GB de RAM — é um limite inferior rígido. Com 1 GB, o instalador chega ao Docker, fica sem memória (OOM) e bloqueia. Não poupe na RAM.

Fontes de preços: Timeweb Cloud, FirstVDS e Selectel.

Se precisar de mais potência (uma base de dados de 100 GB, várias instâncias Postgres), escolha Aeza Dedicated.

O que NÃO deve escolher:

  • VPS partilhado com 512 MB–1 GB de RAM — não chega nem para o Coolify. É indicado para sites estáticos em nginx, não para uma PaaS.

Quer não só configurar a implementação, mas também criar uma configuração que torne o Claude fiável? O Coolify é uma ferramenta de execução, mas sem contexto estruturado (CLAUDE.md, um segundo cérebro e engenharia de contexto), o Claude continuará a alucinar em tarefas longas. A configuração completa inclui os três elementos: clone de IA + segundo cérebro + engenharia de contexto — esta combinação transforma o Claude de «um assistente que alucina» numa ferramenta fiável.

Como instalar o Coolify em 5 minutos

Principal conclusão

A instalação é feita com um único comando curl da documentação. Quando arranca, aparece uma interface Web na porta 8000. Aí, cria o primeiro utilizador administrador e vê um painel vazio. O tempo real entre uma instalação Ubuntu vazia e o Coolify em funcionamento é de 5–7 minutos, dos quais 3–4 minutos são gastos em apt-get install docker. O script obtém as dependências necessárias e configura o Docker; só precisa de esperar que termine.

Passo 1. Ligue-se ao VPS por SSH.

Depois de criar um VPS junto do fornecedor, o endereço IP do servidor e a palavra-passe root aparecerão num e-mail ou no painel de controlo. Ligue-se a partir do seu computador local:

ssh root@1.2.3.4

Se o fornecedor lhe tiver dado uma chave SSH em vez de uma palavra-passe, ligue-se com -i path/to/key. A partir daqui, parto do princípio de que está perante uma instalação limpa do Ubuntu 22.04 ou 24.04 LTS.

Passo 2. Execute o comando de instalação do Coolify.

Um comando da documentação oficial:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash

O script faz três coisas:

  1. Verifica o sistema (Ubuntu LTS? root? AMD64?)
  2. Instala o Docker e o Docker Compose, se ainda não estiverem instalados
  3. Transfere as imagens do Coolify (coolify/coolify, coolify/realtime, traefik) e executa-as em segundo plano através de docker-compose

Isto demora 3–5 minutos. Verá os registos de apt-get a passar, seguidos de docker pull. Quando aparecer Coolify v4.1.0 is now running, avance para o passo 3.

Passo 3. Abra a interface Web.

Abra isto no seu browser:

http://1.2.3.4:8000

O Coolify apresentará um assistente de configuração — um formulário para criar o primeiro utilizador. Introduza um e-mail e uma palavra-passe e guarde-os. Este utilizador torna-se automaticamente administrador; ainda não precisa de outros utilizadores.

Depois de guardar, chegará a um painel vazio: uma barra lateral à esquerda com Resources / Projects / Servers / Sources / Notifications / Settings e, ao centro, uma mensagem para «Add your first resource».

Passo 4. Abra portas na firewall do fornecedor (não no UFW).

O Coolify já está em execução, mas, do exterior, só a porta 8000 (o painel) está acessível. Para permitir que os utilizadores acedam às suas aplicações, tem de abrir as portas 80 (HTTP) e 443 (HTTPS):

PortaFinalidade
22Acesso SSH ao servidor
80Recebe tráfego HTTP, necessário para a validação do Let's Encrypt
443Recebe tráfego HTTPS dos utilizadores
8000Painel do Coolify (vamos fechar esta porta depois de configurar um domínio personalizado para o painel)

Uma armadilha importante indicada na documentação oficial:

O Docker utiliza regras iptables baseadas em NAT que podem contornar firewalls Linux tradicionais, como o UFW.

— Documentação do Coolify (firewall), https://coolify.io/docs/knowledge-base/server/firewall

Isto significa que, mesmo que ative o UFW e feche todas as portas, o Docker continuará a expor os seus contentores através do iptables. O UFW não serve de nada neste caso. A solução é abrir e fechar portas no painel de controlo do fornecedor, não através do UFW. Na Timeweb / Selectel / Aeza, faz-se isto na secção «Network → Firewall» da consola Web.

Passo 5 (opcional). Associe o painel ao seu domínio.

Para visitar https://coolify.example.com em vez de http://1.2.3.4:8000, crie um registo DNS A coolify.example.com → 1.2.3.4, aceda a Settings → Instance Settings → Instance Domain no Coolify, introduza o seu subdomínio e guarde. O Coolify solicitará um certificado Let's Encrypt e, um minuto depois, recarregará o painel através de HTTPS.

Depois disso, pode fechar a porta 8000 na firewall — o painel ficará disponível por HTTPS na porta padrão 443.

Como ligar o GitHub: App ou PAT?

Principal conclusão

O Coolify suporta duas formas de ligar ao GitHub: GitHub App (recomendada) e Personal Access Token (PAT). Use a GitHub App: a configuração demora 5 minutos com o assistente, as pré-visualizações de PR funcionam e as permissões podem ser limitadas com precisão ao nível do repositório. PAT é uma opção desatualizada para casos antigos; não permite implementações de pré-visualização e implica o risco de acesso global a todos os seus repositórios. A documentação oficial afirma diretamente: «para 95% dos utilizadores, a GitHub App é a escolha certa».

No Coolify, aceda a Sources → + Add → GitHub App. O Coolify apresentará um assistente com três ecrãs:

  1. Name & description — dê um nome à origem (introduza github-main) e, opcionalmente, adicione uma descrição.
  2. Configure on GitHub — um botão que o leva ao GitHub.com e abre automaticamente um formulário de criação de GitHub App com as permissões corretas.
  3. Confirm — depois de regressar do GitHub, clique em «Save».

No segundo passo, o GitHub pedir-lhe-á que confirme as permissões solicitadas pelo Coolify:

PermissãoNívelFinalidade
ContentsSó de leituraClonar o repositório
Pull RequestsLeitura e escritaCriar implementações de pré-visualização e comentar PRs
Email addressesSó de leituraIdentificar commits
MetadataSó de leituraListar repositórios

Estas são permissões mínimas — a GitHub App não consegue ver as suas chaves privadas, não consegue escrever em main e não pode aceder a repositórios que não tenha ligado explicitamente.

Da documentação oficial:

Personal Access Token (PAT) é o método antigo; recomendo que não o utilize. Desvantagens:

  • PAT concede acesso global a todos os seus repositórios (incluindo os privados)
  • As pré-visualizações de PR não funcionam — essa funcionalidade é exclusiva da GitHub App
  • O token dura muito tempo (90 dias, um ano ou indefinidamente) — se for exposto, é um problema

Utilize PAT apenas se trabalhar com um repositório de uma organização cuja política de segurança proíba GitHub Apps e não houver forma de contornar essa restrição.

Depois de guardar a origem no Coolify, verá a GitHub App no painel, com uma lista dos repositórios ligados. Quando criar uma nova aplicação, poderá selecionar qualquer um deles com um clique.

Como implementar um projeto Next.js do Claude Code em 6 passos

Principal conclusão

O percurso completo, desde uma configuração vazia do Claude Code até um site em funcionamento: 1) execute claude numa pasta vazia, descreva o projeto e o Claude gera o código; 2) execute git init && git remote add (o Claude pode fazê-lo por si através de um comando slash); 3) envie as alterações para o GitHub; 4) no Coolify, escolha «+ New Resource → Application» e selecione o repositório; 5) adicione variáveis de ambiente; 6) clique em Deploy. O Coolify detetará que é Next.js, escolherá o build pack Nixpacks, criará uma imagem Docker em 3–5 minutos e fornecerá um domínio temporário no formato YOUR_TEMPORARY_DOMAIN com HTTPS incluído de origem.

Passo 1. Descreva o projeto ao Claude Code numa pasta vazia.

mkdir my-vibe-app
cd my-vibe-app
git init
claude

Na sessão:

Cria um projeto Next.js 14 app router:
- uma página inicial com uma lista de utilizadores
- o endpoint /api/users devolve um array da base de dados
- Postgres através de Prisma
- Tailwind para os estilos
- .env.example com DATABASE_URL
- README.md com instruções para executar o projeto

O Claude irá gerar a estrutura de ficheiros, package.json, prisma/schema.prisma e .env.example. Peça também:

Cria um Dockerfile para compilações de produção e um .dockerignore.

Isto é opcional — o Coolify compila com Nixpacks mesmo sem um Dockerfile. Mas um Dockerfile dá-lhe controlo sobre o processo e é mais rápido para projetos maiores.

Passo 2. Crie um repositório GitHub e envie-lhe o projeto.

Pode fazê-lo manualmente através da interface do GitHub + git remote add origin ..., mas o Claude Code pode fazê-lo por si:

/commit-push-pr Initial Next.js app generated with Claude Code

Ou diga simplesmente: «Commit everything and push it to a new repository my-vibe-app under my account.» O Claude utilizará o CLI gh para criar um repositório privado (ou público) e fazer o primeiro push. Fonte: comando oficial do Claude Code.

Passo 3. Crie uma aplicação no Coolify.

No painel do Coolify, clique em + New → Application. Abrir-se-á um formulário:

  1. Source — selecione github-main (a GitHub App que ligou na secção H2 anterior)
  2. Repository — selecione my-vibe-app na lista
  3. Branch — main
  4. Build Pack — o Coolify detetá-lo-á automaticamente. Se existir um Dockerfile, usará dockerfile. Caso contrário, usará nixpacks. Pode substituir esta opção manualmente.
  5. Domain — deixe o valor sugerido (YOUR_TEMPORARY_DOMAIN) por agora; é temporário e irá substituí-lo pelo seu mais tarde
  6. Port — 3000 por predefinição para Next.js

Guarde.

Passo 4. Adicione variáveis de ambiente.

Na aplicação criada, abra o separador Environment Variables. Adicione as variáveis uma a uma:

DATABASE_URL=postgresql://user:pass@db-host:5432/mydb
NODE_ENV=production
ANTHROPIC_API_KEY=sk-ant-...

Se não tiver uma base de dados, crie uma diretamente no Coolify: + New → Database → PostgreSQL. O Coolify iniciará um contentor Postgres em 30 segundos e fornecerá uma DATABASE_URL interna no formato postgresql://postgres:pass@postgres-xyz:5432/postgres — introduza-a na aplicação.

Todas as variáveis são encriptadas na base de dados do Coolify e não são apresentadas nos registos de compilação.

Passo 5. Clique em Deploy.

No canto superior direito, há um botão azul Deploy. Os registos em tempo real aparecerão no separador Logs:

[stage: clone]   Cloning '<repository-url-from-github>'
[stage: build]   Detected Next.js, using Nixpacks
[stage: build]   Installing Node 20, npm 10
[stage: build]   npm install (245s)
[stage: build]   npm run build (87s)
[stage: deploy]  Creating container my-vibe-app-xyz
[stage: deploy]  Container started, health check passed
[stage: proxy]   Traefik routing configured for YOUR_TEMPORARY_DOMAIN
[stage: ssl]     Let's Encrypt cert issued for YOUR_TEMPORARY_DOMAIN

A primeira compilação demora 3–5 minutos (transfere a imagem base do Node e instala as dependências). As compilações seguintes demoram 60–90 segundos graças à cache de camadas do Docker.

Quando o estado mudar para Running, copie o URL da aplicação no campo Domains do Coolify e abra esse endereço exato no navegador. Use-o como <app-url-from-coolify> abaixo; o texto entre sinais de maior e menor é um marcador, não um endereço real.

Passo 6. Verifique se tudo funciona.

Abra o URL da aplicação do passo anterior com /api/users acrescentado, por exemplo <app-url-from-coolify>/api/users, sem duplicar a barra. É o endpoint JSON criado no passo 1; o URL raiz é a página inicial. Se ocorrer um erro 500, verá o stack trace no separador Logs. O problema mais comum numa primeira implementação é a DATABASE_URL apontar para uma base de dados inexistente. Resolva-o criando uma instância PostgreSQL no Coolify (consulte o passo 4 acima) e substituindo a DATABASE_URL.

15 minutos, a contar do momento em que encomenda o VPS. No exemplo original, este fluxo demorou 12–18 minutos num servidor acabado de instalar.

Como configurar um domínio personalizado e HTTPS

Principal conclusão

Um domínio personalizado liga-se em 3 passos: crie um registo DNS A que aponte para o IP do servidor, introduza o seu domínio na configuração do Coolify em vez do domínio temporário, ative Automatic HTTPS e clique em Redeploy. O Let's Encrypt emitirá automaticamente um certificado SSL 2–3 minutos após a propagação do DNS (normalmente 5–30 minutos). O requisito principal é que o DNS já resolva quando clicar em Redeploy; caso contrário, a validação do Let's Encrypt falhará e terá de esperar 12 minutos antes de tentar novamente.

Passo 1. Crie um registo DNS A no painel de controlo do seu registador.

Os exemplos originais utilizam domínios alojados na Reg.ru, Beget ou Timeweb. O processo é o mesmo:

Tipo de registoNomeValor
Aapp (ou @ para a raiz)1.2.3.4 (IP do servidor)

Guarde-o, abra uma consola e verifique:

dig app.example.com +short
# Deveria devolver 1.2.3.4

Se não devolver nada ou devolver um IP diferente, o DNS ainda não se propagou. Aguarde 5–30 minutos.

Passo 2. Introduza o seu domínio no Coolify.

Na aplicação, abra o separador Configuration → General. No campo Domains, substitua o URL temporário da aplicação copiado do Coolify por https://app.example.com (usando o seu domínio configurado). Ative Automatic HTTPS (normalmente já está ativo por predefinição).

Guarde e clique em Redeploy.

Passo 3. Aguarde pelo certificado Let's Encrypt.

Os registos de compilação mostrarão:

[stage: ssl]  Requesting Let's Encrypt cert for app.example.com
[stage: ssl]  HTTP challenge sent to /.well-known/acme-challenge/xxx
[stage: ssl]  Validation passed, cert issued
[stage: ssl]  Cert installed, HTTPS enabled

Em 2–3 minutos, o seu site estará disponível em https://app.example.com com um cadeado verde na barra de endereço.

O que pode correr mal com o Let's Encrypt (os 3 problemas mais comuns indicados no guia oficial de resolução de problemas):

  1. A porta 80 está fechada na firewall. O Let's Encrypt valida através de um HTTP challenge — envia um pedido para http://app.example.com/.well-known/acme-challenge/xxx. Sem a porta 80, a validação não será aprovada. Abra-a na firewall do fornecedor.
  2. O proxy da Cloudflare está ativado (nuvem laranja). Interceta o pedido do Let's Encrypt e devolve a sua própria página de marcador — a validação falha. A solução é mudar para «DNS only» (nuvem cinzenta) ou configurar um challenge DNS-01 através da API da Cloudflare.
  3. O DNS ainda não se propagou. Se criou um registo A há 30 segundos e clicou imediatamente em Redeploy, o Let's Encrypt não encontrará o seu domínio. Aguarde 5–30 minutos para que o DNS se propague pelos servidores.

Limite de frequência do Let's Encrypt: 5 tentativas falhadas por hora para um domínio, com recuperação à taxa de 1 a cada 12 minutos. Se atingir o limite, não clique em Redeploy 10 vezes seguidas; verifique os registos, resolva o problema e tente novamente dentro de 12 minutos.

Como usar um agente de inteligência artificial no Claude Code para gerir o Coolify?

Principal conclusão

Através do Model Context Protocol, o Claude Code obtém acesso direto à API do Coolify — pode dizer «implemente esta aplicação» para iniciar uma compilação, verificar o estado, ler registos ou atualizar variáveis de ambiente. Há três opções: forsonny/Coolify-MCP-Server (básica, 7 categorias de operações), dazeb/coolify-mcp-enhanced (mais de 15 ferramentas adicionais, incluindo implementação de bases de dados com um clique) e ajmcclary/Coolify-Manager (uma Claude Skill criada em torno do CLI oficial). A partir da v4.1.0 (18 de maio de 2026), o Coolify disponibiliza um endpoint MCP nativo sem servidores de terceiros — mas, por enquanto, é só de leitura.

O Model Context Protocol (MCP) é uma norma da Anthropic que permite ao Claude Code comunicar com sistemas externos (consulte o guia sobre servidores MCP para saber mais). Ligue um servidor MCP e o Claude recebe um conjunto de ferramentas que pode invocar. Existem três servidores prontos a usar para o Coolify, além de uma opção nativa.

Opção 1. forsonny/Coolify-MCP-Server-for-Claude-Code — básica.

O que pode fazer:

  • Aplicações: criar, iniciar, parar, reiniciar
  • Serviços: listar, criar, iniciar/parar/reiniciar
  • Implementações: ver as em execução, obter por UUID
  • Equipas e membros: listar, obter informações
  • Chaves SSH: listar, criar
  • Variáveis de ambiente: CRUD completo para aplicações e serviços
  • Informações do servidor: domínios por servidor, estado de saúde, versão

Instalação:

git clone '<OFFICIAL_URL>'
cd Coolify-MCP-Server-for-Claude-Code
npm install
npm run build
# Em .env:
#   COOLIFY_BASE_URL=https://coolify.example.com
#   COOLIFY_API_TOKEN=[do Coolify Settings → API Tokens]
npm run setup  # configura automaticamente o Claude Code

Depois, pode escrever isto no Claude Code:

Mostra o estado da aplicação my-vibe-app no Coolify e as 3 implementações mais recentes.

O Claude devolverá uma tabela.

Opção 2. dazeb/coolify-mcp-enhanced — melhorada (recomendada).

O que acrescenta ao conjunto básico:

  • Implementação de PostgreSQL / Redis / MinIO com um clique através de IA — peça «configura o Postgres por mim» e cria um contentor e devolve a DATABASE_URL
  • Monitorização em tempo real + utilização de recursos — CPU/RAM de cada aplicação em tempo real
  • Atualizações em lote da configuração env — atualize 20 variáveis com um comando
  • Suporte para Docker Compose — implementar aplicações com vários serviços

Configuração para Claude Code (.mcp.json na raiz do projeto):

{
  "mcpServers": {
    "coolify-enhanced": {
      "command": "node",
      "args": ["/path/to/coolify-mcp-enhanced/dist/index.js"],
      "env": {
        "COOLIFY_ACCESS_TOKEN": "your-token-here",
        "COOLIFY_BASE_URL": "https://coolify.example.com"
      }
    }
  }
}

Opção 3. ajmcclary/Coolify-Manager — uma Claude Skill criada em torno do CLI.

Não é um servidor MCP, mas sim uma Claude Code Skill que envolve o CLI oficial do Coolify. Inclui:

  • Diagnóstico de estado de serviços e contentores
  • Diagnóstico de certificados SSL
  • Suporte para várias instâncias (se tiver vários servidores Coolify)
  • Receitas para resolução de problemas

Instalação: transfira a skill e coloque-a em ~/.claude/skills/coolify-manager/. O Claude Code irá detetá-la e sugeri-la para tarefas relevantes.

Opção 4 (nova em maio de 2026). MCP nativo no Coolify v4.1.0.

O registo de alterações da v4.1.0, datado de 18 de maio de 2026, diz:

Foi adicionado suporte MCP ao nível da instância, com ferramentas só de leitura para recursos do Coolify e para a API/UI.

O Coolify disponibiliza agora o seu próprio endpoint MCP — pode ligar o Claude Code diretamente, sem servidores de terceiros. Por enquanto, é só de leitura (listas de aplicações, estados, configurações), sem operações de alteração. Mas isso é suficiente para a maioria das tarefas, como «diz-me o que há na infraestrutura».

Ligue-o através de .mcp.json:

{
  "mcpServers": {
    "coolify-native": {
      "url": "https://coolify.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

Aguarde pelo acesso completo de escrita no MCP nativo na v4.2 ou v4.3 — a equipa do Coolify prometeu disponibilizá-lo até ao final de 2026.

5 armadilhas na primeira implementação — e como evitá-las

Principal conclusão

Os erros mais comuns numa primeira implementação são RAM insuficiente, porta 80 fechada, proxy da Cloudflare a impedir o Let's Encrypt, UFW sem conseguir proteger o Docker e escolha de PAT em vez de GitHub App. Todos estão documentados nos guias oficiais, mas é fácil deparar-se com eles sem experiência prática. Segue-se uma lista de verificação em 5 pontos, baseada na experiência original da primeira instalação do Coolify.

Armadilha 1: Menos de 2 GB de RAM — a instalação falha com OOM.

Sintoma: curl install.sh chega a docker pull coolify/coolify, bloqueia nos 70% e, depois, o processo é terminado com Killed (signal 9). Os registos de dmesg | tail mostram Out of memory: Killed process.

Solução:

# Crie um ficheiro de swap de 4 GB para resolver temporariamente o problema
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

A longo prazo, atualize para 4 GB de RAM. O Coolify funciona com swap, mas as compilações de projetos Next.js grandes podem falhar.

Armadilha 2: O UFW está ativado, mas o Docker continua a abrir portas.

Sintoma: ativou o UFW e fechou todas as portas, exceto a 22, mas a sua aplicação continua acessível pela Internet numa porta aleatória (como a 3000).

O motivo, segundo a documentação oficial:

O Coolify é executado no Docker, que utiliza regras iptables baseadas em NAT e pode contornar firewalls Linux tradicionais, como o UFW.

— Documentação do Coolify (firewall), https://coolify.io/docs/knowledge-base/server/firewall

Solução: utilize a firewall do painel de controlo do fornecedor, não o UFW. A Timeweb / Selectel / Aeza têm uma secção «Firewall» ou «Network → Firewall», onde configura regras ao nível da rede virtual — estas são aplicadas antes de os pacotes chegarem ao Docker.

Uma alternativa é o ufw-docker, um script que corrige o UFW para ser compatível com o Docker. Mas isso é mais complicado do que clicar no painel de controlo.

Armadilha 3: O proxy da Cloudflare (nuvem laranja) impede o Let's Encrypt.

Sintoma: depois de clicar em Redeploy, os registos mostram Let's Encrypt validation failed - challenge returned 403.

Motivo: a Cloudflare encaminha o pedido HTTP do Let's Encrypt e devolve a sua própria página em vez do ficheiro de validação.

Solução — escolha uma de duas opções:

  1. Mude para «DNS only» (a nuvem cinzenta na Cloudflare). Desvantagem: perde a CDN e a proteção da Cloudflare.
  2. Configure um challenge DNS-01 através da API da Cloudflare. No Coolify, aceda a Settings → SSL Configuration, selecione o fornecedor Cloudflare e introduza um token API com permissões Zone:Read e DNS:Edit. O Let's Encrypt validará através de um registo TXT em vez de HTTP.

A segunda opção é mais complicada de configurar, mas mantém o proxy da Cloudflare.

Armadilha 4: PAT em vez de GitHub App — as pré-visualizações de PR não funcionam.

Sintoma: ligou o GitHub através de um Personal Access Token; tudo funciona, mas não são criadas implementações de pré-visualização para PRs. Abriu um PR no GitHub, mas não apareceu nada no Coolify.

Motivo: as pré-visualizações de PR são uma funcionalidade exclusiva da GitHub App. PAT não recebe eventos pull_request através de um webhook.

Solução: volte a ligar o GitHub através da App. Sources → Add → GitHub App → conclua o assistente. Pode eliminar a origem PAT antiga.

Armadilha 5: «Coolify == Vercel» não é totalmente verdade.

O que o Coolify não faz de origem:

VercelCoolifyO que fazer
CDN globalNãoColoque a Cloudflare à frente (gratuita para conteúdo estático)
Incremental Static RegenerationNãorevalidatePath funciona apenas no seu servidor
Otimização de imagensNãoUtilize next/image com um loader local ou Cloudflare Images
Escalabilidade automática nos picosNãoAumente a escala manualmente; atualize o seu VPS
Edge FunctionsNãoUtilize rotas API normais

Se o seu projeto for um SaaS de tráfego elevado, com público global e requisitos de latência de < 100 ms em todo o mundo, o Coolify não é adequado; escolha Vercel Enterprise. Se é um vibe coder com um MVP que está a testar com 100–1 000 utilizadores por dia, o Coolify cobre tudo.

De uma análise honesta de alojamento próprio:

Os 15 minutos do título deste guia referem-se ao percurso sem imprevistos da primeira implementação de um projeto. A configuração completa da infraestrutura, com monitorização, cópias de segurança e alertas, demora uma ou duas noites. Seja honesto consigo próprio.

Quanto poupará num ano em comparação com a Vercel?

Os valores Vercel seguintes são estimativas dos cenários do artigo em maio de 2026, não cotações atuais. São apenas um lado da comparação. O Coolify alojado por si não tem licença paga, mas VPS, cópias de segurança, armazenamento, tráfego e operação custam dinheiro. Obtenha uma cotação que cumpra os requisitos acima; os cenários não fornecem um preço numérico de VPS, pelo que não sustentam uma poupança fixa.

Seja C a fatura mensal total de infraestrutura do VPS escolhido, armazenamento de cópias, tráfego adicional, monitorização e eventual painel pago. Conte cada despesa uma única vez. Seja r o custo horário de operação, usando sempre a mesma moeda. A estimativa de tempo do artigo é de 5–10 horas iniciais mais 1–2 horas mensais: 17–34 horas no primeiro ano e 12–24 horas nos anos seguintes.

CenárioEstimativa Vercel/mêsVercel/anoInfraestrutura Coolify/mêsTCO Coolify no primeiro ano, com trabalhoPoupança no primeiro ano face à Vercel
Um protótipo, 100 000 visitas/mês$20 base + ~$5 tráfego = $25$300C12C + (17–34)r$300 − 12C − (17–34)r
Cinco projetos num VPS$20 base + $30 tráfego/funções = $50$600C12C + (17–34)r$600 − 12C − (17–34)r
Três programadores, cinco projetos$60 lugares + $30 tráfego = $90$1,080C12C + (17–34)r$1,080 − 12C − (17–34)r

Use um C diferente em cada cenário se as cargas precisarem de servidores diferentes. Para comparação mensal, distribua a configuração inicial por 12 meses: o equivalente mensal do primeiro ano é C + (17–34)r/12. O TCO dos anos seguintes é 12C + (12–24)r. As fórmulas comparam a estimativa Vercel declarada com as despesas de alojamento próprio; inclua também custos de operação comparáveis no lado Vercel. Poupança negativa significa maior custo de alojamento próprio com os valores introduzidos. Não volte a contar o salário integral do mesmo engenheiro se r já o incluir.

Antes de mudar, preencha C com uma cotação real e um plano de cópias, escolha r e compare a utilização efetiva durante um mês. Sem esses valores, o artigo fornece um modelo de custos, não uma poupança em dólares.

O principal benefício não é o dinheiro. Ao mudar para o Coolify, desaparece a categoria «dependência da política de pagamentos de terceiros».

O Coolify não é uma Vercel mais barata. É uma categoria de produto diferente: é proprietário da infraestrutura, assume a responsabilidade por ela e poupa dinheiro aceitando a sua complexidade.

Se implementar um protótipo for a sua primeira tarefa depois de o gerar no Claude Code, a gestão do ambiente (env, segredos, tarefas agendadas, cópias de segurança) faz parte da engenharia de contexto. Sem uma estrutura que indique «onde está tudo», o Claude perde-se e perde tempo em cada alteração. A configuração completa inclui: clone de IA (Skills e Subagents adaptados à sua metodologia) + segundo cérebro (a base de conhecimento do projeto) + engenharia de contexto (Plan Mode, /compact, ambiente de execução). Estes são os 3 pilares sem os quais a IA alucina.

O fluxo completo de contexto: clone de IA + segundo cérebro + engenharia de contexto.

Há mais materiais disponíveis em Ailoot.

Mais detalhes

Perguntas frequentes

Que URL deve devolver JSON depois da implementação?

Copie o URL da aplicação apresentado no campo Domains do Coolify e abra o caminho /api/users. O URL raiz é a página inicial; /api/users é o endpoint JSON especificado no projeto de exemplo.

Como calculo se o alojamento próprio poupa dinheiro?

Some em C os custos mensais de VPS, cópias, armazenamento, tráfego, monitorização e painel opcional. O TCO do primeiro ano é 12C mais 17–34 horas ao seu custo horário; compare com a estimativa anual Vercel do cenário e inclua custos de operação comparáveis em ambos os lados.

Todos os artigos