Port: WEAVIATE_PORT (REST, default 63030) / WEAVIATE_GRPC_PORT (gRPC, default 63031) SOURCE variable: WEAVIATE_SOURCE SOURCE options: container, localhost, disabled

Vector database used for semantic search, RAG, embeddings, n8n workflows, Backend features, and notebooks. It is enabled by default (WEAVIATE_SOURCE=container), together with the multi2vec-clip image vectorizer.

Anonymous access is on, so only the Kong origin may call Weaviate from a browser: CORS_ALLOW_ORIGIN=http://weaviate.localhost:${KONG_HTTP_PORT}. Server-side clients are unaffected.

See the canonical port table at Ports and Routes.

WEAVIATE_SOURCE=container          # container | localhost | disabled
WEAVIATE_LOCALHOST_PORT=8080       # host port when WEAVIATE_SOURCE=localhost
# WEAVIATE_URL is auto-managed: http://weaviate:8080, http://host.docker.internal:<port>, or empty

Scripted changes: ./start.sh --weaviate-source <value> and --multi2vec-clip-source <value>.

Text vectorization goes through the always-on LiteLLM gateway via the text2vec-openai module. Weaviate receives only OPENAI_APIKEY, set to LITELLM_MASTER_KEY. Whoever creates a collection (the Backend or a consumer) sets the LiteLLM base URL in moduleConfig.text2vec-openai.baseURL. Without it, text2vec-openai calls api.openai.com.

Weaviate uses whatever embedding model LiteLLM serves: Ollama nomic-embed-text by default, or a cloud model. No separate text2vec-ollama wiring is needed. The default vectorizer is none. Each collection must name its vectorizer and baseURL, or supply its own vectors. Otherwise a text2vec-openai default would send the master key to api.openai.com. To add embedding models, see LiteLLM Gateway.

The default stack keeps the multimodal CLIP vectorizer enabled:

MULTI2VEC_CLIP_SOURCE=container-cpu
WEAVIATE_ENABLE_MODULES=text2vec-openai,text2vec-ollama,multi2vec-clip,generative-openai,generative-ollama,backup-filesystem
CLIP_INFERENCE_API=http://multi2vec-clip:8080
MULTI2VEC_CLIP_SIGLIP2_IMAGE=semitechnologies/multi2vec-clip:google-siglip2-so400m-patch16-512-1.5.1

With MULTI2VEC_CLIP_SOURCE=disabled the bootstrapper drops multi2vec-clip from WEAVIATE_ENABLE_MODULES and blanks CLIP_INFERENCE_API itself; the resulting values are:

MULTI2VEC_CLIP_SOURCE=disabled
WEAVIATE_ENABLE_MODULES=text2vec-openai,text2vec-ollama,generative-openai,generative-ollama,backup-filesystem
CLIP_INFERENCE_API=

SigLIP 2 is opt-in. The default ViT-B/32 image emits 512-d vectors; MULTI2VEC_CLIP_SIGLIP2_IMAGE emits 1152-d vectors. Do not change MULTI2VEC_CLIP_IMAGE for existing collections until you recreate or revectorize them. Keep CLIP_INFERENCE_API=http://multi2vec-clip:8080. The SigLIP 2 image is much larger than the default. MULTI2VEC_CLIP_SOURCE=container-gpu currently requests no GPU device (open issue #1373), so it runs on CPU.

In container mode, collections persist in the ${PROJECT_NAME}-weaviate-data volume. Native snapshots from the backup-filesystem module go to the ${PROJECT_NAME}-weaviate-backups volume at /var/lib/weaviate/backups. ./stop.sh --cold removes both volumes.

The backup service owns backup and restore. services/backup/run-consistent-backup.sh takes a native snapshot while Weaviate stays online. services/backup/run-database-restore.sh restores Neo4j and Weaviate together into fresh volumes, validates them, then replaces the live data. It requires BACKUP_RESTORE_MAINTENANCE_MODE=confirmed and stopped writers. The backup README has the full procedure. In localhost mode, use the host installation's own backup tools.

