Vai contribuir?

Bem-vindo ao Firecrawl 🔥! Aqui estão algumas instruções para obter o projeto localmente, executá-lo por conta própria e contribuir. Se você for contribuir, observe que o processo é semelhante ao de outros repositórios de código aberto: faça um fork do Firecrawl, faça alterações, rode os testes e abra um PR. Se tiver dúvidas ou precisar de ajuda para começar, entre na nossa comunidade no Discord aqui para mais informações ou abra uma issue no GitHub aqui!

Hospedando o Firecrawl por conta própria

Consulte SELF_HOST.md para instruções sobre como executá-lo localmente.

Por quê?

Hospedar o Firecrawl por conta própria é especialmente vantajoso para organizações com políticas de segurança rigorosas que exigem manter os dados em ambientes controlados. Aqui estão alguns motivos principais para considerar a hospedagem própria:
  • Segurança e conformidade reforçadas: Ao auto-hospedar, você garante que todo o tratamento e processamento de dados esteja em conformidade com regulamentações internas e externas, mantendo informações sensíveis dentro da sua infraestrutura segura. Observe que o Firecrawl é um produto da Mendable e possui certificação SOC 2 Type II, o que significa que a plataforma segue altos padrões do setor para gestão da segurança de dados.
  • Serviços personalizáveis: A hospedagem própria permite adaptar serviços, como o Playwright, para atender a necessidades específicas ou lidar com casos de uso particulares que podem não ser contemplados pela oferta padrão em nuvem.
  • Aprendizado e contribuição para a comunidade: Ao configurar e manter sua própria instância, você obtém um entendimento mais profundo de como o Firecrawl funciona, o que também pode resultar em contribuições mais relevantes para o projeto.

Considerações

No entanto, há algumas limitações e responsabilidades adicionais das quais você deve estar ciente:
  1. Acesso limitado ao Fire-engine: Atualmente, instâncias auto-hospedadas do Firecrawl não têm acesso ao Fire-engine, que inclui recursos avançados para lidar com bloqueios de IP, mecanismos de detecção de robôs e mais. Isso significa que, embora você possa gerenciar tarefas básicas de scraping, cenários mais complexos podem exigir configuração adicional ou talvez não sejam suportados.
  2. Configuração manual necessária: Se você precisar usar métodos de scraping além das opções básicas de fetch e Playwright, será necessário configurá-los manualmente no arquivo .env. Isso exige um entendimento mais profundo das tecnologias e pode demandar mais tempo de configuração.
Hospedar o Firecrawl por conta própria é ideal para quem precisa de controle total sobre seus ambientes de scraping e processamento de dados, mas tem como contrapartida a necessidade de manutenção e configurações adicionais.

Passos

  1. Primeiro, instale as dependências
  1. Defina as variáveis de ambiente
Crie um .env no diretório raiz; você pode copiar o template em apps/api/.env.example. Para começar, não vamos configurar autenticação nem quaisquer subserviços opcionais (análise de PDF, suporte a bloqueio de JS, recursos de IA).
# .env

# ===== Variáveis de ambiente obrigatórias ======
NUM_WORKERS_PER_QUEUE=8 
PORT=3002
HOST=0.0.0.0

# para auto-hospedagem com Docker, use redis://redis:6379. Para executar localmente, use redis://localhost:6379
REDIS_URL=redis://redis:6379

# para auto-hospedagem com Docker, use redis://redis:6379. Para executar localmente, use redis://localhost:6379
REDIS_RATE_LIMIT_URL=redis://redis:6379 
PLAYWRIGHT_MICROSERVICE_URL=http://playwright-service:3000/html

## Para ativar a autenticação no banco de dados, você precisa configurar o Supabase.
USE_DB_AUTHENTICATION=false

# ===== Variáveis de ambiente opcionais ======

# Configuração do Supabase (usada para autenticação no banco de dados, logs avançados, etc.)
SUPABASE_ANON_TOKEN= 
SUPABASE_URL= 
SUPABASE_SERVICE_TOKEN=

# Outros opcionais
# use se você configurou autenticação e quer testar com uma chave de API real
TEST_API_KEY=
# defina se quiser testar o limite de taxa de scraping
RATE_LIMIT_TEST_API_KEY_SCRAPE=
# defina se quiser testar o limite de taxa de crawling
RATE_LIMIT_TEST_API_KEY_CRAWL=
# adicione para recursos dependentes de LLM (geração de texto alternativo de imagem, etc.)
OPENAI_API_KEY=
BULL_AUTH_KEY=@
# use se estiver configurando logging básico com o Logtail
LOGTAIL_KEY=
# defina se tiver uma chave do LlamaParse que queira usar para processar PDFs
LLAMAPARSE_API_KEY=
# defina se quiser enviar mensagens de status de saúde do servidor para o Slack
SLACK_WEBHOOK_URL=
# defina se quiser enviar eventos do PostHog como logs de jobs
POSTHOG_API_KEY=
# defina se quiser enviar eventos do PostHog como logs de jobs
POSTHOG_HOST=

# defina se quiser usar a closed beta do Fire Engine
FIRE_ENGINE_BETA_URL=

