Deploy Weaviate v1.38: Cloud Native Vector DB Guide

Hot take: if you’re deploying a cloud native vector DB in 2026 and reaching for a managed service first, you’re paying for a database you don’t yet understand. Self-host Weaviate on a $20 VPS for a week. You’ll learn more about vector search economics than any managed dashboard will teach you – and you’ll know exactly when it’s worth graduating to Weaviate Cloud.

This guide gets you from zero to a working Weaviate v1.38 instance, with the memory traps that crash production nodes spelled out before you hit them.

What you’re actually deploying

Weaviate is an open-source vector database written in Go. The current stable release is v1.38.7 (GitHub releases). v1.38.0 shipped two things to general availability: HFresh, a disk-based SPFresh-inspired vector index built for streaming workloads, and the MCP Server. Pick HFresh by setting vectorIndexType: "hnsw" on your named vector – writes get cheaper and the memory ceiling drops compared to pure HNSW, because HFresh is disk-first by design. That matters a lot once you have more than a few million vectors and a machine that isn’t a rental from a cloud provider.

One thing to have on your radar if you’re upgrading from anything below v1.33: compression flips on by default at that version (per the v1.33 release notes). Older tutorials that explicitly disable compression will make your memory footprint worse on upgrade, not better – the opposite of what they were trying to do.

System requirements (the honest version)

The docs list 8 GB RAM as the floor. That number is for a demo. Here’s what the table actually looks like:

