Weaviate

Weaviate 1.38 vector database — semantic and hybrid search over objects, with vectors you bring from your own embedding model. Runs as a single node, or as a multi-node cluster when you add replicas. Secured with an API key and reachable only over your private network by default.

Configuration

services:
  vectors:
    package: weaviate

That's a complete single-node setup — the API key is auto-generated on the first managed apply and reused forever after. To pin your own key (for example from an environment variable):

services:
  vectors:
    package: weaviate
    config:
      api_key: "${WEAVIATE_API_KEY}"

To run a cluster, add replicas:

services:
  vectors:
    package: weaviate
    replicas: 2   # 3 nodes total: the first node + 2 joining nodes

Parameters

Parameter	Required	Default	Description
api_key	Yes	auto-generated	The key clients send as a Bearer token; it maps to the built-in admin user
replicas	No	0	Additional cluster nodes beyond the first
version	No	1.38.6	Weaviate release to install. The default installs checksum-verified; other versions download unverified
bind_public	No	false	Listen on all interfaces instead of the private/overlay IP. A footgun — only enable if you know the ports are firewalled
keep_daily_backups	No	5	Number of daily backups to retain
keep_weekly_backups	No	1	Number of weekly backups to retain
keep_monthly_backups	No	1	Number of monthly backups to retain

Bring your own vectors

The package runs Weaviate with no built-in vectorizer (vectorizer: none): your application computes embeddings (OpenAI, Cohere, a local model, …) and sends them with each object, which is the standard self-hosted setup. Weaviate's API-based generative/vectorizer modules remain available if a collection opts into them; nothing runs models on the server itself.

Connection

Weaviate serves REST and GraphQL on 8080 and gRPC on 50051, bound to the private/overlay address so only your other servers can reach it. Every request carries the API key as a Bearer token:

curl -H "Authorization: Bearer $WEAVIATE_API_KEY" http://<private-ip>:8080/v1/schema

The official client libraries take the same key:

import weaviate
client = weaviate.connect_to_custom(
    http_host="<private-ip>", http_port=8080, http_secure=False,
    grpc_host="<private-ip>", grpc_port=50051, grpc_secure=False,
    auth_credentials=weaviate.auth.AuthApiKey("..."),
)

The auto-generated key is stored with your project's state and shown (masked) in the dashboard's Configuration panel for the service.

Clustering

Set replicas and managed apply grows the service into a multi-node cluster:

• The first node (cluster name node1) is the founding member. Its configuration never changes when nodes join, so scale-ups don't restart it.
• Each new node installs Weaviate, then joins the cluster by gossiping with the first node over the private/overlay network. Every node keeps a stable, unique cluster identity (its managed server name) — Weaviate recognizes its own data by that name.
• All nodes serve the full API on 8080/50051 with the same API key.

Spreading data across nodes

Where your data lives is decided per collection, when you create it. A collection created with defaults keeps its data on one node. To replicate:

curl -X POST -H "Authorization: Bearer $WEAVIATE_API_KEY" -H "Content-Type: application/json" \
  -d '{"class": "Documents", "vectorizer": "none", "replicationConfig": {"factor": 2}}' \
  http://<any-node>:8080/v1/schema

factor: 2 keeps two copies of every shard, so the collection stays readable and writable (with tunable consistency — ONE, QUORUM, ALL per request) when a node is down. Weaviate also shards large collections across nodes automatically via its sharding config.

Checking the cluster

managed service vectors check-cluster

Shows every member, its health and version, and how many nodes the cluster has versus how many it should have. The dashboard also charts a Healthy cluster nodes gauge.

Cluster limitations

• Schema changes go through the first node. The cluster uses single-voter consensus for metadata: creating or changing collections requires node1 to be up. Reading and writing data keeps working on the other nodes (subject to your collections' replication factor and the consistency level you request).
• Backups are single-node only. In cluster mode the daily backup skips (one node's files are not a complete backup) and restore refuses to run. Use replicationConfig factor 2+ for redundancy.
• A cluster needs the private/overlay network — nodes must be able to reach each other. managed apply sets this up automatically when the servers support it.

Backups

On a single node, a full backup runs every 24 hours: Weaviate is paused for a moment while its data directory is streamed to object storage as a compressed archive — a byte-exact, consistent copy — then started again. Retention follows the daily/weekly/monthly scheme (see the parameters above).

managed service vectors backup            # take a backup now (brief pause)
managed service vectors backup-list       # list what's in storage
managed service vectors restore --arg confirm=yes

Restore replaces everything in Weaviate with the backup contents — it previews what it will do and requires the confirm=yes argument. If the download fails mid-restore, the original data is put back untouched.

Commands

Command	Description
managed service <name> status	Server status, version, and collection list
managed service <name> check-cluster	Cluster membership and node health
managed service <name> backup	Back up now (single-node only; brief pause)
managed service <name> backup-list	List available backups in storage
managed service <name> restore	Restore from the latest (or specified) backup

Ports

Port	Protocol	Open to	Purpose
8080	tcp	private networks	REST + GraphQL API
50051	tcp	private networks	gRPC API
7946	tcp + udp	this service's nodes only	Cluster membership (gossip)
7947	tcp	this service's nodes only	Data replication between nodes
8300, 8301	tcp	this service's nodes only	Schema consensus (raft)

How it works

The service installs the official Weaviate binary from GitHub releases — checksum-verified against the upstream's published digests for the default version — and runs it under systemd as the unprivileged weaviate user. All configuration is environment variables in a root-only file, which also carries the API key — never on a command line or in a world-readable config. Anonymous access is disabled, authentication and the admin authorization list are on, and telemetry is off.

Where the data lives

Weaviate keeps everything in /var/lib/weaviate on the server. managed installs onto whatever disk layout the server already has — on OVH bare metal, set up Storage & RAID before the first apply.