Consumers are listed in §7.2. Open WebUI is not wired to Weaviate.

Optional consumers should read WEAVIATE_URL and check readiness at the feature level instead of declaring a hard Compose dependency. JupyterHub, the Backend and n8n still start when Weaviate is disabled or host-run.

Support tier: experimental — Capability contract declared; no cited cold-start, workflow, or upgrade qualification run yet (evidence at v0.1.0).

Run the docker compose commands from the repository root. Add -p "$PROJECT_NAME" if the checkout directory name differs from PROJECT_NAME.

# Check the three containers: weaviate-init must exit 0 before weaviate starts
docker compose ps -a weaviate-init weaviate multi2vec-clip
docker compose logs weaviate-init weaviate

# Readiness from the host (container mode)
curl -fsS http://localhost:${WEAVIATE_PORT}/v1/.well-known/ready

• Vectorization calls api.openai.com or fails with an OpenAI auth error — the collection has no moduleConfig.text2vec-openai.baseURL. Recreate it with the LiteLLM base URL (§3.1).
• multi2vec-clip vectors have the wrong dimension — the CLIP image changed under an existing collection. Recreate or revectorize the collection (§3.2).

For general startup and routing issues, see Troubleshooting.

Open the full-size diagram for a full-screen view.

• weaviate ↔ doc-processor — The Backend ingestion engine already supports Docling extraction, shared chunking, LiteLLM embeddings and explicit-vector Weaviate writes (vectorizer=none). Use POST /api/rag/ingestions with a consumer profile for that path. Remaining: ship an n8n example for a Document collection vectorized by text2vec-openai through LiteLLM. Mechanism: read Docling JSON, chunk it, then POST /v1/batch/objects. Effort: medium. Confidence: high.
• weaviate ↔ n8n — Why: n8n already receives WEAVIATE_URL. No shipped example workflow uses n8n's Weaviate node to ingest webhook payloads, search, and feed retrieval into the AI Agent nodes. Mechanism: seed an example workflow driving the n8n Weaviate node → http://weaviate:8080 (REST) or gRPC on :50051. Effort: small. Confidence: high.
• weaviate ↔ hermes — Why: Hermes has no long-term memory or retrieval tool. A Weaviate-backed memory skill lets Hermes recall past sessions, store tool outputs, and do semantic lookup over user docs. Mechanism: Hermes custom skill posts/queries via the Weaviate Python client to http://weaviate:8080 with hybrid search; collection seeded by weaviate-init. Effort: medium. Confidence: medium.
• weaviate ↔ comfyui — Why: ComfyUI generates images but they're write-only artifacts on disk. CLIP-vectorizing them into Weaviate enables similarity search over the user's own generation history ("more like this"). Mechanism: ComfyUI custom node or n8n post-execution hook → POST /v1/objects to a Generation collection vectorized by multi2vec-clip (already enabled). Effort: medium. Confidence: medium.

No high-confidence opportunities identified.

• backup-s3 module — Why pursue: the current single-node filesystem module is exported by the backup runner; direct S3 backup would support a future multi-node Weaviate deployment. Effort: small.
• Named vectors (vectorConfig array) — Why pursue: one collection could carry both a text2vec-openai vector and a multi2vec-clip vector, for hybrid text+image search without two collections. Effort: medium.
• Reranker modules (reranker-transformers or reranker-cohere) — Why pursue: cheap quality lift on RAG queries; the transformers variant runs in-cluster with no extra API costs. Effort: medium.
• Multi-tenancy (per-collection tenant shards) — Why pursue: backend/n8n/Hermes could share one Weaviate cluster with per-user isolation instead of single-tenant anonymous access. Effort: medium.
• Generative modules beyond OpenAI/Ollama — Why pursue: LiteLLM already fronts Anthropic/Cohere; matching Weaviate's generative module list (generative-anthropic, generative-cohere) widens GraphQL-side RAG options. Effort: small.