> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy with Docker Compose

> Run the PraisonAI agents API + Postgres locally with one command

Run your agents behind a production-like API with a pgvector Postgres database using a single command.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Compose Stack"
        CLI[💻 deploy compose up] --> Gen[🔐 Generate .env]
        Gen --> API[🚀 api :8005]
        Gen --> DB[🗄️ postgres]
        API --> Health[✅ /health]
    end

    classDef cli fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef gen fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef svc fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff

    class CLI cli
    class Gen gen
    class API,DB svc
    class Health ok
```

<Warning>
  The compose stack ships in the git checkout, **not** in the PyPI wheel (`MANIFEST.in` excludes `infra/`). Run from a full monorepo checkout, or point the CLI at the stack with `PRAISONAI_INFRA_ROOT` / `PRAISONAI_COMPOSE_STACK`.
</Warning>

## Quick Start

<Steps>
  <Step title="Scaffold an agents.yaml">
    Start from the compose starter (or bring your own `agents.yaml`).

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy create --template docker-compose
    ```
  </Step>

  <Step title="Start the stack">
    The first run auto-generates a strong `POSTGRES_PASSWORD` and launches both services in the background.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy compose up
    ```

    The API is served at `http://127.0.0.1:8005`.
  </Step>

  <Step title="Call your agent">
    Hit the health endpoint, then chat.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl http://127.0.0.1:8005/health
    ```
  </Step>

  <Step title="Stop the stack">
    Stop the containers; add `-v` to also drop the Postgres volume.

    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai deploy compose down
    ```
  </Step>
</Steps>

***

## How It Works

`compose up` copies your `agents.yaml` into `.praisonai-compose/`, generates `api_server.py`, writes a locked-down `.env`, then runs `docker compose up`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as deploy compose up
    participant FS as .praisonai-compose/
    participant Docker

    User->>CLI: praisonai deploy compose up
    CLI->>FS: Copy agents.yaml + generate api_server.py
    CLI->>FS: Write .env (auto POSTGRES_PASSWORD, chmod 0600)
    CLI->>Docker: docker compose up -d
    Docker->>Docker: Start postgres (healthcheck)
    Docker->>Docker: Start api :8005 (GET /health)
    Docker-->>User: http://127.0.0.1:8005
```

| Service | Image | Port | Notes |
| - | - | - | - |
| `postgres` | `pgvector/pgvector:pg16` | `${POSTGRES_BIND:-127.0.0.1}:5432` | Healthchecked; **loopback-bound by default**. |
| `api` | `ghcr.io/mervinpraison/praisonai:latest` | `8005` | Runs `api_server.py`; healthcheck on `/health`. |

The named volume `postgres_data` persists the database between restarts.

***

## Commands

Two subcommands manage the stack.

| Command | Flag | Default | Description |
| - | - | - | - |
| `compose up` | `--file` / `-f` | `agents.yaml` | Agents file to serve. |
| | `--stack-dir` | *(resolved)* | Override the compose stack template directory. |
| | `--foreground` | `False` | Run in the foreground (no `-d`). |
| | `--json` | `False` | Machine-readable output. |
| `compose down` | `--file` / `-f` | `agents.yaml` | Agents file (for project directory resolution). |
| | `--stack-dir` | *(resolved)* | Override the compose stack template directory. |
| | `--volumes` / `-v` | `False` | Also remove the named `postgres_data` volume. |
| | `--json` | `False` | Machine-readable output. |

Both commands wrap `docker compose` with a **600 s** timeout so first-run image pulls complete without hanging on an unresponsive Docker daemon.

***

## Environment Variables

The generated `.env` drives both services. Defaults come from the stack's `docker-compose.yml`.

| Variable | Default | Description |
| - | - | - |
| `AGENTS_FILE` | `./agents.yaml` | Agents file mounted into the API container. |
| `API_PORT` | `8005` | Host port for the API. |
| `POSTGRES_BIND` | `127.0.0.1` | Host interface Postgres binds to. Loopback by default. |
| `POSTGRES_PORT` | `5432` | Host port for Postgres. |
| `POSTGRES_USER` | `praisonai` | Database user. |
| `POSTGRES_DB` | `praisonai` | Database name. |
| `POSTGRES_PASSWORD` | *(required)* | Compose fails fast if unset; CLI auto-generates one on first run. |
| `PRAISONAI_IMAGE` | `ghcr.io/mervinpraison/praisonai:latest` | API image (pin a tag for production). |
| `OPENAI_API_KEY` | *(empty)* | LLM provider key. |
| `ANTHROPIC_API_KEY` | *(empty)* | LLM provider key. |
| `GOOGLE_API_KEY` | *(empty)* | LLM provider key. |
| `PRAISONAI_API_TOKEN` | *(empty)* | Bearer token clients send to the API. |
| `PRAISONAI_API_AUTH` | `enabled` | Toggle API bearer-token auth. |
| `DATABASE_URL` | *(auto)* | Composed from the Postgres variables above. |

***

## Security

The stack ships secure-by-default; three safeguards matter most.

<AccordionGroup>
  <Accordion title="POSTGRES_PASSWORD is required — no repo default">
    The shipped stack has **no default password**, so Postgres never starts with a repo-known credential. Compose uses the `:?` operator and fails fast if it is unset. On the first `compose up`, the CLI writes a strong `secrets.token_urlsafe(24)` value into `.praisonai-compose/.env`.
  </Accordion>

  <Accordion title="Postgres binds to loopback by default">
    `POSTGRES_BIND` defaults to `127.0.0.1`, so the database is not reachable on all host interfaces. Set it explicitly (e.g. `POSTGRES_BIND=0.0.0.0`) only when you intend to expose it.
  </Accordion>

  <Accordion title="The generated .env is chmod 0600">
    Because `.env` holds the database password and API token, the CLI restricts it to owner read/write on POSIX systems.
  </Accordion>
</AccordionGroup>

***

## Path Resolution & Overrides

The CLI finds the stack automatically in a checkout, with explicit overrides.

| Override | Purpose |
| - | - |
| `--stack-dir` | Point at a directory containing `docker-compose.yml`. |
| `PRAISONAI_COMPOSE_STACK` | Env override for the stack directory. |
| `PRAISONAI_INFRA_ROOT` | Env override for the whole `infra/` tree. |

<Note>
  As a one-release compatibility fallback, the CLI still resolves a legacy `deploy/` layout **in your own checkout** — it walks up from the working directory looking for `deploy/helm`, `deploy/compose`, or `deploy/starters`. A fresh PraisonAI clone ships **no** root `deploy/` folder, so this path stays inactive unless you created that layout yourself. Prefer the new `praisonai deploy compose` commands.
</Note>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Pin PRAISONAI_IMAGE in production">
    The default image tag is `latest`, which drifts. Pin a released tag in `.env` for reproducible deployments.
  </Accordion>

  <Accordion title="Keep auth enabled when exposing the API">
    Leave `PRAISONAI_API_AUTH=enabled` and set `PRAISONAI_API_TOKEN`. Clients then send `Authorization: Bearer <token>`.
  </Accordion>

  <Accordion title="Use --volumes only when you mean it">
    `compose down -v` drops the `postgres_data` volume and all stored data. Omit `-v` to keep the database between runs.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Deploy Templates" icon="file-code" href="/docs/docs/features/create-templates">
    Scaffold this stack and cloud projects.
  </Card>

  <Card title="Helm Chart — Agents API" icon="ship" href="/docs/docs/features/helm-chart-agents-api">
    The Kubernetes equivalent of this stack.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.