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.

Este guia de início rápido para uma rede confiável desativa a autenticação da API e não é uma arquitetura de produção. Ele é iniciado sem armazenamento persistente, TLS, alta disponibilidade nem todos os recursos do Firecrawl Cloud.

Escolha entre auto-hospedagem e Firecrawl Cloud

Hospede o Firecrawl por conta própria quando

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.

O que a auto-hospedagem exige

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.

Hospede o Firecrawl por conta própria com Docker Compose

Comece com estas configurações padrão

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.

Pré-requisitos

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.

Clone a versão validada

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.git
cd firecrawl
git 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.

Configure a implantação para avaliação

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

cat > .env <<'EOF'
USE_DB_AUTHENTICATION=false
POSTGRES_USER=postgres
POSTGRES_PASSWORD=replace-with-at-least-32-random-characters
POSTGRES_DB=postgres
EOF

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.

apps/api/.env.example serve para o desenvolvimento da API e não é um arquivo Compose pronto para uso. Nesta primeira execução, a autenticação do banco de dados é desativada, portanto as requisições não precisam de uma chave de API nem do header Authorization.

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 e inicie o Firecrawl

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

docker compose up --build -d
docker 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.

Verifique a acessibilidade da API

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"}

Esta é uma verificação de atividade, não um teste de ponta a ponta. Ela não verifica Redis, PostgreSQL, RabbitMQ, Playwright, workers nem o acesso à rede externa. Execute o scraping abaixo antes de considerar a implantação utilizável.

Execute um teste de fumaça funcional

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.

Suporte a recursos auto-hospedados

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

Se você precisa de	Decisão
Rotas principais de scraping, rastreamento, mapeamento e busca	Mantenha a stack padrão. O processamento com Fetch e Playwright está incluído.
Extração ou formatos baseados em LLM	Conecte um provedor compatível com OpenAI ou o Ollama e teste esse fluxo separadamente.
Fire-engine ou seu comportamento avançado antibot	Execute e configure esse serviço separadamente; ele não está incluído.
Capturas de tela ou ações na página	Não estão disponíveis na stack padrão. Fetch e Playwright não oferecem suporte; ambos exigem o Fire-engine.
Agente, Navegador, interagir, feedback ou formatos especializados de produtos, menus, áudio e vídeo	Use o Firecrawl Cloud ou verifique os requisitos de serviços externos para a funcionalidade específica.

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.

Antes da produção

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.

Próximos passos

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 Execução local para configurar o ambiente de desenvolvimento para colaboradores.
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.

Resolução de problemas

Você está ignorando a autenticação

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.

Os contêineres Docker não iniciam

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

docker compose ps --all
docker 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.

Problemas de conexão com o Redis

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 redis
docker 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.

O endpoint da API não responde

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

docker compose ps api
docker 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

A solicitação de scraping excede o tempo limite

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.

Primeiros passos

Endpoints principais

Mais

Guias de início rápido

Guias para desenvolvedores

Webhooks

Casos de uso

Outros

Como contribuir

Auto-hospedagem do Firecrawl

Escolha entre auto-hospedagem e Firecrawl Cloud

Hospede o Firecrawl por conta própria quando

O que a auto-hospedagem exige

Hospede o Firecrawl por conta própria com Docker Compose

Comece com estas configurações padrão

Pré-requisitos

Clone a versão validada

Configure a implantação para avaliação

Compile e inicie o Firecrawl

Verifique a acessibilidade da API

Execute um teste de fumaça funcional

Suporte a recursos auto-hospedados

Antes da produção

Próximos passos

Resolução de problemas

Você está ignorando a autenticação

Os contêineres Docker não iniciam

Problemas de conexão com o Redis

O endpoint da API não responde

A solicitação de scraping excede o tempo limite

​Escolha entre auto-hospedagem e Firecrawl Cloud

​Hospede o Firecrawl por conta própria quando

​O que a auto-hospedagem exige

​Hospede o Firecrawl por conta própria com Docker Compose

​Comece com estas configurações padrão

​Pré-requisitos

​Clone a versão validada

​Configure a implantação para avaliação

​Compile e inicie o Firecrawl

​Verifique a acessibilidade da API

​Execute um teste de fumaça funcional

​Suporte a recursos auto-hospedados

​Antes da produção

​Próximos passos

​Resolução de problemas

​Você está ignorando a autenticação

​Os contêineres Docker não iniciam

​Problemas de conexão com o Redis

​O endpoint da API não responde

​A solicitação de scraping excede o tempo limite

Escolha entre auto-hospedagem e Firecrawl Cloud

Hospede o Firecrawl por conta própria quando

O que a auto-hospedagem exige

Hospede o Firecrawl por conta própria com Docker Compose

Comece com estas configurações padrão

Pré-requisitos

Clone a versão validada

Configure a implantação para avaliação

Compile e inicie o Firecrawl

Verifique a acessibilidade da API

Execute um teste de fumaça funcional

Suporte a recursos auto-hospedados

Antes da produção

Próximos passos

Resolução de problemas

Você está ignorando a autenticação

Os contêineres Docker não iniciam

Problemas de conexão com o Redis

O endpoint da API não responde

A solicitação de scraping excede o tempo limite