# Configurações de proxy para o Playwright (como alternativa, você pode usar um serviço de proxy como o Oxylabs, que rotaciona IPs a cada requisição)
PROXY_SERVER=
PROXY_USERNAME=
PROXY_PASSWORD=
# defina se quiser bloquear requisições de mídia para economizar banda do proxy
BLOCK_MEDIA=

# Defina a URL do seu webhook ao usar a versão auto-hospedada do Firecrawl
SELF_HOSTED_WEBHOOK_URL=

# Chave de API do Resend para e-mails transacionais
RESEND_API_KEY=

# LOGGING_LEVEL determina a verbosidade dos logs que o sistema emitirá.
# Níveis disponíveis:
# NONE - Nenhum log será emitido.
# ERROR - Para registrar mensagens de erro que indicam falha em uma operação específica.
# WARN - Para registrar situações potencialmente prejudiciais que não são necessariamente erros.
# INFO - Para registrar mensagens informativas que destacam o progresso da aplicação.
# DEBUG - Para registrar informações detalhadas sobre o fluxo do sistema, usadas principalmente para depuração.
# TRACE - Para registrar informações ainda mais detalhadas do que o nível DEBUG.
# Defina LOGGING_LEVEL para uma das opções acima a fim de controlar a saída de logs.
LOGGING_LEVEL=INFO
  1. (Opcional) Executar com o TypeScript Playwright Service
    • Atualize o arquivo docker-compose.yml para alterar o serviço do Playwright:
          build: apps/playwright-service
      
      PARA
          build: apps/playwright-service-ts
      
    • Defina PLAYWRIGHT_MICROSERVICE_URL no seu arquivo .env:
      PLAYWRIGHT_MICROSERVICE_URL=http://localhost:3000/scrape
      
    • Não se esqueça de configurar o servidor proxy no arquivo .env, se necessário.
  2. Compile e execute os contêineres Docker:
    docker compose build
    docker compose up
    
Isso iniciará uma instância local do Firecrawl, acessível em http://localhost:3002. Você deverá ver a interface do Bull Queue Manager em http://localhost:3002/admin/@/queues.
  1. (Opcional) Testar a API
Se quiser testar o endpoint /crawl, execute:
  curl -X POST http://localhost:3002/v2/crawl \
      -H 'Content-Type: application/json' \
      -d '{
        "url": "https://docs.firecrawl.dev"
      }'

Solução de problemas

Esta seção apresenta soluções para problemas comuns que você pode encontrar ao configurar ou executar sua instância auto-hospedada do Firecrawl.

O cliente Supabase não está configurado

Sintoma:
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - Tentativa de acessar o cliente do Supabase quando ele não está configurado.
[YYYY-MM-DDTHH:MM:SS.SSSz]ERROR - Erro ao inserir evento de scraping: Erro: o cliente do Supabase não está configurado.
Explicação: Esse erro ocorre porque a configuração do cliente do Supabase não foi concluída. Você deve conseguir executar scraping e crawling sem problemas. No momento, não é possível configurar o Supabase em instâncias auto-hospedadas.

Você está ignorando a autenticação

Sintoma:
[YYYY-MM-DDTHH:MM:SS.SSSz]WARN - Você está contornando a autenticação
Explicação: Esse erro ocorre porque a configuração do cliente do Supabase não foi concluída. Você deve conseguir fazer scraping e crawling sem problemas. No momento, não é possível configurar o Supabase em instâncias autohospedadas.

Contêineres Docker não iniciam

Sintoma: Contêineres Docker encerram inesperadamente ou não chegam a iniciar. Solução: Verifique os logs do Docker em busca de mensagens de erro usando o comando:
docker logs [nome_do_container]
  • Certifique-se de que todas as variáveis de ambiente necessárias estejam definidas corretamente no arquivo .env.
  • Verifique se todos os serviços do Docker definidos em docker-compose.yml estão configurados corretamente e se as imagens necessárias estão disponíveis.

Problemas de conexão com o Redis

Sintoma: Erros ao conectar ao Redis, como timeouts ou “Connection refused”. Solução:
  • Garanta que o serviço do Redis esteja ativo e em execução no seu ambiente Docker.
  • Verifique se as variáveis REDIS_URL e REDIS_RATE_LIMIT_URL no seu arquivo .env apontam para a instância correta do Redis.
  • Confira as configurações de rede e as regras de firewall que possam estar bloqueando a conexão com a porta do Redis.

O endpoint da API não responde

Sintoma: As requisições de API para a instância do Firecrawl esgotam o tempo (timeout) ou não retornam resposta. Solução:
  • Verifique se o serviço do Firecrawl está em execução conferindo o status do contêiner Docker.
  • Confirme se as variáveis PORT e HOST no arquivo .env estão corretas e se nenhum outro serviço está usando a mesma porta.
  • Verifique a configuração de rede para garantir que o host esteja acessível a partir do cliente que faz a requisição de API.
Ao corrigir esses problemas comuns, você garante uma configuração e operação mais estáveis da sua instância autogerenciada do Firecrawl.

Instalar o Firecrawl em um cluster Kubernetes (versão simples)

Leia o examples/kubernetes-cluster-install/README.md para instruções de como instalar o Firecrawl em um cluster Kubernetes.