Auto-hospedagem do Firecrawl

Hospede o Firecrawl por conta própria com Docker Compose quando precisar ter controle sobre o código-fonte ou a infraestrutura. Este guia usa a versão v2.11.162, inicia a API em http://localhost:3002 e verifica uma resposta bem-sucedida a POST /v2/scrape com Markdown.

• Você quer ter controle sobre o código-fonte ou a infraestrutura. Este guia coloca a API e os serviços de suporte em funcionamento na sua máquina.
• Você se sente à vontade para operar a stack. Você será responsável por atualizações, segurança, armazenamento, monitoramento e recuperação.
• Você quer validar o Firecrawl no seu ambiente. Faça a configuração básica funcionar aqui e, depois, defina os controles em Antes da produção.

Escolha o Firecrawl Cloud quando quiser começar a fazer scraping sem precisar operar infraestrutura. Consulte Código aberto vs. Cloud para conhecer as diferenças de recursos.

Nossa recomendação: hospede por conta própria quando o acesso ao código-fonte ou o controle da infraestrutura justificar o trabalho operacional. Se quiser o caminho com suporte mais rápido para produção, comece com o Firecrawl Cloud.

• Você é responsável por atualizações, segredos, armazenamento, monitoramento, recuperação e resposta a incidentes.
• O scraping ainda envia solicitações para sites de destino. Provedores opcionais de proxy, análise ou IA adicionam outros fluxos de dados.
• Este guia mantém a primeira execução intencionalmente simples. Primeiro, faça um scraping funcionar e, depois, altere uma decisão por vez.
• Os comandos estão fixados na versão v2.11.162. Uma versão diferente pode usar um contrato do Compose diferente.

• Versão: Firecrawl v2.11.162. Primeiro, fixe o código e a configuração. Atualize após revisar o docker-compose.yaml e as notas de auto-hospedagem da versão de destino.
• Autenticação da API: desativada para esta execução local. Adicione-a apenas com uma arquitetura completa e compatível de identidade e banco de dados; uma variável de ambiente não é suficiente.
• Fila: PostgreSQL. Mantenha-o, a menos que você queira operar intencionalmente o backend opcional do FoundationDB.
• UI de administração da fila: desativada. Habilite-a apenas com uma BULL_AUTH_KEY forte e controles de rede.
• Provedores de IA e scraping avançado: não configurados. Adicione um provedor quando precisar de uma capacidade que o exija.

Mantenha a primeira execução simples: faça um scraping funcionar e, depois, adicione o que seu caso de uso exigir.

Antes de começar, instale:

• Git
• Docker Engine ou Docker Desktop
• Docker Compose v2, chamado como docker compose
• curl para as requisições de verificação

Certifique-se de que a porta 3002 esteja disponível e que o Docker tenha capacidade suficiente para compilar e executar vários serviços. O Firecrawl não especifica uma configuração mínima de host validada para esta stack.

Este guia foi validado com o Firecrawl v2.11.162. Faça checkout dessa versão específica para manter o código, os comandos e a configuração sincronizados:

git clone https://github.com/firecrawl/firecrawl.gitcd firecrawlgit checkout v2.11.162

Quer usar outra versão? Consulte o docker-compose.yaml e as notas sobre auto-hospedagem antes de reutilizar estes valores.

Crie o menor arquivo .env funcional na raiz do repositório:

cat > .env <<'EOF'USE_DB_AUTHENTICATION=falsePOSTGRES_USER=postgresPOSTGRES_PASSWORD=replace-with-at-least-32-random-charactersPOSTGRES_DB=postgresEOF

Substitua a senha do PostgreSQL antes de iniciar a stack e não faça commit do .env. Mantenha POSTGRES_DB=postgres para a versão v2.11.162, pois a configuração integrada do pg_cron é direcionada a esse banco de dados. O Compose repassa esses valores tanto para a API quanto para o serviço PostgreSQL.

Deixe NUQ_BACKEND e BULL_AUTH_KEY sem definir. Você usará a fila do PostgreSQL sem executar a UI de administração da fila — menos componentes envolvidos no primeiro scraping.

Compile o código-fonte clonado e inicie tudo em segundo plano:

docker compose up --build -ddocker compose ps --all

Avisos sobre variáveis opcionais não definidas são esperados nesta configuração de referência. docker compose ps --all deve mostrar a API e os serviços de suporte em execução, com os serviços de inicialização única concluídos. Aguarde um pouco caso os serviços ainda estejam sendo iniciados.

Primeiro, confirme se a API consegue responder a uma solicitação HTTP:

curl \  --fail \  --silent \  --show-error \  --max-time 5 \  http://localhost:3002/v0/health/readiness

Resposta esperada:

{"status":"ok"}

Agora, teste o que importa: um scraping real. O tempo limite da solicitação é em milissegundos; o tempo limite do cliente curl é em segundos e é um pouco maior:

curl \  --fail-with-body \  --silent \  --show-error \  --max-time 75 \  -X POST \  http://localhost:3002/v2/scrape \  -H 'Content-Type: application/json' \  -d '{    "url": "https://example.com",    "formats": ["markdown"],    "timeout": 60000  }'

