README.md

---
title: Slack Bot ChromaDB
emoji: 🧠
colorFrom: blue
colorTo: green
sdk: docker
app_port: 8000
pinned: false
license: mit
---

# ChromaDB for Slack Deno Bot

Hosts [ChromaDB 1.5.9](https://github.com/chroma-core/chroma) for the Slack knowledge-base bot.  
Public API: `GET /api/v2/heartbeat`

---

## Hugging Face setup (exact steps)

### 1. Create the Space

1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
2. **Space name:** e.g. `slack-bot-chroma` (becomes `YOUR_USERNAME-slack-bot-chroma.hf.space`)
3. **License:** MIT (or your choice)
4. **SDK:** **Docker** (not Gradio)
5. **Hardware:** CPU basic (free) is enough for demos; use persistent storage for production data
6. Click **Create Space**

### 2. Upload these two files to the Space repo

Copy from this folder in the bot repo:

| File | Purpose |
|------|---------|
| `Dockerfile` | Chroma 1.5.9 (listens on **8000** by default) |
| `README.md` | This file (`app_port: 8000` tells HF which port to probe) |

**Option A — Git (recommended)**

```bash
# Install HF CLI once: pip install huggingface_hub
huggingface-cli login

git clone https://huggingface.co/spaces/YOUR_USERNAME/slack-bot-chroma
cd slack-bot-chroma

# From your slack_deno_bot repo:
cp /path/to/slack_deno_bot/chromadb_server/huggingface/Dockerfile .
cp /path/to/slack_deno_bot/chromadb_server/huggingface/README.md .

git add Dockerfile README.md
git commit -m "Deploy ChromaDB 1.5.9 for Slack bot"
git push
```

**Option B — Web UI**

1. Open your Space → **Files** tab
2. **Add file** → upload `Dockerfile` and `README.md` (delete the auto-generated ones first if needed)
3. Space rebuilds automatically

### 3. Wait for the build

1. Open the Space → **Logs** tab
2. Wait until you see the container running (no build errors)
3. First boot can take 2–5 minutes on free tier

### 4. Enable persistent storage (recommended)

Without this, **data is lost** when the Space restarts or sleeps.

1. Space → **Settings** → **Persistent storage**
2. Turn **on** and pick a size (e.g. 5 GB for demos)
3. Data is stored at `/data` inside the container (Chroma default)

### 5. Verify the Space is live

Replace with your Space URL:

```bash
curl -sS https://YOUR_USERNAME-slack-bot-chroma.hf.space/api/v2/heartbeat
```

Expected: JSON response with `"nanosecond heartbeat"` (or similar), not an HTML error page.

**Cold start:** Free Spaces sleep after ~48h idle. The first request may take 30–60s while the Space wakes up.

### 6. Point the Slack bot project at Hugging Face

In your local `slack_deno_bot/.env`:

```env
CHROMA_URL=https://YOUR_USERNAME-slack-bot-chroma.hf.space
CHROMA_COLLECTION=company_knowledge
GEMINI_API_KEY=your_key
```

Test from the bot repo:

```bash
deno task chroma:ping
deno task chroma:ingest -- knowledge_base_docs/example.md
deno task chroma:search -- "your test question"
```

### 7. Configure the **deployed** Slack app

Local `.env` is **not** used by `slack deploy`. Set prod env on the deployed app:

```bash
# Manifest outgoing domain (use your real hostname)
echo 'CHROMA_DEPLOY_URL=https://YOUR_USERNAME-slack-bot-chroma.hf.space' >> .env

slack env set CHROMA_URL "https://YOUR_USERNAME-slack-bot-chroma.hf.space" -a YOUR_DEPLOYED_APP_ID
slack deploy -a YOUR_DEPLOYED_APP_ID
```

### 8. Ingest documents into hosted Chroma

Run ingest **from your laptop** (embeddings use your `GEMINI_API_KEY`; vectors are sent to HF Chroma):

```bash
deno task chroma:ingest -- ./knowledge_base_docs -r
```

Re-run after adding or updating docs.

---

## Space URL format

| Space name | Public API base URL |
|------------|---------------------|
| `slack-bot-chroma` | `https://YOUR_USERNAME-slack-bot-chroma.hf.space` |

Always use **HTTPS**, no port suffix (HF terminates TLS on 443).

---

## Security notes

- **Public Space:** Anyone with the URL can call the Chroma API. Fine for internal demos; use a **private** HF Space or org access for production.
- **Do not** commit `GEMINI_API_KEY` or Slack secrets to the Space repo — only the Dockerfile and README belong there.
- Embeddings are computed locally/on Slack infra; HF only stores vectors and document text.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Space stuck on "Building" / slow start | Chroma runs on **8000** — README must have `app_port: 8000`, not `7860` |
| Build fails | Check Logs; ensure `sdk: docker` and `app_port: 8000` are in README YAML |
| `502` / Space sleeping | Open the Space URL in a browser, wait, retry `chroma:ping` |
| Slack deploy `domain_blocked` | Set `CHROMA_DEPLOY_URL` in `.env` before `slack deploy` |
| Empty KB answers | Run `chroma:ingest` against the HF URL; confirm collection `company_knowledge` |
| Data gone after restart | Enable **Persistent storage** in Space settings |