Which Weaviate deployment model fits your team
For a prototype or a developer's laptop, embedded Weaviate is the fastest route, but it is labeled experimental software whose APIs and parameters may change, and it stops when the client process exits. Use it to test schemas and queries, not to host data that other people depend on. Pin the version explicitly, because the Python client's pinned default may lag several minor releases behind. Embedded mode is supported on Linux and macOS, so confirm your target platform against the Embedded Weaviate documentation before you build around it.
For a single-host service, Docker Compose is the documented option that stays close to a conventional server. It suits a team that wants a long-running Weaviate process with its own data path, API keys and RBAC, and does not yet need orchestration. Its main advantage matters only when you run more than one host: the Compose guide builds multi-node clusters by configuring one founding node and setting CLUSTER_JOIN on the others, with CLUSTER_HOSTNAME recommended because hostname changes are known to cause issues. Replication is disabled by default and is enabled per collection with a replication factor, so a second node adds nothing to durability until you configure it. Anonymous access is strongly discouraged outside development, so turn on API key or OIDC authentication before any shared use.
For a production cluster that needs scheduled rollouts, failover and standard operational tooling, the Weaviate Helm chart on Kubernetes is the better fit, but only if your team already runs Kubernetes. The guide requires Kubernetes 1.23 or later, Helm v3 and PersistentVolumeClaims with ReadWriteOnce storage, and it cites chart version 17.8.3. Its default configuration defines one Weaviate replica, so high availability is a deliberate change you must make and test. You also inherit the cluster's own duties, including etcd backups and Secret encryption at rest, which are not optional if you go this route. Confirm the chart version and replica settings against the Weaviate Kubernetes installation guide before you commit.
How the three documented options differ in practice
Embedded Weaviate starts a Weaviate instance from application code instead of a stand-alone server. The Python client includes it for Weaviate v1.23.7 or later, and TypeScript users install the separate weaviate-ts-embedded package. The process lifecycle is tied to your application: Weaviate stops when the client process exits, while data stays in the data path you configure. The mode is labeled experimental, and its APIs and parameters may change, so the docs recommend pinning the Weaviate version explicitly.
- Startup: the database starts and stops with the application process, with no separate service to run.
- Data location: data persists in the configured data path on the host running the application.
- Platforms: supported on Linux and macOS only.
- Multi-node: not a fit for this mode, since it runs as a single instance inside one process.
- Best fit: prototypes, notebooks, local tests and single-user tools where a separate server adds no value.
Before relying on embedded mode, confirm with the Weaviate documentation how the version pin is set in your client and whether the experimental status matters for your change control.
Docker Compose runs Weaviate as a container service on one host or across several hosts. The Compose guide builds a multi-node cluster by configuring one founding node and setting CLUSTER_JOIN on the others, so new nodes know where to join. Weaviate recommends setting CLUSTER_HOSTNAME explicitly because changing hostnames is known to cause problems, and each node needs its own gossip and data bind ports. Your team owns the host operating system, container runtime, storage, backups and any load balancing in front of the nodes.
- Startup: containers are started with Compose on each host, and the founding node comes up first.
- Data location: each node stores data on its host through a bind mount or volume you define.
- Multi-node: set CLUSTER_JOIN on non-founding nodes and a stable CLUSTER_HOSTNAME on every node.
- Ports: assign separate gossip and data bind ports per node and keep them stable across restarts.
- Best fit: teams with a small number of hosts, a Docker skill set and no existing Kubernetes platform.
Ask your Weaviate contact or review the Docker guide to confirm the exact replication settings for your collections, since replication is disabled by default and must be enabled per collection.
The Weaviate Helm chart deploys Weaviate onto an existing Kubernetes cluster. The Kubernetes guide requires Kubernetes 1.23 or later, Helm v3, and PersistentVolumeClaims using ReadWriteOnce storage, and it cites Helm chart version 17.8.3. The default configuration defines one Weaviate replica, so a multi-replica deployment needs deliberate values changes and replication configuration. Your platform team takes on cluster upgrades, node pools, storage classes, secrets handling and backups.
- Startup: Helm installs the chart into a namespace, and Kubernetes schedules the pods.
- Data location: each replica binds to a PersistentVolumeClaim, so storage class and volume behavior matter.
- Requirements: Kubernetes 1.23 or later, Helm v3 and ReadWriteOnce-capable storage.
- Multi-replica: the default is one replica, so scaling out needs explicit configuration and replication settings.
- Best fit: organizations already running Kubernetes with platform staff who manage upgrades, storage and access control.
Confirm your cluster's current minor version against the Kubernetes release schedule, and ask whether your storage class and backup tooling support the chart's volume layout.
Side-by-side: embedded, Compose and Helm on Kubernetes
This table compares the three documented ways to run self-hosted Weaviate across maturity, placement, multi-node setup, storage, authentication, upgrades, skills and operating surface. Read each row as a question to answer for your environment, not a ranking. The main takeaway is that embedded mode is experimental and suited to development, while Compose and Helm both move the operating burden onto your team.
| Row | Embedded Weaviate | Docker Compose | Helm chart on Kubernetes |
|---|---|---|---|
| Maturity and stability | Labeled experimental; APIs and parameters may change, so pin the version explicitly | Documented installation path; confirm the image tag you pin against the releases page | Documented installation path; the guide cites Helm chart version 17.8.3, so confirm the current chart version |
| Where the instance runs | Inside the application process, started from Python or TypeScript code, on Linux or macOS | On one or several hosts you manage with Docker | On a Kubernetes cluster you run, requiring version 1.23 or later |
| Multi-node support | Not a multi-node deployment model | Multi-node clusters built by configuring one founding node and setting CLUSTER_JOIN on the others | Default configuration defines one replica; confirm the replica count and replication settings you need |
| Storage and persistence | Keeps data in its data path, but stops when the client process exits | Persistence depends on the volumes and bind mounts you configure on each host | Uses PersistentVolumeClaims with ReadWriteOnce storage; confirm your storage class supports it |
| Authentication options | Confirm which auth settings apply in embedded mode before relying on them | API key, OIDC and RBAC are available; anonymous access is strongly discouraged outside development | API key, OIDC and RBAC are available; anonymous access is strongly discouraged outside development |
| Upgrade path | Upgrade by changing the pinned client and server version in application code and testing | Change the image tag and restart nodes in a planned order; test cluster joins after each change | Helm v3 chart upgrades, plus Kubernetes minor version upgrades on your own schedule; confirm the chart and Weaviate version pairing |
| Required skills | Application development; no separate server administration | Docker administration, networking, bind ports and backups | Kubernetes administration, Helm, storage classes, RBAC and secrets handling |
| Operating surface added | Minimal: the application owns the database lifecycle | Hosts, container runtime, volumes, gossip and data ports, and backup jobs | Cluster, control plane and etcd health, PVCs, ingress, Secrets encryption and Pod Security settings |
What runs in each topology
Weaviate can run inside an application process, on one Compose host, across several Compose hosts, or on a Kubernetes cluster. Each option moves more operational work onto your team, and the cards below set out what each layer adds and what to check before you commit.
Embedded process inside the client
Embedded Weaviate starts a Weaviate instance from application code instead of a standalone server, and it stops when the client process exits while keeping data in its data path. The docs label it experimental, with APIs and parameters that may change, and support is limited to Linux and macOS. For a prototype, pin the version explicitly, since the Python client's default can lag several minor releases behind. Do not treat it as a production database without a plan for upgrades and restarts.
Single Compose host
The Docker Compose guide runs Weaviate as containers on one machine, which is the simplest server-based option. You own the host, its disks, its patching and its backups, and a single host is a single point of failure. Anonymous access is strongly discouraged outside development or evaluation, so configure API key or OIDC authentication before any data arrives. Confirm which settings your environment needs from the Docker installation guide.
Multi-host Compose cluster
A multi-node Compose cluster designates one founding node and sets CLUSTER_JOIN on the others so they attach to it. Set CLUSTER_HOSTNAME explicitly, because changing hostnames is known to cause issues, and give each node its own gossip and data bind ports. Your team writes and maintains the Compose files, host firewall rules and node recovery steps. Ask your own platform team who will handle a failed host at 2 a.m. before choosing this layout.
Helm chart with PersistentVolumeClaims
The Weaviate Helm chart on Kubernetes requires Kubernetes 1.23 or later, Helm v3 and PersistentVolumeClaims with ReadWriteOnce storage. The chart version cited in the guide is 17.8.3, and its default configuration defines one Weaviate replica, so high availability requires you to change the replica count and storage design. Check that your storage class and backup tooling support the volume mode you choose. Pin the chart version in your deployment pipeline.
Replication per collection
Replication is disabled by default and enabled per collection with a replication factor, which is separate from how many pods you run. Reads and writes can be set to ONE, QUORUM or ALL at query time, trading latency against how many replicas must respond. Replication protects availability of data only when the replicas sit on separate failure domains. Decide the replication factor per collection during design, then test failover before go-live.
Kubernetes control plane you must run
Running Weaviate on Kubernetes also makes your team responsible for the cluster itself. A kubeadm high availability design needs at least three control plane nodes with a TCP load balancer on port 6443, and etcd should run with an odd member count, with five members recommended in production. You also need an etcd backup plan using etcdctl snapshot save and restores with etdutl. Ask whether this platform team already operates these components before choosing the Helm path.
Why replication defaults matter more than the install method
Replication is off until you turn it on, so no install method gives high availability by default. Weaviate replication is leaderless, disabled by default and enabled per collection with a replication factor. A multi-node Docker Compose cluster built from a founding node and CLUSTER_JOIN settings, or a Helm install that defines one Weaviate replica, can run several processes and still store each object only once. Before you go live, confirm the replication factor on every collection that matters, then confirm that the replicas are placed on different nodes. Check this in the replication settings of each collection, not in the deployment manifest alone. Also plan how you will add replicas to collections that already contain data, since a collection created without replication does not gain it by joining more nodes.
Consistency is a query-time choice, so it belongs in your application design as well as your runbook. Weaviate offers ONE, QUORUM and ALL consistency levels, set when a request is made. ONE favors responsiveness, QUORUM balances agreement across replicas with availability, and ALL requires every replica to respond. Decide which level each workload needs, for example retrieval for a chat assistant may tolerate a different level than a compliance lookup, and write that decision into the service code and test plans. Ask your engineering team to confirm the default the client library uses in each service, because a default that the application never sets explicitly is easy to forget during an upgrade.
Replication only protects data while the layer beneath it stays up. On Kubernetes, the control plane depends on etcd, which the kubeadm high availability guide describes as a cluster that should have an odd number of members, with five members recommended in production and a backup plan for etcd data. On Compose, the single host or set of hosts running the containers becomes the failure boundary, so host redundancy, storage and backups need the same attention as the database settings. Ask your platform team to show, for your chosen install method, which node failure leaves Weaviate writable and readable at your chosen consistency level, and test that path before you rely on it.
Operating each model: backups, monitoring and team skills
This table compares what each Weaviate deployment model asks of your team after go-live: backups, monitoring, logs, secrets and hardening. Read each row as a list of what you must build yourself, and confirm the Weaviate-specific details with the Weaviate documentation or your own environment before you commit.
| Operating concern | Embedded Weaviate | Docker Compose (one or several hosts) | Weaviate Helm chart on Kubernetes |
|---|---|---|---|
| Backups of Weaviate data | Data lives in the data path of the application host. Confirm the supported backup method for experimental embedded mode with Weaviate documentation, since its APIs and parameters may change. | Weaviate data is stored in the node's volumes. Confirm the backup module and procedure for your Weaviate version, and test restores on each node. | Etcd snapshots protect Kubernetes cluster state, not Weaviate objects. Plan a separate Weaviate backup and confirm its procedure, storage target and restore test with Weaviate documentation. |
| Cluster state backups | Not applicable: there is no separate control plane to back up. | Not applicable to Compose itself. Keep the Compose files, environment settings and volume layout under version control. | Kubernetes documents that etcd needs a backup plan and uses etcdctl snapshot save for backups and etcdutl for restores. Apply this to the control plane, which is separate from Weaviate data. |
| Monitoring and metrics | Usually handled by the host application. Confirm which Weaviate metrics are exposed in embedded mode before relying on them. | Monitor each container and host separately. Confirm the Weaviate metrics endpoint and scrape configuration for your version. | Monitor pods, persistent volumes and the Weaviate service through your cluster monitoring stack. Confirm the metrics and health endpoints in the Helm chart for your version. |
| Log handling | Logs go to the application's logging setup. Decide how they are shipped and retained, and confirm what Weaviate writes. | Logs are per container. Set a log driver or forwarder on every node and confirm the Weaviate log level and format. | Cluster-level log collection is needed for pods across nodes. Confirm the log output of Weaviate pods and the retention your audit process requires. |
| Secrets handling | API keys and OIDC settings sit in the application environment or code. Keep them out of source control and confirm where the client stores them. | API keys and environment values sit in Compose files or an env file on each host. Restrict file permissions and confirm the approach for each node. | Kubernetes Secrets are stored unencrypted in etcd by default. Enable encryption at rest, restrict list and watch access with least-privilege RBAC, or use an external store through the Secrets Store CSI Driver. |
| Hardening baseline | Limited to the host and application. Apply your host hardening standard and confirm that anonymous access is disabled. | Anonymous access is strongly discouraged outside development. Enable API key or OIDC authentication and review RBAC roles per environment. | Apply Pod Security Standards to the namespace and review the CIS Kubernetes Benchmark with your cluster administrators. Confirm which controls your distribution and chart values satisfy. |
| Upgrades and version pinning | Pin the Weaviate version explicitly. The docs say the client default may lag several minor releases. | Pin image tags and test each Weaviate release, including maintenance lines, on a staging host first. | Plan upgrades around Kubernetes version skew and Weaviate chart versions. Confirm the chart version you pin and test the upgrade order in staging. |
| Skills your team needs | Application development skills and basic Weaviate operations knowledge. Lowest operating surface, with the most dependence on the application. | Linux administration, container networking, volume management and TLS. Multi-node setup adds gossip and bind port planning. | Kubernetes administration, Helm, storage classes, etcd operations, RBAC and certificate management. Most staff hours usually sit here, so confirm your team has these skills or a partner to cover them. |
Questions buyers ask before choosing a Weaviate deployment
Is embedded Weaviate safe to use in production?
Not as a production database today. Embedded Weaviate is labeled experimental software, and its APIs and parameters may change, so treat it as a development and prototyping option. It runs inside your application process, stops when that process exits, and keeps data in its data path, which makes it a poor fit for a shared service. The Python client includes it from Weaviate v1.23.7 onward, and the docs recommend pinning the version explicitly because the client default may lag several minor releases. For production, plan a stand-alone server under Docker or Kubernetes, and confirm with Weaviate which embedded parameters are stable before you depend on any of them.
How much more effort does Kubernetes add over Docker Compose?
Kubernetes adds cluster operations that Compose does not require. Compose runs Weaviate on a host you manage directly. The Weaviate Kubernetes guide requires Kubernetes 1.23 or later, Helm v3 and PersistentVolumeClaims with ReadWriteOnce storage, and it cites Helm chart version 17.8.3. Your cluster also needs upgrades on a fixed cadence: Kubernetes ships about three minor releases per year, and the project maintains the three most recent minors. Ask who patches the control plane, who owns storage classes and backups, and whether the cluster is managed by a cloud provider or built with kubeadm. Those answers, not the Weaviate chart, usually set the ongoing effort.
Can a small team run the Weaviate Helm chart without a platform team?
A small team can install the chart, but running the surrounding cluster is the harder part. The default configuration defines one Weaviate replica, so a single-replica install is a simple starting point, but it does not provide the redundancy of a multi-replica setup. Before committing, confirm that someone can own cluster upgrades, node failures, persistent volume behavior and etcd backups if you run kubeadm yourself. Kubernetes documentation says etcd needs a backup plan and recommends an odd number of members, with five in production. If no one on the team can take that on, a fixed-scope engagement or a managed Kubernetes service may suit better than hiring in-house.
What does a multi-node Docker Compose Weaviate cluster need?
It needs one founding node, additional nodes that join it, and stable identity for each node. The Weaviate Docker guide configures the first node as the founder and sets CLUSTER_JOIN on the others. Set CLUSTER_HOSTNAME explicitly, because the docs note that changing hostnames is known to cause issues. Each node also needs its own gossip and data bind ports, and the hosts must reach each other on those ports. Compose has no built-in scheduler, restart coordination across hosts or volume orchestration, so you own host patching, failover runbooks and monitoring. Ask for a written runbook covering node replacement and recovery before you go live.
How do replication and consistency work with each deployment model?
Replication is a collection-level setting, not a deployment setting. Weaviate replication is leaderless, disabled by default, and enabled per collection with a replication factor. Consistency levels ONE, QUORUM and ALL are set at query time. A replication factor only adds fault tolerance if you have enough nodes to place those replicas, so a one-node Embedded or single-container setup gives you no replica redundancy regardless of the factor you set. Compose and Kubernetes can both host replicated clusters, but the Kubernetes chart's default of one replica means you must change the configuration deliberately. Test node loss and consistency behavior in your own environment before choosing QUORUM or ALL for latency-sensitive queries.
What does a DeployOpen engagement cover, and what must our team provide?
DeployOpen plans, implements, hardens, backs up, documents and supports self-hosted open-source platforms inside your own infrastructure, including cloud accounts, data centers and air-gapped networks. Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts, and ongoing support and upgrades are available as retainers. Your team typically supplies access to the target environment, the identity provider and network rules, data residency requirements and named owners for decisions. DeployOpen does not publish a price list, so ask for a quote that lists the deployment model chosen, node count, Kubernetes or host responsibilities, authentication and RBAC setup, backup and restore testing, documentation and handover, and what is excluded.
What drives the cost of running Weaviate yourself?
The cost has three parts: infrastructure you pay your cloud or data center provider for, the people who run it, and any outside help you buy. Embedded mode costs little to start but moves the operating burden into application releases. Compose adds host management and cluster runbooks. Kubernetes adds cluster upgrades, storage and backup tooling. Most of the expense is recurring: patching, upgrades, backups, monitoring and on-call. Ask a provider or consultant to separate one-time setup from recurring operations, to state which Weaviate version and chart version they will pin, and to name who handles security patches. Compare that against Weaviate Cloud pricing published by the vendor rather than assumed figures.
Moving from embedded or Compose to Kubernetes later
Plan the move to Kubernetes before you start on embedded or Compose, because each starting point leaves different things behind. Embedded Weaviate keeps its data in the data path of the application process, and it is labeled experimental, with APIs and parameters that may change. Moving off it means exporting or re-importing your collections into a server deployment rather than pointing the Helm chart at the same files. A Compose deployment is closer to the target, but its node identities are the constraint: the founding node and the nodes that set CLUSTER_JOIN depend on hostnames and on the gossip and data bind ports you assigned. Keep CLUSTER_HOSTNAME values stable from the first day, because changing hostnames are known to cause issues, and record every port mapping so the cluster can be rebuilt with the same identities.
The Helm chart places its own requirements on storage. The Kubernetes guide calls for PersistentVolumeClaims with ReadWriteOnce storage, Kubernetes 1.23 or later and Helm v3, and its default configuration defines one Weaviate replica. Before cutover, confirm with your storage class owner that the volumes you need are ReadWriteOnce and that they can be sized and snapshotted for your data. Then write a backup and restore plan that you have tested against a copy of the data, including how you will verify object counts and vector search results after the restore. Replication is disabled by default and is enabled per collection, so decide which collections need a replication factor on the new cluster and plan the change explicitly instead of assuming the Compose settings carry over.
Treat the migration steps as something to confirm, not something to reuse from this page. Check the current embedded, Docker and Helm installation guides and the Weaviate replication and authentication docs for the version you intend to run, since the embedded guide says the client's pinned default may lag several minor releases. Ask your Weaviate contact or DeployOpen during scoping to confirm the export, restore and cutover sequence, and agree on who runs the rehearsal. Also review your authentication settings before cutover, because anonymous access is strongly discouraged outside development and API key, OIDC and RBAC configuration should be carried into the cluster deliberately.
A phased path from prototype to production cluster
This sequence moves a Weaviate deployment from a throwaway validation run to a hardened production topology, with each stage ending in a check you can verify. It works whether the destination is a Compose cluster on several hosts or the Helm chart on Kubernetes.
Validate the data model on embedded or one Compose host
Start with Embedded Weaviate from the Python client or a single-node Docker Compose stack, depending on whether the goal is a quick local test or a service your team can reach. Treat embedded mode as experimental, since its APIs and parameters may change, and pin the Weaviate version explicitly rather than relying on the client default. Confirm that a sample import, vector search and hybrid query return the results you expect before moving on.
Define collections and set replication factors
Create the collections your application needs and decide which of them need replication, because replication is disabled by default and is enabled per collection with a replication factor. Record the consistency level your queries will use (ONE, QUORUM or ALL) and check it against your availability and staleness requirements. Your output is a written schema file, with a replication factor for each collection, that can be reapplied to a new environment.
Confirm the production topology before building it
Choose between a multi-node Compose cluster and the Weaviate Helm chart on Kubernetes based on the platform your team already operates. The Kubernetes guide requires Kubernetes 1.23 or later, PersistentVolumeClaims with ReadWriteOnce storage and Helm v3, and its default configuration defines one replica, so replica counts must be set deliberately. Ask your platform team who will patch the cluster and the host, since that work recurs for the life of the deployment.
Harden authentication with API keys or OIDC and RBAC
Turn off anonymous access, which the Docker guide strongly discourages outside development or evaluation. Enable API key authentication or OIDC, then assign custom roles and permissions through the user management API so each service and person has only the access it needs. Verify the result by sending a request with no credentials and confirming it is refused, and by checking that each role can perform only its intended operations.
Deploy the chosen topology with secrets and network controls
Build the multi-node Compose cluster or the Helm release using the same schema and authentication settings from earlier steps. For Compose, set CLUSTER_HOSTNAME on each node and keep hostnames stable, since changing them is known to cause issues. For Kubernetes, store keys as Secrets, and review the Secrets guidance, which notes that Secrets are unencrypted in etcd by default. Confirm that all nodes join the cluster and that the collections replicate as defined.
Add monitoring and alerting before go-live
Set up metrics collection, log retention and alerts on node health, disk usage and query errors in your existing monitoring stack, and confirm that alerts reach an on-call owner. Document which team responds to each alert and the steps they follow. The check that closes this step is a test alert that fires and is acknowledged by the responsible team.
Test restores before relying on the deployment
Take a backup, restore it into a separate environment and confirm the collections, objects and authentication settings come back intact. Repeat the restore on a schedule and record the time and any gaps. Ask your deployment partner or internal team to show the restore procedure in writing, because an untested backup does not count as a recovery plan.
How DeployOpen plans and runs Weaviate deployments
DeployOpen plans and runs self-hosted Weaviate inside your own cloud accounts, data centers or air-gapped networks. We start by matching the deployment path to your team, data residency and availability requirements, then write the scope before any work begins.
How we scope
- Engagements are fixed-scope, with deployment path, environments and deliverables agreed in writing before work starts.
- We record which path fits your team: embedded for prototypes, Compose for a small cluster, or Helm on Kubernetes.
- The written scope states the replication factor, authentication model and backup approach you need to confirm with your own requirements.
- Quotes follow from the written scope, so the scope document should list every host, cluster and environment in play.
How we build
- We deploy Weaviate in your environment, with the version pinned explicitly rather than left to a client default.
- For Compose, we configure a founding node and joining nodes with stable hostnames and separate gossip and data ports.
- For Kubernetes, we check cluster version, PersistentVolumeClaim storage and Helm v3 before installing the chart.
- We configure API key or OIDC authentication and RBAC roles, and disable anonymous access outside development.
How we hand over
- You receive documentation of the deployed topology, configuration keys, versions and the replication settings applied.
- Runbooks cover startup, restarts, backups and restores, and what changes if you move from embedded mode to a server.
- Test results from the agreed scope are delivered with the environment so your team can rerun them.
- We walk your operators through upgrade steps so version changes are planned rather than improvised.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the build.
- A retainer can cover version reviews against Weaviate releases and maintenance lines your team chooses to track.
- Ask us to confirm the support hours, response expectations and upgrade cadence in the written retainer scope.
- We prepare evidence for compliance assessments, but independent auditors and certification bodies issue any reports.
