# How to Deploy Crawl4AI in Docker with the Official Image

> Quickly deploy Crawl4AI using the official Docker image. Follow simple steps to run it locally or use docker-compose for production-ready deployments. Get started now.

- Repository: [UncleCode/crawl4ai](https://github.com/unclecode/crawl4ai)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Deploy Crawl4AI by pulling the official `unclecode/crawl4ai` image from Docker Hub and running it with port mapping and shared memory allocation, or orchestrate production-ready stacks using the repository's [`docker-compose.yml`](https://github.com/unclecode/crawl4ai/blob/main/docker-compose.yml) file.**

Crawl4AI provides an official Docker image that packages the FastAPI service, Redis cache, and Playwright browser engine into a hardened, single-container deployment. Whether you need to deploy crawl4ai in docker for local development or production scraping workflows, this guide covers the official image architecture, runtime configuration, and API access patterns based on the source code in the `unclecode/crawl4ai` repository.

## Understanding the Official Image Architecture

The official image (`unclecode/crawl4ai:latest`) is built from the repository's [`Dockerfile`](https://github.com/unclecode/crawl4ai/blob/main/Dockerfile), which uses `python:3.12-slim-bookworm` as its secure, minimal base. The build process installs system dependencies including `build-essential`, `git`, `redis-server`, `supervisor`, and a full suite of Chromium libraries required by Playwright (lines 34-66). For AMD64 systems requiring hardware acceleration, passing `ENABLE_GPU=true` as a build argument installs the CUDA toolkit (lines 77-84).

### Security Hardening and Process Management

The container enforces security through a dedicated non-root `appuser` created in lines 102-107 of the Dockerfile, ensuring the process runs without elevated privileges. A health check defined in lines 87-95 periodically verifies that the FastAPI service responds at `http://localhost:11235/health`. Inside the container, **Supervisor** (configured via [`deploy/docker/supervisord.conf`](https://github.com/unclecode/crawl4ai/blob/main/deploy/docker/supervisord.conf) at line 205) manages both the Redis server and the FastAPI application, automatically restarting either service if they crash.

## Quick Start with Docker Run

For immediate testing without custom builds, pull the pre-built image and expose port 11235:

```bash
docker pull unclecode/crawl4ai:latest

docker run -d \
  -p 11235:11235 \
  --shm-size=1g \
  --name crawl4ai \
  unclecode/crawl4ai:latest

```

The `--shm-size=1g` flag is critical for Chromium stability, allocating sufficient shared memory for browser process communication. Upon startup, Supervisor launches Redis and the FastAPI server automatically, making the API available at `http://localhost:11235`.

## Production Deployment with Docker Compose

For persistent deployments with health monitoring and resource constraints, use the provided [[`docker-compose.yml`](https://github.com/unclecode/crawl4ai/blob/main/docker-compose.yml)](https://github.com/unclecode/crawl4ai/blob/main/docker-compose.yml):

```yaml
version: '3.8'

x-base-config: &base-config
  ports:
    - "11235:11235"
  volumes:
    - /dev/shm:/dev/shm
  env_file:
    - .llm.env
  deploy:
    resources:
      limits:
        memory: 4G
  restart: unless-stopped
  healthcheck:
    test: ["CMD", "curl", "-f", "http://localhost:11235/health"]
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 40s
  user: "appuser"

services:
  crawl4ai:
    image: ${IMAGE:-unclecode/crawl4ai:${TAG:-latest}}
    build:
      context: .
      dockerfile: Dockerfile
      args:
        INSTALL_TYPE: ${INSTALL_TYPE:-default}
        ENABLE_GPU: ${ENABLE_GPU:-false}
    <<: *base-config

```

Deploy the stack with:

```bash
docker compose up -d

```

This configuration mounts the host's shared memory into the container, enforces the non-root `appuser` at runtime (line 34), and applies a 4GB memory limit to prevent resource exhaustion.

### Build Arguments for Customization

When building locally rather than pulling the official image, you can customize the deployment using these Dockerfile arguments:

- **`INSTALL_TYPE`**: Controls dependency installation profiles (default or full)
- **`ENABLE_GPU`**: Enables CUDA support when set to `true` on AMD64 architectures
- **`USE_LOCAL`**: Determines whether to install the package from local source (`/tmp/project`) or directly from GitHub

## Accessing the API and Dashboard

Once the container is healthy, interact with the crawler through the REST API or web interface. Submit crawl jobs programmatically:

```python
import requests

response = requests.post(
    "http://localhost:11235/crawl",
    json={"urls": ["https://example.com"], "priority": 10}
)

if response.ok:
    task_id = response.json()["task_id"]
    result = requests.get(f"http://localhost:11235/task/{task_id}").json()
    print(result["results"])

```

Access the real-time monitoring dashboard at `http://localhost:11235/dashboard` to view browser pool utilization, memory consumption, and active crawl tasks.

## Summary

- The official `unclecode/crawl4ai` image combines FastAPI, Redis, and Playwright into a single container orchestrated by Supervisor according to [`deploy/docker/supervisord.conf`](https://github.com/unclecode/crawl4ai/blob/main/deploy/docker/supervisord.conf)
- Use `docker run -p 11235:11235 --shm-size=1g` for quick deployments, ensuring adequate shared memory for Chromium rendering processes
- Production environments should use the provided [`docker-compose.yml`](https://github.com/unclecode/crawl4ai/blob/main/docker-compose.yml) with explicit health checks, 4GB memory limits, and the non-root `appuser` for security isolation
- The container exposes port 11235 for the REST API and serves a monitoring dashboard at the `/dashboard` endpoint
- GPU acceleration is available when building the image with `ENABLE_GPU=true` on AMD64 architectures

## Frequently Asked Questions

### What port does Crawl4AI use in Docker?

Crawl4AI exposes the FastAPI service on port 11235 inside the container. You must map this to a host port using `-p 11235:11235` in Docker run commands or the ports section of Docker Compose to access the API and web dashboard from outside the container.

### How do I enable GPU support in the Crawl4AI container?

GPU support requires building the image locally with the `ENABLE_GPU=true` build argument on AMD64 architecture. The Dockerfile installs CUDA toolkit dependencies in lines 77-84 when this flag is enabled, allowing Playwright to leverage GPU acceleration for browser rendering tasks.

### Is the Crawl4AI Docker image secure for production?

Yes. The Dockerfile implements security hardening by creating a dedicated non-root `appuser` in lines 102-107, disabling file URL access and external hooks by default as documented in v0.8.0 security fixes. The health check defined in lines 87-95 provides automated failure detection for orchestration platforms.

### Why does the container need `--shm-size=1g`?

Chromium and Playwright require shared memory (`/dev/shm`) for inter-process communication and rendering complex JavaScript-heavy pages. Without adequate shared memory (Docker defaults to 64MB), Chromium crashes during execution. The [`docker-compose.yml`](https://github.com/unclecode/crawl4ai/blob/main/docker-compose.yml) persists this by mounting the host's `/dev/shm` volume directly into the container.