Skip to content
Learni
View all tutorials
Bases de données vectorielles

How to Deploy Weaviate in Production with Docker in 2026

22 minEXPERT
DockerWeaviateVector Database
Lire en français

Introduction

Weaviate is an open-source vector database designed for semantic search and AI applications. In 2026, its adoption for RAG systems and hybrid search requires mastering production deployments. This tutorial guides you step by step through configuring a scalable cluster, managing modules, and optimizing performance. You'll learn to avoid common pitfalls while building a robust and maintainable solution.

Prerequisites

  • Docker and Docker Compose v2.20+
  • Python 3.11+ with Pydantic knowledge
  • OpenAI account or API key for embeddings
  • Advanced understanding of vector embeddings and JSON schemas

Docker Compose Configuration

docker-compose.yml
version: '3.8'
services:
  weaviate:
    image: semitechnologies/weaviate:1.26.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      ENABLE_MODULES: 'text2vec-openai,generative-openai,qna-openai'
      CLUSTER_HOSTNAME: 'node1'
    volumes:
      - weaviate_data:/var/lib/weaviate
volumes:
  weaviate_data:

This file defines a Weaviate deployment with OpenAI modules enabled. Environment variables activate authentication and persistence. Adjust the hostname for multi-node clusters.

Starting the Container

terminal
docker compose up -d
sleep 10
curl http://localhost:8080/v1/meta

Starts the container in the background and verifies that the Weaviate API responds. The sleep command allows time for the service to fully initialize.

Python Client and Connection

connect.py
import weaviate
from weaviate.classes.init import Auth

client = weaviate.connect_to_local(
    host="localhost",
    port=8080,
    grpc_port=50051,
)
print(client.is_ready())
client.close()

Connects using the official Python client with gRPC support. Always verify is_ready() before any operations and close the connection properly.

Creating the Article Schema

schema.py
from weaviate.classes.config import Configure, Property, DataType

client.collections.create(
    name="Article",
    vectorizer_config=Configure.Vectorizer.text2vec_openai(
        model="text-embedding-3-small"
    ),
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="content", data_type=DataType.TEXT),
        Property(name="url", data_type=DataType.TEXT, skip_vectorization=True)
    ]
)

Creates a collection with automatic vectorization via OpenAI. The url field is excluded from vectorization to optimize costs.

Data Ingestion

ingest.py
import json

with client.batch.dynamic() as batch:
    for item in json.load(open("articles.json")):
        batch.add_object(
            collection="Article",
            properties=item,
        )
print("Ingestion terminée")

Uses dynamic batching to efficiently ingest large volumes. Avoid individual calls in production environments.

Advanced Hybrid Query

query.py
from weaviate.classes.query import HybridFusion

response = client.collections.get("Article").query.hybrid(
    query="intelligence artificielle",
    alpha=0.75,
    fusion_type=HybridFusion.RELATIVE_SCORE,
    limit=10,
    return_properties=["title", "url"]
)
for obj in response.objects:
    print(obj.properties)

Hybrid query combining vector search and BM25. The alpha parameter controls the balance between the two approaches.

Best Practices

  • Always enable persistence and configure regular backups
  • Use consistent embedding models between ingestion and search
  • Monitor memory and CPU via Prometheus metrics
  • Limit object size and use references for relationships
  • Version schemas and test migrations in a staging environment

Common Errors to Avoid

  • Forgetting to enable required modules in docker-compose
  • Ingesting without batching on large datasets
  • Using vector queries without prior indexing
  • Neglecting gRPC timeout configuration in production

Going Further

Explore replication modules and geospatial filters. Discover our Learni training on vector databases.