Configuration Reference

All configuration lives in a single .env file at the project root. Copy it from .env.example, fill in your secrets, and restart the stack. This page documents every variable.

Generate strong secrets. The bundled installer fills these in for you. If you set them by hand, use a random source:

openssl rand -hex 32   # DJANGO_SECRET_KEY
openssl rand -hex 24   # RAG_API_KEY / WHISPER_API_KEY

Bootstrap an `.env`

cp .env.example .env
# Edit .env — set DJANGO_SECRET_KEY, POSTGRES_PASSWORD,
# RAG_API_KEY, WHISPER_API_KEY at minimum.
docker compose up -d

Never commit .env to version control.

Database (PostgreSQL)

PostgreSQL stores users, chats, documents, and settings. Runs in the bundled postgres:16-alpine container.

Variable	Default	Purpose
`POSTGRES_USER`	`localai`	Database username. Match the one in `DATABASE_URL`.
`POSTGRES_PASSWORD`	`localai_dev`	Replace this with a strong password before exposing the host.
`POSTGRES_DB`	`localai`	Database name. Match the one in `DATABASE_URL`.
`DATABASE_URL`	`postgresql://localai:localai_dev@postgres:5432/localai`	Connection string Django uses. Keep host as `postgres` (Docker service name).

Django (REST API)

Variable	Default	Purpose
`DJANGO_SECRET_KEY`	`change-me-in-production`	Cryptographic key used to sign sessions, JWTs, password reset tokens. Must be unique per install.
`DJANGO_DEBUG`	`true`	Set `false` for production. Disables verbose errors and the debug toolbar.
`CORS_ALLOWED_ORIGINS`	`http://localhost:3000,http://127.0.0.1:3000`	Comma-separated browser origins permitted to call the API. Add your real frontend URL if not localhost.
`BACKEND_URL`	`http://django:8000`	How Next.js reaches Django inside the Docker network. Change only if running Next.js outside Docker.

RAG service (document chat)

FastAPI service that indexes uploaded files and answers questions over them. Reached from Django and the frontend with a shared API key.

Variable	Default	Purpose
`RAG_API_KEY`	`dev-rag-key-change-me`	Shared secret. The same value must appear in Django, Next.js, and the RAG container.
`RAG_SERVICE_URL`	`http://rag:8080`	Internal URL Django uses to reach the RAG FastAPI endpoint. Service-name only (Docker DNS).
`RAG_URL`	`http://rag:8080`	Same target as `RAG_SERVICE_URL`, but read by the Next.js build.

Ollama (LLM inference)

Ollama serves chat and embedding models. Two ways to wire it up: bundled container (default) or your existing host install.

Variable	Default	Purpose
`OLLAMA_BASE_URL`	`http://ollama:11434`	Where RAG and Django send model requests. Service-name URL by default.
`OLLAMA_HOST`	`http://ollama:11434`	Override to point at an external Ollama instance.
`COMPOSE_PROFILES`	`container-ollama`	Profile that enables the bundled Ollama service. Clear it to use host Ollama only.

Use host Ollama instead of the container

If you already run Ollama on your Mac / Linux host, point the stack at it and skip the bundled container:

OLLAMA_HOST=http://host.docker.internal:11434
COMPOSE_PROFILES=

On Linux, replace host.docker.internal with your host LAN IP or use --add-host in compose.

Whisper (speech-to-text)

Offline transcription via faster-whisper. The container caches its models in a named volume.

Variable	Default	Purpose
`WHISPER_API_KEY`	`change-me-in-production`	Shared secret between Django and the Whisper container.
`WHISPER_SERVICE_URL`	`http://whisper:8090`	Internal URL Django uses to reach Whisper.
`WHISPER_MODEL`	`base`	Model size: `tiny` · `base` · `small` (multilingual), or add `.en` for English-only and faster CPU inference.

