> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-8bb4v8.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-hospedagem do Firecrawl

> Hospede o Firecrawl por conta própria com Docker Compose, verifique um scraping local, entenda as limitações do código aberto e prepare a stack para produção.

<span id="self-hosting-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.

<Warning>
  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.
</Warning>

<div id="choose-self-hosting-or-firecrawl-cloud">
  ## Escolha entre auto-hospedagem e Firecrawl Cloud
</div>

<div id="self-host-firecrawl-when">
  ### Hospede o Firecrawl por conta própria quando
</div>

* **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](#before-production).

Escolha o [Firecrawl Cloud](https://firecrawl.dev) quando quiser começar a fazer scraping sem precisar operar infraestrutura. Consulte [Código aberto vs. Cloud](/pt-BR/contributing/open-source-or-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.

<div id="what-self-hosting-requires">
  ### O que a auto-hospedagem exige
</div>

* 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.

<div id="self-host-firecrawl-with-docker-compose">
  ## Hospede o Firecrawl por conta própria com Docker Compose
</div>

<div id="start-with-these-defaults">
  ### Comece com estas configurações padrão
</div>

* **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.

<div id="prerequisites">
  ### Pré-requisitos
</div>

Antes de começar, instale:

* [Git](https://git-scm.com/downloads)
* [Docker Engine](https://docs.docker.com/engine/install/) 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.

<div id="clone-the-verified-release">
  ### Clone a versão validada
</div>

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:

```bash theme={null}
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.

<div id="configure-the-evaluation-deployment">
  ### Configure a implantação para avaliação
</div>

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

```bash theme={null}
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.

<Note>
  `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`.
</Note>

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.

<div id="build-and-start-firecrawl">
  ### Compile e inicie o Firecrawl
</div>

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

```bash theme={null}
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.

<div id="check-api-reachability">
  ### Verifique a acessibilidade da API
</div>

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

```bash theme={null}
curl \
  --fail \
  --silent \
  --show-error \
  --max-time 5 \
  http://localhost:3002/v0/health/readiness
```

Resposta esperada:

```json theme={null}
{"status":"ok"}
```

<Warning>
  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.
</Warning>

<div id="run-a-functional-smoke-test">
  ### Execute um teste de fumaça funcional
</div>

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:

```bash theme={null}
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:

```json theme={null}
{
  "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.

<div id="self-hosted-feature-support">
  ## Suporte a recursos auto-hospedados
</div>

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](/pt-BR/contributing/open-source-or-cloud). Para configurações específicas de cada versão, use o [`docker-compose.yaml`](https://github.com/firecrawl/firecrawl/blob/v2.11.162/docker-compose.yaml) fixado como fonte complementar.

<div id="before-production">
  ## Antes da produção
</div>

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.

<div id="where-to-go-next">
  ## Próximos passos
</div>

* **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](#self-hosted-feature-support) para encontrar o provedor ou serviço necessário e teste esse fluxo isoladamente.
* **Alterando o código do Firecrawl?** Consulte [Execução local](/pt-BR/contributing/guide) para configurar o ambiente de desenvolvimento para colaboradores.
* **Conectando um cliente?** Aponte a [CLI do Firecrawl](/pt-BR/sdks/cli#connect-the-cli-to-self-hosted-firecrawl) ou o [servidor MCP local](/pt-BR/mcp-server/local#connect-mcp-to-self-hosted-firecrawl) 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`](https://github.com/firecrawl/firecrawl/blob/main/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](/pt-BR/contributing/open-source-or-cloud).
* **Indo para produção?** Conclua todas as decisões em [Antes da produção](#before-production) antes de expor a API.

<div id="troubleshooting">
  ## Resolução de problemas
</div>

<div id="youre-bypassing-authentication">
  ### Você está ignorando a autenticação
</div>

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](#before-production).

<div id="docker-containers-fail-to-start">
  ### Os contêineres Docker não iniciam
</div>

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

```bash theme={null}
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.

<div id="connection-issues-with-redis">
  ### Problemas de conexão com o Redis
</div>

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.

```bash theme={null}
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.

<div id="api-endpoint-does-not-respond">
  ### O endpoint da API não responde
</div>

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

```bash theme={null}
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:

```bash theme={null}
docker compose logs --tail=200 api playwright-service
```

<div id="scrape-request-times-out">
  ### A solicitação de scraping excede o tempo limite
</div>

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.