victor HF Staff commited on
Commit
96fb92b
·
1 Parent(s): 008e1e3

Update README with simplified MongoDB setup instructions

Browse files

Streamlines the setup steps by clarifying that MongoDB configuration is optional for local development, as Chat UI now falls back to an embedded MongoDB if MONGODB_URL is not set. Updates Docker instructions and removes redundant details about MongoDB setup, making the guide easier to follow for new users.

Files changed (1) hide show
  1. README.md +9 -11
README.md CHANGED
@@ -26,8 +26,6 @@ Chat UI speaks to OpenAI-compatible APIs only. The fastest way to get running is
26
  ```env
27
  OPENAI_BASE_URL=https://router.huggingface.co/v1
28
  OPENAI_API_KEY=hf_************************
29
- # Fill in once you pick a database option below
30
- MONGODB_URL=
31
  ```
32
 
33
  `OPENAI_API_KEY` can come from any OpenAI-compatible endpoint you plan to call. Pick the combo that matches your setup and drop the values into `.env.local`:
@@ -42,9 +40,7 @@ MONGODB_URL=
42
 
43
  Check the root [`.env` template](./.env) for the full list of optional variables you can override.
44
 
45
- **Step 2 – Choose where MongoDB lives:** Either provision a managed cluster (for example MongoDB Atlas) or run a local container. Both approaches are described in [Database Options](#database-options). After you have the URI, drop it into `MONGODB_URL` (and, if desired, set `MONGODB_DB_NAME`).
46
-
47
- **Step 3 – Install and launch the dev server:**
48
 
49
  ```bash
50
  git clone https://github.com/huggingface/chat-ui
@@ -59,6 +55,9 @@ You now have Chat UI running locally. Open the browser and start chatting.
59
 
60
  Chat history, users, settings, files, and stats all live in MongoDB. You can point Chat UI at any MongoDB 6/7 deployment.
61
 
 
 
 
62
  ### MongoDB Atlas (managed)
63
 
64
  1. Create a free cluster at [mongodb.com](https://www.mongodb.com/pricing).
@@ -70,13 +69,13 @@ Atlas keeps MongoDB off your laptop, which is ideal for teams or cloud deploymen
70
 
71
  ### Local MongoDB (container)
72
 
73
- If you prefer to run MongoDB locally:
74
 
75
  ```bash
76
  docker run -d -p 27017:27017 --name mongo-chatui mongo:latest
77
  ```
78
 
79
- Then set `MONGODB_URL=mongodb://localhost:27017` in `.env.local`. You can also supply `MONGO_STORAGE_PATH` if you want Chat UI’s fallback in-memory server to persist under a specific folder.
80
 
81
  ## Launch
82
 
@@ -91,19 +90,18 @@ The dev server listens on `http://localhost:5173` by default. Use `npm run build
91
 
92
  ## Optional Docker Image
93
 
94
- Prefer containerized setup? You can run everything in one container as long as you supply a MongoDB URI (local or hosted):
95
 
96
  ```bash
97
  docker run \
98
  -p 3000:3000 \
99
- -e MONGODB_URL=mongodb://host.docker.internal:27017 \
100
  -e OPENAI_BASE_URL=https://router.huggingface.co/v1 \
101
  -e OPENAI_API_KEY=hf_*** \
102
- -v db:/data \
103
  ghcr.io/huggingface/chat-ui-db:latest
104
  ```
105
 
106
- `host.docker.internal` lets the container reach a MongoDB instance on your host machine; swap it for your Atlas URI if you use the hosted option. All environment variables accepted in `.env.local` can be provided as `-e` flags.
107
 
108
  ## Extra parameters
109
 
 
26
  ```env
27
  OPENAI_BASE_URL=https://router.huggingface.co/v1
28
  OPENAI_API_KEY=hf_************************
 
 
29
  ```
30
 
31
  `OPENAI_API_KEY` can come from any OpenAI-compatible endpoint you plan to call. Pick the combo that matches your setup and drop the values into `.env.local`:
 
40
 
41
  Check the root [`.env` template](./.env) for the full list of optional variables you can override.
42
 
43
+ **Step 2 – Install and launch the dev server:**
 
 
44
 
45
  ```bash
46
  git clone https://github.com/huggingface/chat-ui
 
55
 
56
  Chat history, users, settings, files, and stats all live in MongoDB. You can point Chat UI at any MongoDB 6/7 deployment.
57
 
58
+ > [!TIP]
59
+ > For quick local development, you can skip this section. When `MONGODB_URL` is not set, Chat UI falls back to an embedded MongoDB that persists to `./db`.
60
+
61
  ### MongoDB Atlas (managed)
62
 
63
  1. Create a free cluster at [mongodb.com](https://www.mongodb.com/pricing).
 
69
 
70
  ### Local MongoDB (container)
71
 
72
+ If you prefer to run MongoDB in a container:
73
 
74
  ```bash
75
  docker run -d -p 27017:27017 --name mongo-chatui mongo:latest
76
  ```
77
 
78
+ Then set `MONGODB_URL=mongodb://localhost:27017` in `.env.local`.
79
 
80
  ## Launch
81
 
 
90
 
91
  ## Optional Docker Image
92
 
93
+ The `chat-ui-db` image bundles MongoDB inside the container:
94
 
95
  ```bash
96
  docker run \
97
  -p 3000:3000 \
 
98
  -e OPENAI_BASE_URL=https://router.huggingface.co/v1 \
99
  -e OPENAI_API_KEY=hf_*** \
100
+ -v chat-ui-data:/data \
101
  ghcr.io/huggingface/chat-ui-db:latest
102
  ```
103
 
104
+ All environment variables accepted in `.env.local` can be provided as `-e` flags.
105
 
106
  ## Extra parameters
107