Published

LibreChat

Self-hosted multi-user chat interface for commercial and open language-model APIs (OpenAI, Anthropic, Google and compatible endpoints), with agents, conversation search and file search. Fits a team that wants one shared chat app with its own accounts and history while the models stay with the providers.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Up to 10 users, up to 100 stored messages a day (prompts + replies), up to 0.1 GB of documents uploaded for file search; one year of history.	3 vCPU · 4.25 GiB RAM · 15.494 GiB disk	3.72 vCPU · 6.6 GiB RAM · 27.594 GiB disk
MediumEstimate	Up to 50 users, up to 500 stored messages a day (prompts + replies), up to 0.5 GB of documents uploaded for file search; one year of history.	4.5 vCPU · 6.25 GiB RAM · 21.432 GiB disk	5.52 vCPU · 9 GiB RAM · 34.422 GiB disk
HeavyEstimate	Up to 200 users, up to 2,000 stored messages a day (prompts + replies), up to 2 GB of documents uploaded for file search; one year of history.	8 vCPU · 14.75 GiB RAM · 88.695 GiB disk	9.72 vCPU · 19.2 GiB RAM · 111.775 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
LibreChat (API and web client) (app)	1 / 1 / 4.126	1.5 / 2 / 4.499	2 / 4 / 5.896	[16][18][19][21][25]
MongoDB (database)	0.25 / 0.75 / 1.319	0.5 / 1 / 1.863	1 / 2 / 3.902	[25][27][30]
Meilisearch (other)	0.25 / 0.5 / 1.501	0.5 / 0.75 / 6.522	1 / 2.75 / 25.349	[8][25][31][32]
PostgreSQL with pgvector (database)	1 / 1 / 6.5	1 / 1 / 6.5	2 / 4 / 51.5	[2][10][33][34][35][39][40][41][42][43][44][45]
rag_api (lite) (worker)	0.5 / 1 / 2.048	1 / 1.5 / 2.048	2 / 2 / 2.048	[10][25][35][36][38]

How the estimates are worked out

