Skip to content
Klutch.sh Docs

Deploying a Weaviate App

Introduction

Weaviate is an open-source vector database with a GraphQL/REST API for semantic search and retrieval. This guide shows how to containerize Weaviate, persist its data, configure auth, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM semitechnologies/weaviate:latest


# Default Weaviate port
ENV HTTP_PORT=8080
EXPOSE 8080

Required environment variables

  • AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true (or false to require keys)
  • PERSISTENCE_DATA_PATH=/var/lib/weaviate
  • QUERY_DEFAULTS_LIMIT=20
  • ENABLE_MODULES=text2vec-openai (set to the modules you need)
  • DEFAULT_VECTORIZER_MODULE=text2vec-openai (align with enabled module)

If you disable anonymous access, configure your chosen auth provider variables accordingly.

Persistence

Weaviate stores indexes on disk:

  • Mount path: /var/lib/weaviate
  • Size: based on expected vector count and replication settings

Networking

  • Protocol: HTTP
  • Internal port: 8080
  • Clients reach https://example-app.klutch.sh while Klutch.sh routes to port 8080 inside the container.
Terminal window
curl -I http://localhost:8080/v1/.well-known/ready

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 8080.
  5. Add environment variables for persistence, auth, default vectorizer, and any modules. Mark secrets (e.g., provider API keys) as sensitive.
  6. Attach a persistent volume at /var/lib/weaviate sized for your data.
  7. Deploy. After the app starts, test the API and load your first schema and objects.

Verification

  • Readiness:

    Terminal window
    curl https://example-app.klutch.sh/v1/.well-known/ready

  • Metadata:

    Terminal window
    curl https://example-app.klutch.sh/v1/meta

Next steps

  • Secure access by disabling anonymous access and configuring API keys or OIDC.
  • Monitor disk usage on /var/lib/weaviate and plan capacity for your index size.
  • Configure backups of the mounted volume and any external module credentials.