Hosting Weaviate on a VPS

Why self-host Weaviate on a VPS

What Weaviate brings in practice

• Built-in vectorization — with a text2vec-* module, you insert raw text and Weaviate computes the vector itself.
• Native hybrid search — a hybrid query combines the vector score and BM25, weighted by the alpha parameter.
• RAG inside the database — generative-* modules send the retrieved objects to an LLM and return the answer along with the sources.
• Multi-tenancy — one isolated shard per customer within the same collection, ideal for a SaaS that separates each account's data.
• Named vectors — several vectors per object (title, content, image), each with its own vectorizer and its own index.
• Index compression — PQ, BQ or SQ quantization to cut the memory used by vectors.
• BSD-3-Clause licence — auditable code you can deploy without depending on a managed service.

Sized requirements for a Weaviate VPS

Which vectorizer to choose

Scroll the table

Deploying Weaviate step by step

1. 01

   Prepare the VPS and DNS

   Check Docker with docker compose version. Create a DNS A record for vectors.example.com pointing to the VPS IP, then a /opt/weaviate directory that will hold the docker-compose.yml.

2. 02

   Write the weaviate service

   Declare the semitechnologies/weaviate:1.27.2 image (also published on cr.weaviate.io). Publish the ports locally only: 127.0.0.1:8080:8080 and 127.0.0.1:50051:50051. Docker bypasses ufw rules for published ports, so an 8080:8080 mapping would remain reachable from the Internet even with the firewall on. Mount a named volume on /var/lib/weaviate and add restart: unless-stopped.

3. 03

   Set the base variables

   PERSISTENCE_DATA_PATH=/var/lib/weaviate for persistence, QUERY_DEFAULTS_LIMIT=25 for the default number of results, CLUSTER_HOSTNAME=node1 for a stable node name: if it changes between restarts, the node no longer finds its state. Add DEFAULT_VECTORIZER_MODULE=none or the module of your choice, and ENABLE_API_BASED_MODULES=true to enable the modules that call an API (text2vec-openai, text2vec-ollama, generative-openai…).

4. 04

   Enable API key authentication

   Set AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=false, then AUTHENTICATION_APIKEY_ENABLED=true, AUTHENTICATION_APIKEY_ALLOWED_KEYS=admin-key,read-key and AUTHENTICATION_APIKEY_USERS=admin,app-reader: keys and users are matched in order. Generate the keys with openssl rand -hex 32. To restrict the second key to reads, add AUTHORIZATION_ADMINLIST_ENABLED=true, AUTHORIZATION_ADMINLIST_USERS=admin and AUTHORIZATION_ADMINLIST_READONLY_USERS=app-reader.

5. 05

   Start and check

   Run docker compose up -d, then curl -s localhost:8080/v1/.well-known/ready, which answers 200 once the node is ready. curl -s -H "Authorization: Bearer $KEY" localhost:8080/v1/meta returns the version and the list of loaded modules: it is the first check to run when a vectorizer seems to be missing.

6. 06

   Put Nginx and TLS in front of port 8080

   Configure an Nginx server for vectors.example.com with proxy_pass http://127.0.0.1:8080;, issue the certificate with certbot --nginx -d vectors.example.com and raise client_max_body_size if you import batches over REST. The Authorization header is passed through to Weaviate unchanged.

7. 07

   Connect with the Python client v4

   Install pip install -U weaviate-client. On the VPS: client = weaviate.connect_to_local(port=8080, grpc_port=50051, auth_credentials=Auth.api_key(KEY)), with from weaviate.classes.init import Auth. From another server, use weaviate.connect_to_custom(...) and specify host, port and TLS for both HTTP and gRPC. Check with client.is_ready() and finish with client.close().

8. 08

   Create a collection and import

   client.collections.create("Article", ...) with its properties and vectorizer, then articles = client.collections.get("Article"). Import in batches inside a with articles.batch.dynamic() as batch: block by calling batch.add_object(properties={...}), and add vector=[...] if the vectorizer is none. Then check articles.batch.failed_objects to spot rejected objects.

9. 09

   Connect the rest of the AI stack

   For fully local embeddings and generation, install Ollama on the same VPS and point text2vec-ollama and generative-ollama at its API. Open WebUI or your RAG application then query Weaviate as their document memory.

Data modelling: collections, multi-tenancy and named vectors

Querying Weaviate: the useful queries

• Semantic search — articles.query.near_text(query="contract termination", limit=5) requires a vectorizer; otherwise use near_vector with your own embedding.
• Hybrid search — articles.query.hybrid(query="duplicate invoice", alpha=0.5): alpha=1 gives a purely vector search, alpha=0 a purely BM25 search.
• Keywords only — articles.query.bm25(query="GDPR") uses the inverted index, useful for references, product codes and proper names.
• Filters — filters=Filter.by_property("language").equal("en"), imported from weaviate.classes.query, combines with all of the queries above.
• Built-in RAG — articles.generate.near_text(query=..., limit=3, grouped_task="Answer using these excerpts") returns the objects and the answer from the configured LLM.
• GraphQL — the /v1/graphql endpoint remains available for tools that use it, with the nearText, hybrid and bm25 operators.

HNSW, flat or dynamic index and memory sizing

Backups and upgrades

Monitoring Weaviate

Troubleshooting: the most common errors

• 401 response on every request — anonymous access is disabled and the request does not send Authorization: Bearer <key>, or the key is not listed in AUTHENTICATION_APIKEY_ALLOWED_KEYS.
• The Python client v4 refuses to connect — it also checks gRPC: port 50051 must be reachable from the client, locally or through an SSH tunnel, and grpc_port must match.
• Module not found when creating a collection — the module is not loaded: check ENABLE_MODULES, ENABLE_API_BASED_MODULES and the list returned by /v1/meta.
• Container restarting with exit code 137 — the kernel killed it for lack of memory: set GOMEMLIMIT, enable quantization or add RAM to the VPS.
• Imports rejected in read-only mode — the disk crossed DISK_USE_READONLY_PERCENTAGE: free some space or grow the volume, then set the shards back to writable.
• Vectorization errors at import — the provider API key is missing (X-OpenAI-Api-Key passed in the client headers) or the Ollama server cannot be reached from the Weaviate container.

Weaviate, Qdrant, pgvector or Milvus

Scroll the table

When Weaviate is the right choice