The 8 GB floor is fiction for anything real. Community reports on the Weaviate forum show 100k records at 768-dim vectors sitting idle at ~33 GB after restart – import worked fine, but the process slowly ate memory until the kernel killed it (documented in forum thread #2246). Plan for at least 2 GB baseline plus your compressed vector footprint × 1.5.

Docker Compose install

Docker Compose is the safe default for single-node work. Kubernetes via the weaviate-helm chart (v17.7.0 as of this writing) is where you go for production – you want its PVC handling and rolling updates the moment uptime matters.

Create docker-compose.yml:

services:
 weaviate:
 image: cr.weaviate.io/semitechnologies/weaviate:1.38.7
 command:
 - --host
 - 0.0.0.0
 - --port
 - '8080'
 - --scheme
 - http
 ports:
 - 8080:8080
 - 50051:50051
 volumes:
 - weaviate_data:/var/lib/weaviate
 restart: on-failure:0
 environment:
 QUERY_DEFAULTS_LIMIT: 25
 AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false'
 AUTHENTICATION_APIKEY_ENABLED: 'true'
 AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'change-me-now'
 AUTHENTICATION_APIKEY_USERS: '[email protected]'
 AUTHORIZATION_ADMIN_USERS: '[email protected]'
 PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
 CLUSTER_HOSTNAME: 'node1'
 LIMIT_RESOURCES: 'true'
 GOMEMLIMIT: '6GiB'
volumes:
 weaviate_data:

Boot it:

docker compose up -d
docker compose logs -f weaviate

Two deliberate choices here that the official quickstart skips: anonymous access is off (the docs call this strongly discouraged except for dev/evaluation), and LIMIT_RESOURCES plus GOMEMLIMIT are set before you need them. Most guides add those after the first crash. Don’t be most guides.

Verify it’s actually running

curl http://localhost:8080/v1/.well-known/ready
# Expect: 200 OK, empty body

curl http://localhost:8080/v1/meta 
 -H "Authorization: Bearer change-me-now" | jq .version
# Expect: "1.38.7"

Then wire up the Python client. The current release is v4.18.1:

pip install -U "weaviate-client==4.18.1"

import weaviate
from weaviate.classes.init import Auth

client = weaviate.connect_to_local(
 auth_credentials=Auth.api_key("change-me-now")
)
print(client.is_ready()) # True
client.close()

is_ready() returns True? You’re done with setup. Hangs indefinitely? The errors section is next.

Three errors nobody warns you about

1. The vm.max_map_count crash – looks like OOM, isn’t

You see fatal error: runtime: cannot allocate memory and the container dies. Looks like OOM. It’s not. Turns out Go’s runtime throws a fatal error when it runs out of memory mappings – and unlike a regular panic, that error can’t be caught. The whole node goes down hard (tracked in GitHub issue #4585).

Fix on the host, not inside the container:

sudo sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

2. Idle memory growth → OOM-kill

On large machines with fast import speeds, Weaviate can allocate memory faster than the Go garbage collector frees it. The kernel then kills the process (per Weaviate’s resource planning docs). The GOMEMLIMIT and LIMIT_RESOURCES settings in the compose file above are the fix – set GOMEMLIMIT to roughly 75% of your container’s memory ceiling.

3. Anonymous-access production leak

Copy-pasted the quickstart from any tutorial before 2025? You’re probably running with AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'. If port 8080 is exposed, anyone can drop your collections. Test it right now:

curl -X DELETE http://YOUR_HOST:8080/v1/schema/YourCollection

If that returns 200 without an auth header, close it before you finish reading.

Note: Weaviate telemetry is on by default – as of this writing. Set DISABLE_TELEMETRY: 'true' in your env block if you’re in a regulated or air-gapped environment. Check the current docs to confirm this hasn’t changed.

Upgrading and rolling back

Weaviate upgrades one minor version at a time – skipping from v1.31 to v1.38 in one jump is not officially supported (check the migration guide for your specific path; this may have changed). Walk each minor version: v1.32, v1.33, and so on.

1. Back up first. Use the backup module to snapshot to filesystem or S3.
2. Read the migration guide for each minor version in the path.
3. Bump the image tag in docker-compose.yml.
4. Pull and restart:docker compose pull && docker compose up -d.
5. Verify with /v1/meta.

Rollback isn’t “change the tag back.” Once Weaviate writes data in a newer format, downgrading can corrupt it. Restore from backup. The release notes page flags breaking changes per version.

Uninstall (clean)

docker compose down
docker volume rm $(docker volume ls -q | grep weaviate_data)
docker rmi cr.weaviate.io/semitechnologies/weaviate:1.38.7

The volume delete is destructive – all vectors, all schemas, gone. Confirm your backup restored somewhere else before running it.

Next step

Spin up the compose file above on your smallest available machine. Push 10k vectors through it. Watch docker stats during import. Whatever memory number you see, double it for production sizing. That’s the honest math the docs won’t give you.

At some point it’s worth asking: is self-hosting still the right call? The answer usually flips when you have more than one node, need zero-downtime upgrades, or your ops team has better things to do than babysit a Go process at 3am. Until then, this setup gives you the full picture.

FAQ

Should I use Docker Compose or Kubernetes for production?

Kubernetes. Compose works for single-node dev – the moment you care about uptime, you want the Helm chart’s PVC handling and rolling updates.

Why does my Weaviate container eat memory when idle?

Go’s runtime doesn’t aggressively return memory to the OS, and HNSW keeps vectors in RAM by default. If you imported 100k+ vectors on a tight machine, set GOMEMLIMIT to a hard ceiling (e.g., 6GiB). One more thing: compression is on by default since v1.33, but only for new collections. Collections created before v1.33 stay uncompressed until you explicitly migrate them – so an upgrade alone won’t fix the footprint on old data.

Can I run Weaviate on ARM (Raspberry Pi, Apple Silicon, cloud ARM instances)?

The official image is multi-arch and arm64 works – as of this writing. That said, expect real limits on a Pi 4: anything beyond a few thousand vectors will feel sluggish, and HFresh’s disk-first design fights SD card I/O hard. Use an SSD via USB 3, and treat the Pi setup as a learning exercise rather than a deployment target. Apple Silicon M-series or cloud ARM instances (Graviton, Ampere) are a different story – those run Weaviate fine.