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

# Prerequisites

> Install Python and Docker; choose Ollama, OpenAI, or Cohere for text embeddings.

## Summary

| Requirement | Required? | Why |
| - | - | - |
| [Python 3.10+](#python) | **Yes** | Installs `moorcheh-client` (CLI + SDK) |
| [Docker Engine](#docker) | **Yes** | Runs the Moorcheh server container via `moorcheh up` |
| [Docker Desktop](#docker-desktop-vs-docker-engine) | **No** (but common) | One way to get Docker on Windows/macOS — not the only option |
| [Embedding provider](#embedding-provider) | **Yes for text workflows** | Embeds documents and text search queries |
| [Ollama](#ollama-optional) | **Only if provider is Ollama** | Local embeddings; host app or bundled container |
| [OpenAI / Cohere API key](#cloud-embedding-providers) | **Only if provider is OpenAI or Cohere** | Cloud embeddings; no Ollama needed |

**Vector-only workflows** (precomputed vectors, no text upload/search) do not need any embedding provider or Ollama.

## How install and startup work

```bash theme={null}
pip install moorcheh-client
moorcheh configure    # optional; first moorcheh up can do this interactively
moorcheh up
```

| Step | What it does | What it does **not** do |
| - | - | - |
| **`pip install moorcheh-client`** | Installs the `moorcheh` CLI, `MoorchehClient` SDK, and bundled `docker-compose.yml` | Does not start Docker or configure embeddings |
| **`moorcheh configure`** | Saves embedding + LLM provider, model, and API keys to `~/.moorcheh/config.json` | Does not start or restart containers |
| **`moorcheh up`** | Starts Docker stack per provider; for Ollama, may start bundled Ollama and pull the model | Does not apply config changes to an already-running container — use `moorcheh down` then `moorcheh up` after reconfigure |

If `~/.moorcheh/data` already has namespaces, changing **embedding** settings can break existing text search until you re-upload. The configure wizard warns when data is present.

On first `moorcheh up`, Docker **pulls** `moorcheh/server:latest` (if not cached). The image is published for **`linux/amd64`** and **`linux/arm64`**, so Docker Desktop on **Apple Silicon Macs** runs natively without emulation. **Ollama** (`ollama/ollama:latest`) is pulled only when your config uses provider **ollama** and host Ollama is not already running.

<Note>
  You do **not** need to build Moorcheh from source or run `docker compose` manually.
</Note>

***

## Python

**Version:** Python **3.10 or newer**

```bash theme={null}
python --version
pip install moorcheh-client
```

***

## Docker

Moorcheh on-prem runs the **API server in Docker**. `moorcheh up` runs compose and mounts **`~/.moorcheh/data`** (index) and **`~/.moorcheh/uploads`** → `/uploads` (read-only, for file upload).

| Component | Required |
| - | - |
| **Docker CLI** + **Compose V2** (`docker compose`) | Yes |
| **Running daemon** (`docker info` succeeds) | Yes |

Default ports:

| Port | Service |
| - | - |
| **8080** | Moorcheh API |
| **11434** | Ollama (only when using Ollama provider and bundled/host Ollama) |

```bash theme={null}
moorcheh up --server-port 8081
```

**Network:** Pull `moorcheh/server` from Docker Hub. The image supports **Intel and Apple Silicon Macs**, Windows, and Linux (`linux/amd64` and `linux/arm64`). Cloud providers also need **outbound HTTPS** from the server container to OpenAI or Cohere.

### Docker Desktop vs Docker Engine

| Platform | Typical setup |
| - | - |
| **macOS** | [Docker Desktop](https://www.docker.com/products/docker-desktop/) (recommended) |
| **Windows** | Docker Desktop or Docker Engine with WSL2 |
| **Linux** | Docker Engine + Compose plugin |

You only need a running Docker daemon (`docker info` succeeds). Docker Desktop is the most common way to get that on macOS and Windows, but it is not required on Linux.

***

## Embedding provider

Pick one provider for **all text** namespaces on this instance. Full model list and dimensions: [Embedding providers](/on-prem/guides/embedding-providers).

| Provider | You need | Moorcheh starts |
| - | - | - |
| **Ollama** | Nothing extra, or [host Ollama](#ollama-optional) | Server; optionally `moorcheh-ollama` + auto model pull |
| **OpenAI** | API key | Server only |
| **Cohere** | API key | Server only |

```bash theme={null}
moorcheh configure
# or
moorcheh up   # interactive wizard if config.json is missing
```

***

## Ollama (optional)

Required **only** when `provider` is `ollama` in `~/.moorcheh/config.json`.

Ollama is used for:

* Uploading documents to **text** namespaces
* **File upload** chunk embedding (same provider as text upload)
* **Text** semantic search (query strings)

### Host vs bundled

```mermaid theme={null}
flowchart TD
  A[moorcheh up + provider ollama] --> B{"Ollama on 127.0.0.1:11434?"}
  B -->|Yes| C[Server only → host.docker.internal]
  B -->|No| D[Start moorcheh-ollama + server]
  D --> E[Auto-pull configured embedding model]
```

| Mode | Command |
| - | - |
| **Auto (default)** | `moorcheh up` |
| **Force bundled** | `moorcheh up --bundled-ollama` |
| **Host only** | `moorcheh up --use-host-ollama` |

### Option A — Host Ollama

1. Install from [ollama.com](https://ollama.com/download)
2. `moorcheh configure` → choose **ollama** and a model
3. `moorcheh up` — reuses host Ollama; pulls model if missing

### Option B — Bundled Ollama (no host install)

If host Ollama is not running, `moorcheh up` starts **`moorcheh-ollama`** and pulls your configured model (for example `nomic-embed-text`).

### Vector-only

If you **only** use **vector** namespaces:

* No Ollama, OpenAI, or Cohere setup required
* `moorcheh up` starts **only** the server when config uses a cloud provider
* If config still says `ollama`, switch with `moorcheh configure --force` or use OpenAI/Cohere

***

## Cloud embedding providers

### OpenAI

* API key from [platform.openai.com](https://platform.openai.com/)
* Set during `moorcheh configure` or `moorcheh up --embedding-provider openai --embedding-api-key ...`
* Default base URL: `https://api.openai.com/v1` (overridable in `config.json`)

### Cohere

* API key from [dashboard.cohere.com](https://dashboard.cohere.com/)
* Default base URL: `https://api.cohere.com/v2`

***

## Checklist before Quickstart

```bash theme={null}
python --version          # 3.10+
docker info
docker compose version
pip install moorcheh-client
moorcheh configure        # or rely on moorcheh up wizard
moorcheh up
moorcheh status
```

Expected: `"status": "ok"`, `"embedding_provider"`, and `"model"` matching your config.

***

## Troubleshooting

| Symptom | Likely cause | What to try |
| - | - | - |
| `docker compose` fails on `up` | Port in use, pull failed | Check `8080`; `docker pull moorcheh/server:latest` |
| Text upload fails (Ollama) | Model not pulled / Ollama down | `moorcheh up` again or `ollama pull <model>` |
| Text upload fails (OpenAI/Cohere) | Invalid or missing API key | `moorcheh configure --force` |
| Bundled Ollama never needed | Wrong provider in config | `moorcheh configure` → openai or cohere |

***

## Next steps

* [Quickstart](/on-prem/quickstart)
* [Embedding providers](/on-prem/guides/embedding-providers)
* [moorcheh configure](/on-prem/cli/runtime/configure)
* [moorcheh up](/on-prem/cli/runtime/up)


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