---
title: Docker
description: "Run Mudabbir in Docker with the included Dockerfile and docker-compose.yml. Multi-stage build, non-root user, Playwright browser support, optional Ollama and Qdrant services via Compose profiles."
section: Deployment
ogType: article
keywords: ["docker", "container", "docker-compose", "dockerfile", "containerized ai"]
tags: ["deployment", "docker"]
---

# Docker Deployment

Mudabbir ships with a production-ready `Dockerfile` and `docker-compose.yml` in the repository root. The Docker image includes all extras (`[all]`), Playwright Chromium, and tesseract OCR — everything works out of the box.

## Quick Start

```bash
# Clone the repo
git clone https://github.com/Ahmed5754/Mudabbir.git
cd mudabbir

# Copy the env template and fill in your keys
cp .env.example .env

# Build and start
docker compose up -d
```

The dashboard is available at `http://localhost:8888`.

<Callout type="warning">
  Docker's bridge networking means localhost auth bypass doesn't work inside a container. You'll need to log in with the access token.
</Callout>

Get the access token and paste it into the login page:

```bash
docker exec mudabbir cat /home/mudabbir/.mudabbir/access_token
```

## Dockerfile Overview

The `Dockerfile` uses a multi-stage build for a lean runtime image:

**Builder stage** (`python:3.12-slim`):
- Installs build dependencies (`gcc`, `python3-dev`, `git`)
- Creates a virtual environment and installs `mudabbir[all]`
- Downloads Playwright Chromium

**Runtime stage** (`python:3.12-slim`):
- Installs only runtime system deps (tesseract, Chromium shared libs, curl)
- Copies the venv and Playwright browsers from the builder
- Runs as a non-root `mudabbir` user
- Exposes port `8888` with a healthcheck

<Callout type="info">
  The container binds to `0.0.0.0:8888` by default (set via `MUDABBIR_WEB_HOST` and `MUDABBIR_WEB_PORT` environment variables in the Dockerfile).
</Callout>

## Docker Compose

The `docker-compose.yml` defines three services. Only the main `mudabbir` service starts by default — Ollama and Qdrant are behind [Compose profiles](https://docs.docker.com/compose/profiles/).

### Default (Mudabbir only)

```bash
docker compose up -d
```

### With Ollama (local LLM)

```bash
docker compose --profile ollama up -d
```

Set the Ollama host to the container service name in your `.env`:

```bash
MUDABBIR_OLLAMA_HOST=http://ollama:11434
```

Then pull the models you need:

```bash
docker compose exec ollama ollama pull llama3.2
docker compose exec ollama ollama pull nomic-embed-text
```

<Callout type="tip">
  For GPU passthrough with NVIDIA, uncomment the `deploy.resources.reservations` block in `docker-compose.yml`.
</Callout>

### With Qdrant (vector memory)

```bash
docker compose --profile qdrant up -d
```

Qdrant is needed for Mem0 semantic memory. It exposes port `6333` for the REST API.

### All services

```bash
docker compose --profile ollama --profile qdrant up -d
```

## Environment Variables

All configuration is passed via environment variables. Copy `.env.example` to `.env` and fill in the values you need:

```bash
cp .env.example .env
```

The `.env.example` file is organized by section (LLM, channels, memory, tools, security) and documents every available `MUDABBIR_` variable. See the [Configuration reference](/getting-started/configuration) for full details.

You can also change the host port:

```bash
MUDABBIR_PORT=9000 docker compose up -d
```

## Persistent Data

A named Docker volume (`mudabbir-data`) is mounted at `/home/mudabbir/.mudabbir` to persist:

- Configuration (`config.json`, `secrets.enc`)
- Session history
- Memory data (file-based and Mem0)
- OAuth tokens
- Audit logs
- MCP server configs
- Skills

Data survives `docker compose down` and `docker compose up` cycles. To fully reset, remove the volume:

```bash
docker compose down -v
```

## Managing the Container

```bash
# View logs
docker compose logs -f mudabbir

# Restart
docker compose restart mudabbir

# Stop everything
docker compose down

# Rebuild after pulling updates
git pull && docker compose build && docker compose up -d
```

## Browser Automation

Playwright Chromium is included in the Docker image along with all required shared libraries. Browser tools work out of the box inside the container — no additional setup needed.

## Limitations

- **Desktop tools** (`pyautogui`) require a display server and won't work in a headless container. They fail gracefully at invocation time.
- **WhatsApp Personal mode** (neonize QR pairing) requires a persistent session. The named volume handles this, but the QR code must be scanned via the web dashboard on first setup.

## Next Steps

<CardGroup>
  <Card title="Self-Hosting" icon="lucide:server" href="/deployment/self-hosting">
    Reverse proxy, SSL, and production hardening.
  </Card>
  <Card title="Systemd Service" icon="lucide:terminal" href="/deployment/systemd">
    Run Mudabbir as a background service without Docker.
  </Card>
</CardGroup>