Uma resposta bem-sucedida tem este formato:

{  "success": true,  "data": {    "markdown": "...",    "metadata": {      "statusCode": 200    }  }}

Isso verifica em conjunto a API, o pipeline de scraping, um caminho do mecanismo de scraping e o acesso de saída. Os metadados exatos podem variar conforme a resposta do destino.

Se você receber esses campos de sucesso, o Firecrawl estará funcionando de ponta a ponta na sua infraestrutura. Mantenha essa referência e escolha o que adicionar em seguida.

Seu primeiro scraping funciona. Adicione a próxima funcionalidade porque precisa dela, não apenas porque ela existe:

Para uma comparação mais ampla entre os produtos, consulte Código aberto vs. Cloud. Para configurações específicas de cada versão, use o docker-compose.yaml fixado como fonte complementar.

O Compose permite chegar ao primeiro resultado. A produção exige algumas decisões explícitas antes de expor a API fora de uma rede confiável:

• Se os dados precisarem sobreviver à substituição de serviços, adicione armazenamento persistente para PostgreSQL, Redis e RabbitMQ e defina e teste procedimentos de backup e restauração. O arquivo Compose fornecido não adiciona esses volumes.
• Se usuários ou redes não confiáveis puderem acessar a API, implemente um modelo de autenticação compatível, controles de acesso à rede e TLS em um proxy reverso ou controlador de entrada. Não exponha publicamente essa configuração de referência sem autenticação.
• Se houver requisitos de disponibilidade ou capacidade, defina metas de disponibilidade, monitoramento, dimensionamento de recursos, gatilhos de escalonamento e procedimentos de atualização e reversão. Os limites do Compose não são requisitos mínimos comprovados.
• Se a localização dos dados ou a conformidade for importante, mapeie as solicitações para os sites-alvo e para todos os provedores opcionais de IA, proxy ou análise antes de ativá-los.
• Se os segredos precisarem ser gerenciados centralmente, mova a senha do banco de dados de .env para o sistema de gerenciamento de segredos da sua plataforma.

Essas são decisões de infraestrutura. Nenhuma configuração isolada em .env deixa a stack pronta para produção.

• Ainda avaliando? Mantenha a API em uma rede confiável e execute docker compose down quando terminar.
• Adicionando um recurso de código aberto? Use Suporte a recursos auto-hospedados para encontrar o provedor ou serviço necessário e teste esse fluxo isoladamente.
• Alterando o código do Firecrawl? Consulte Configuração para colaboradores para o ambiente de desenvolvimento.
• Conectando um cliente? Aponte a CLI do Firecrawl ou o servidor MCP local para o URL verificado da sua API.
• Migrando para o Kubernetes? Comece pelas referências versionadas de Kubernetes ou Helm vinculadas em SELF_HOST.md e, depois, defina explicitamente as decisões de produção acima para sua plataforma.
• Quer infraestrutura gerenciada ou recursos exclusivos da Cloud? Compare Código aberto vs. Cloud.
• Indo para produção? Conclua todas as decisões em Antes da produção antes de expor a API.

Se este aviso aparecer com USE_DB_AUTHENTICATION=false, você está no fluxo esperado da primeira execução. As solicitações usam uma identidade auto-hospedada e não exigem uma chave de API. Se a API estiver acessível em uma rede não confiável, interrompa o processo e adicione os controles descritos em Antes da produção.

Se algum serviço de longa execução for encerrado, inspecione o estado do contêiner e os logs recentes:

docker compose ps --alldocker compose logs --tail=200

• Se a revisão de origem for diferente, faça checkout de v2.11.162 ou use a configuração dessa versão.
• Se um build ou contêiner estiver com recursos limitados, aumente a capacidade de CPU, memória ou disco do Docker.
• Se o PostgreSQL falhar, verifique a sintaxe do .env, mantenha POSTGRES_DB=postgres e certifique-se de que os valores de usuário e senha sejam consistentes.

Se um contêiner não conseguir se conectar ao Redis, mantenha o endereço do serviço do Compose como redis://redis:6379. localhost se refere ao próprio contêiner, não ao serviço Redis.

docker compose ps redisdocker compose logs --tail=100 redis

Se você adicionou REDIS_URL ou REDIS_RATE_LIMIT_URL, remova a substituição para restaurar o padrão ou use um endereço que possa ser resolvido dentro da rede do Compose.

Se a porta 3002 não responder, verifique o contêiner da API e os respectivos logs:

docker compose ps apidocker compose logs --tail=200 api

Se outro processo estiver usando a porta 3002, interrompa-o ou altere a porta exposta de forma consistente. Durante a inicialização, tente novamente somente depois que o contêiner da API estiver em execução.

Se /v0/health/readiness for bem-sucedido, mas /v2/scrape falhar, verifique os logs da API e do Playwright, pois o endpoint de disponibilidade não valida essas dependências:

docker compose logs --tail=200 api playwright-service

Se o scraping exceder o tempo limite, confirme que a implantação consegue acessar https://example.com e que os serviços da API e do Playwright estão em execução. Mantenha o --max-time do curl maior que o timeout no corpo da solicitação para que a API possa retornar sua própria resposta de tempo limite.