Build a Private Chat Workspace with LibreChat

What you will build

A disposable LibreChat workspace with persistent conversations and a local Ollama backend on its private Docker network. The browser is accessible only through host loopback. This avoids making a host's loopback-only Ollama service reachable from containers by accident.

This is a fresh-install reference exercise. Do not replace an existing deployment's Compose files or environment. Allow 1-2 hours plus image and model downloads; no hosted API subscription is needed for this local path.

Before you start

Use Docker Engine, Git, and Docker Compose 2.24.4 or newer, which supports the !override syntax below. Reserve an unused local port 3080 and enough memory for both the application stack and model. Sixteen GB is a sensible starting point for a small model, not a universal requirement.

docker version
docker compose version
git --version

Select a LibreChat release or reviewed commit from its official release history. Record the commit and image IDs; this guide does not certify an unpinned future release.

1. Create an independent workspace

In a new parent directory you control:

git clone https://github.com/LibreChat-AI/LibreChat.git librechat-lab
cd librechat-lab
cp .env.example .env
git rev-parse HEAD

Edit .env using the selected release's template. Set its required JWT and credential-encryption secrets to independently generated random values. Generate a value with openssl rand -hex 32; do not use a published example secret. Some settings require a specific byte length, so follow the environment template exactly.

Keep .env private and out of Git. Registration can remain enabled only while creating the initial local account; disable it afterward if no additional accounts are wanted.

2. Configure a local model service

In this fresh checkout, create docker-compose.override.yml:

services:
  api:
    ports: !override
      - "127.0.0.1:3080:3080"
    volumes:
      - ./librechat.yaml:/app/librechat.yaml:ro
  guide-ollama:
    image: ollama/ollama:latest
    volumes:
      - guide-models:/root/.ollama
    expose:
      - "11434"
volumes:
  guide-models:

This CPU-capable example publishes no Ollama port. GPU support requires the appropriate container runtime and device configuration; add it only after verifying the CPU path. Models downloaded here are separate from models installed on the host.

Create librechat.yaml using the schema version supported by your checkout. The following minimal example uses a commonly supported schema; validate it against that release's example file:

version: 1.2.1
cache: true
endpoints:
  custom:
    - name: "Local Ollama"
      apiKey: "ollama"
      baseURL: "http://guide-ollama:11434/v1"
      models:
        default: ["llama3.2:3b"]
        fetch: false
      titleConvo: true
      titleModel: "llama3.2:3b"

The API-key value is a compatibility placeholder for this isolated unauthenticated Ollama service, not a security credential.

3. Start and inspect

docker compose config --quiet
docker compose up -d
docker compose exec guide-ollama ollama pull llama3.2:3b
docker compose ps
docker compose logs --tail=100 api

Inspect the actual published ports. If the selected release publishes database or search-management ports, remove those unnecessary publications in its configuration before proceeding. Do not assume a private service just because the web port is loopback-bound.

Record pulled image digests and pin them before treating this as a maintained deployment. latest here is a bootstrap choice, not an upgrade policy.

4. Verify the user journey

Open http://127.0.0.1:3080, create the initial account, choose Local Ollama, and send a harmless test prompt. On a remote host, use an SSH tunnel rather than broadening the bind address.

Save a conversation, restart the API with docker compose restart api, and verify that login and history still work. If file uploads are enabled, upload a harmless text file and check it remains accessible after restart.

Disable public registration in .env according to the installed release, recreate the API, and verify an anonymous browser cannot create another account. The UI wording and first-admin behavior vary across releases.

When it breaks

If the model endpoint fails, test the container service name and check whether both services share the intended Compose network. localhost:11434 inside LibreChat is not the guide-ollama container. Invalid YAML and wrong schema versions appear in startup logs. Distinguish a missing model from an unavailable backend.

Back up and stop safely

Do the backup and restore exercise before storing important content. docker compose stop stops this lab without deleting its data. Never use down -v unless you deliberately intend to remove its named volumes.

Explore theLAB