Sizing guide: base ≈ 140 MB on disk, ~1–2 s for a 10 s clip on Apple Silicon CPU. tiny is faster but loses accuracy on noisy audio.

Docker images (release builds)

Used by docker-compose.release.yml when pulling pre-built images instead of building locally.

Variable	Default	Purpose
`LOCAL_AI_IMAGE_PREFIX`	`rizwanhameed360s`	Docker Hub / GHCR namespace where pre-built images live.
`LOCAL_AI_IMAGE_TAG`	`1.0.3`	Pinned image tag for the app services (backend, frontend, rag, updater).
`LOCAL_AI_STABLE_TAG`	`1.0.3`	Tag for the heavier images (Ollama, Whisper) that change less often. Falls back to `LOCAL_AI_IMAGE_TAG` if unset.

Updater service

Small sidecar that drives "Check for Updates" inside the app. Talks to the host Docker socket so it can pull and restart containers.

Variable	Default	Purpose
`UPDATER_SERVICE_URL`	`http://updater:8070`	Internal URL Django uses to proxy update requests.
`UPDATER_API_KEY`	`change-me-in-production`	Shared secret. Replace.

Ports exposed on the host

Defined in docker-compose.yml. Change the host side (left of the colon) to free a port.

Port	Service	Purpose
`80`	Caddy	Reverse proxy → Next.js + Django API by hostname.
`5433`	PostgreSQL	External access to the DB (mapped to container `5432`).
`11434`	Ollama	Ollama API — useful for tools like `ollama list` from the host.
`8501`	RAG (Streamlit)	Optional standalone document-chat UI.

Change the main app port

If port 80 is taken, remap Caddy. Edit docker-compose.yml:

services:
  caddy:
    ports:
      - "8080:80"   # host:container

Then visit http://local-ai.localhost:8080.

Example `.env`

A minimal production-ish file with placeholder secrets:

# PostgreSQL
POSTGRES_USER=localai
POSTGRES_PASSWORD=<strong-password>
POSTGRES_DB=localai

# Django
DATABASE_URL=postgresql://localai:<strong-password>@postgres:5432/localai
DJANGO_SECRET_KEY=<openssl rand -hex 32>
DJANGO_DEBUG=false
CORS_ALLOWED_ORIGINS=http://local-ai.localhost,http://api.local-ai.localhost

# RAG
RAG_API_KEY=<openssl rand -hex 24>
RAG_SERVICE_URL=http://rag:8080
RAG_URL=http://rag:8080

# Ollama (bundled)
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_HOST=http://ollama:11434
COMPOSE_PROFILES=container-ollama

# Whisper
WHISPER_API_KEY=<openssl rand -hex 24>
WHISPER_SERVICE_URL=http://whisper:8090
WHISPER_MODEL=base

# Pre-built images
LOCAL_AI_IMAGE_PREFIX=rizwanhameed360s
LOCAL_AI_IMAGE_TAG=1.0.3
LOCAL_AI_STABLE_TAG=1.0.3

# Updater
UPDATER_SERVICE_URL=http://updater:8070
UPDATER_API_KEY=<openssl rand -hex 24>

Rotating secrets

To replace a leaked or default secret:

Edit the value in .env.
Restart the affected service: docker compose up -d --force-recreate <service>.
For DJANGO_SECRET_KEY: restart django; existing sessions and password-reset tokens are invalidated.
For RAG_API_KEY / WHISPER_API_KEY: restart django, nextjs, and the target service together.

Never store secrets in committed files. If you've accidentally pushed a secret, rotate the value and force the affected service to restart immediately.

Configuration Reference

Bootstrap an .env

Database (PostgreSQL)

Django (REST API)

RAG service (document chat)

Ollama (LLM inference)

Use host Ollama instead of the container

Whisper (speech-to-text)

Docker images (release builds)

Updater service

Ports exposed on the host

Change the main app port

Example .env

Rotating secrets

Bootstrap an `.env`

Example `.env`