LibreChat (API and web client) · Light: vCPU and RAM: the documented minimum (1 vCPU, 1 GiB) taken for the LibreChat container alone; the docs suggest 2 GB with everything enabled, which the other containers cover. Disk: image 3.533 GiB (0.921 compressed + 2.612 unpacked) + uploads 0.1 GB = 0.093 GiB + 0.5 GiB for log files (daily rotation, 20 MB per file, 14 days) = 4.126.
LibreChat (API and web client) · Medium: RAM: 2 × the documented 1 GiB minimum for more responses streaming at once (assumption). vCPU: a single Node.js process (npm run backend) keeps its event loop on one core; +0.5 for garbage collection and file handling. Disk: image 3.533 GiB + uploads 0.5 GB = 0.466 GiB + 0.5 GiB logs = 4.499.
LibreChat (API and web client) · Heavy: RAM: 4 × the documented 1 GiB minimum for many concurrent streams (assumption). vCPU: one Node.js process uses one core for its event loop; a second covers garbage collection, file parsing and libuv threads. More users need more LibreChat instances, not more cores. Disk: image 3.533 GiB + uploads 2 GB = 1.863 GiB + 0.5 GiB logs = 5.896.
MongoDB · Light: Data: 100 messages × 365 days × 4 KB (assumed size of a stored message with metadata and indexes) = 146 MB = 0.136 GiB a year. RAM: WiredTiger's minimum cache 256 MB (0.238 GiB), larger than half the year's data, + 0.5 GiB for mongod, connections and file cache = 0.738, rounded up to 0.75. vCPU: about 0.001 writes a second on average. Disk: image 1.183 GiB (0.291 + 0.891) + 0.136 = 1.319.
MongoDB · Medium: Data: 500 × 365 × 4 KB = 730 MB = 0.68 GiB a year. RAM: cache for half the year's data, 0.34 GiB (above the 256 MB minimum), + 0.5 GiB = 0.84, rounded up to 1. vCPU: 0.5, still well under one write a second on average. Disk: image 1.183 GiB + 0.68 = 1.863.
MongoDB · Heavy: Data: 2,000 × 365 × 4 KB = 2.92 GB = 2.719 GiB a year. RAM: cache for half the year's data, 1.36 GiB, + 0.5 GiB = 1.86, rounded up to 2. vCPU: 1 for indexes and the search sync reads. Disk: image 1.183 GiB + 2.719 = 3.902.
Meilisearch · Light: Index: 100 messages × 365 × 1.5 KB of text (assumption) = 0.051 GiB raw × 24.6 (the docs' 9.1 MB → 224 MB disk measurement) = 1.255 GiB. RAM: 1/10 of the index (docs: often enough) = 0.126, raised to 0.5 since the docs measured ~305 MB for a 224 MB index. Disk: image 0.246 GiB (0.099 + 0.147) + 1.255 = 1.501.
Meilisearch · Medium: Index: 500 × 365 × 1.5 KB = 0.255 GiB raw × 24.6 = 6.276 GiB. RAM: 1/10 of the index = 0.628, rounded up to 0.75. Disk: image 0.246 GiB + 6.276 = 6.522.
Meilisearch · Heavy: Index: 2,000 × 365 × 1.5 KB = 1.02 GiB raw × 24.6 = 25.103 GiB. RAM: 1/10 of the index = 2.51, rounded up to 2.75. Disk: image 0.246 GiB + 25.103 = 25.349.
PostgreSQL with pgvector · Light: Vectors: 0.1 GB of text / 1,400 new chars per chunk (CHUNK_SIZE 1500 − overlap 100) = 71,429 chunks × ~8.2 KB (1536 × 4 + 8 B vector + 1.5 KB text + metadata) = 0.58 GB, inside the light envelope. pgvector/pgvector:0.8.0-pg15-trixie is 152 MiB compressed, within the 0.5 GiB image allowance. Embedded metadata DB with the image's default config: equals the PostgreSQL profile's light preset (≤ 5 GB data, ≤ 20 concurrent connections) at every load level. Light preset method: shared_buffers 25% of RAM, worst-case work_mem/maintenance_work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL with pgvector · Medium: Vectors: 0.5 GB of text / 1,400 chars = 357,143 chunks × ~8.2 KB = 2.91 GB, inside the light envelope (≤ 5 GB). Embedded metadata DB with the image's default config: equals the PostgreSQL profile's light preset (≤ 5 GB data, ≤ 20 concurrent connections) at every load level. Light preset method: shared_buffers 25% of RAM, worst-case work_mem/maintenance_work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL with pgvector · Heavy: Vectors: 2 GB of text / 1,400 chars = 1,428,571 chunks × ~8.2 KB = 11.65 GB, above the light envelope, so the PostgreSQL medium figures (≤ 50 GB) apply. RAM: 4 × light; shared_buffers 1 GiB = 25% (docs guidance); the other 3 GiB covers worst-case 100 connections × work_mem 4 MB × hash_mem_multiplier 2 (800 MB) plus 4 × maintenance_work_mem 64 MB. vCPU: 2 active backend processes, or a leader plus one parallel worker. Disk: 0.5 GiB image (155 MiB compressed × 3, rounded up) + 50 GiB data + 1 GiB WAL (max_wal_size default); GB taken as GiB.
rag_api (lite) · Light: RAM: one upload in flight holds at most 500 × (3 + 2) = 2,500 chunks (README formula, defaults); each is a 1536-float Python list (~49 KB) + 1.5 KB text ≈ 0.12 GiB, + ~0.5 GiB for the Python process (assumption) = 0.62, rounded up to 1. vCPU: embeddings are computed remotely; parsing one file at a time. Disk: image 2.048 GiB (0.503 + 1.546); uploads are deleted after embedding.
rag_api (lite) · Medium: RAM: two uploads in flight, 2 × 0.12 GiB + 0.5 GiB = 0.74, rounded up to 1.5 toward the README's 2 GB line below which smaller batches are advised. vCPU: one core for parsing two files at once. Disk: image 2.048 GiB.
rag_api (lite) · Heavy: RAM: four uploads in flight, 4 × 0.12 GiB + 0.5 GiB = 0.98, rounded up to 2, the README's line for keeping the default batch size. vCPU: 2 threads parsing files at once (the thread pool follows the CPU count, capped at 8). Disk: image 2.048 GiB.

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
LibreChat (API and web client)	3080/tcp	Public, through a proxy	Web client and API (HTTP), published behind a reverse proxy	[2][6][19]
MongoDB	27017/tcp	Internal only	MongoDB used by LibreChat (MONGO_URI)	[2][12]
Meilisearch	7700/tcp	Internal only	Meilisearch API for conversation search; never published	[8][14]
PostgreSQL with pgvector	5432/tcp	Internal only	PostgreSQL with pgvector, used only by rag_api	[2][10]
rag_api (lite)	8000/tcp	Internal only	rag_api file indexing and retrieval (RAG_API_URL), called by LibreChat	[2][9][10]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
LibreChat (API and web client)Derived	1000:1000	`node`	No	`/app/data/app/uploads/app/client/public/images/app/logs`	[16][19][26]
MongoDB	999:999	`mongodb`	Yes, prepares its directories, then drops to this user	`/data/db/data/configdb`	[28][29]
MeilisearchDerived	0:0	`root`	No	`/meili_data`	[14][32]
PostgreSQL with pgvectorDerived	999:999	`postgres`	Yes, prepares its directories, then drops to this user	`/var/lib/postgresql/data/var/run/postgresql`	[15][44]
rag_api (lite)Derived	0:0	`root`	No	`/app/uploads`	[10][37][38]

LibreChat (API and web client): The image runs USER node (uid/gid 1000 in the Node.js base image) with no step-down. The Dockerfile creates /app/data (mode 1777), /app/uploads, /app/client/public/images and /app/logs as node, so named volumes there start writable; logs stay in the container.
Meilisearch: The Dockerfile sets no USER, so tini and meilisearch run as root (uid 0) without a step-down; the database is written under the working directory /meili_data.
PostgreSQL with pgvector: pgvector/pgvector is built FROM the official postgres image, whose entrypoint starts as root, fixes ownership of PGDATA (/var/lib/postgresql/data in PostgreSQL 15) and drops to postgres (uid/gid 999).
rag_api (lite): Dockerfile.lite sets no USER, so python main.py runs as root (uid 0). Uploaded files are written temporarily to RAG_UPLOAD_DIR (./uploads under /app) and removed after embedding; no volume is needed.

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
LibreChat (API and web client)Assumption	0.008	0.039	0.156	[2]
MongoDBAssumption	0.011	0.057	0.227	[27]
MeilisearchAssumption	0.105	0.523	2.092	[31]

What the growth figures rest on

LibreChat (API and web client): The preset's uploads (0.093 GiB) arriving over 12 months; generated images and avatars are small next to them.
LibreChat (API and web client): The preset's uploads (0.466 GiB) arriving over 12 months; generated images and avatars are small next to them.
LibreChat (API and web client): The preset's uploads (1.863 GiB) arriving over 12 months; generated images and avatars are small next to them.
MongoDB: Upstream gives no growth rate. The preset's year of messages (0.136 GiB at an assumed 4 KB a message) spread over 12 months; LibreChat keeps conversations until users delete them.
MongoDB: Upstream gives no growth rate. The preset's year of messages (0.68 GiB at an assumed 4 KB a message) spread over 12 months; LibreChat keeps conversations until users delete them.
MongoDB: Upstream gives no growth rate. The preset's year of messages (2.719 GiB at an assumed 4 KB a message) spread over 12 months; LibreChat keeps conversations until users delete them.
Meilisearch: The preset's year of index (1.255 GiB) spread over 12 months. LMDB does not give space back after deletions, so the volume only grows.
Meilisearch: The preset's year of index (6.276 GiB) spread over 12 months. LMDB does not give space back after deletions, so the volume only grows.
Meilisearch: The preset's year of index (25.103 GiB) spread over 12 months. LMDB does not give space back after deletions, so the volume only grows.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Back up MongoDB (a mongodump or the stopped mongodb-data volume) and the LibreChat data, uploads and images volumes before every update; the v0.8.8 index migration itself asks for a MongoDB backup first. [2][22]

Upgrade steps

Read the release notes and UPGRADING.md of every version between yours and the target for migrations and changed defaults. [22][23]
Set the new pinned tag registry.librechat.ai/librechat-ai/librechat:vX.Y.Z (and the matching rag_api tag) in the Compose file, then run docker compose pull and docker compose up -d. Volumes are kept. [17]DerivedThe docs update the official checkout with git pull and docker compose pull; with pinned tags the same pull and restart follows from raising the tag.
From v0.8.7 or earlier to v0.8.8: stop the librechat service, keep MongoDB running and run docker compose run --rm --no-deps -w /app librechat npm run migrate:tenant-indexes (dry run first), then start it again. [22]
Keep JWT_SECRET, JWT_REFRESH_SECRET, CREDS_KEY and CREDS_IV unchanged; new values sign users out and leave stored user keys unreadable. [4]
When raising the Meilisearch tag, start it with an empty meili-data volume and run npm run reset-meili-sync in the librechat container so LibreChat reindexes from MongoDB. [8]

Roll back

Pin the previous image tags and run docker compose up -d. If the new version changed indexes or data (such as the tenant index migration), restore the MongoDB backup taken before the update. [22]DerivedLibreChat documents no downgrade path; this follows from pinned tags and the MongoDB backup UPGRADING.md asks for.

Known breaking changes

In 0.8.8: Databases from v0.8.7 or earlier can log Index build failed until the tenant index migration (npm run migrate:tenant-indexes) is run; startup does not run it. [22][23]
In 0.8.8: Startup is refused when JWT_SECRET or JWT_REFRESH_SECRET is a retired published default, or when CREDS_KEY / CREDS_IV are not exactly 64 / 32 hex characters; .env.example no longer ships sample credentials. [4][5][23]
In 0.8.8: The first search sync after upgrading reindexes existing conversations and messages, with temporarily higher MongoDB and Meilisearch load on large installations. [8]

Limits

No local models: every chat goes to an external provider API (OpenAI, Anthropic, Google, or OpenAI-compatible endpoints set in librechat.yaml, which this file does not mount). Token costs are billed by the providers, and data leaves the server. [3][17]
File search needs an embeddings key: the lite rag_api image only calls remote embeddings (OpenAI by default), so uploads to file search fail until RAG_OPENAI_API_KEY holds a real key. [9][10]
MongoDB 8 needs a CPU with AVX instructions; it crashes on start on CPUs or virtual machines without AVX. [17]
The Meilisearch index never shrinks (LMDB keeps freed space) and its size cannot be predicted exactly; the figures here use the docs' single measurement. On a shared server MongoDB also sizes its cache from total host RAM unless --wiredTigerCacheSizeGB is set. [27][31]

Security

The first account registered becomes the admin, and email sign-up is open by default. Create your account right after the first start, then set ALLOW_REGISTRATION to false. [4][17]
CREDS_KEY and CREDS_IV encrypt the API keys users save; changing them does not re-encrypt existing records. Keep them and the JWT secrets in your secret store and never reuse sample values. [4][5]
Keep Meilisearch (7700), MongoDB (27017), PostgreSQL (5432) and rag_api (8000) on the internal network; only port 3080 goes behind the HTTPS reverse proxy. [2][8][11]

Backup

Back up MongoDB (users, conversations, agents, stored keys), the LibreChat data, uploads and images volumes, and the secrets in .env together: encrypted keys cannot be read without the matching CREDS_KEY and CREDS_IV. [2][4][22]
The Meilisearch volume can be rebuilt from MongoDB with npm run reset-meili-sync and needs no backup; the pgvector volume holds the file-search embeddings, which are lost without a pg_dump and then need the files uploaded again. [8][9]