How to Connect Weaviate on EC2: Complete Python Guide

Have you ever felt the frustration of setting up a blazing-fast vector database like Weaviate on the cloud, only to get stuck at the connection step? You’re not alone! Many developers and data scientists face this roadblock when deploying Weaviate on AWS EC2 instances. The good news? Connecting your Python application to a cloud-hosted Weaviate is easier than you think—if you know the right steps.

In this comprehensive guide, you’ll learn how to seamlessly connect to a Weaviate instance running on an EC2 server, upload and search documents, and avoid common pitfalls. Whether you’re building a Retrieval-Augmented Generation (RAG) pipeline, experimenting with LLMs, or just exploring vector databases, this post will empower you to get started quickly and confidently.

Prerequisites

Before you dive in, make sure you have the following:

Basic Python knowledge
AWS EC2 instance running Weaviate (see official Weaviate deployment docs)
Python 3.10+ installed locally
Docker (optional, for local testing)
Weaviate Python client (pip install weaviate-client)
Streamlit (pip install streamlit)
OpenAI/Azure OpenAI API key (for embedding and QA)
Security group on EC2 allowing inbound traffic on port 8080

Why Connect to Weaviate on EC2?

Weaviate is a powerful, open-source vector database that enables semantic search, RAG, and LLM-powered applications. Deploying it on EC2 gives you full control, scalability, and security. However, cloud networking can introduce connection issues if not configured properly.

Step 1: Launch Weaviate on EC2

First, deploy Weaviate on your EC2 instance. You can use Docker Compose or a pre-built AMI. Make sure Weaviate is listening on port 8080.

Pro Tip:
Open port 8080 in your EC2 security group to allow external connections.

Setting	Value
EC2 Port	8080 (TCP)
Source	Your IP/CIDR
Protocol	TCP

Step 2: Test the REST API Connection

Before integrating with Python, verify that your Weaviate instance is reachable.

import requests

WEAVIATE_URL = "http://<EC2_PUBLIC_IP>:8080"
response = requests.get(f"{WEAVIATE_URL}/v1/meta", timeout=10)
if response.status_code == 200:
    print("Connection successful!", response.json())
else:
    print("Connection failed:", response.text)

Python

Common Pitfall:
If you see a timeout or connection error, double-check your EC2 security group and ensure Weaviate is running.

Step 3: Connect Using the Weaviate Python Client

Now, let’s connect using the official Weaviate client. Here’s a snippet from our implementation:

import weaviate

client = weaviate.Client(
    url="http://<EC2_PUBLIC_IP>:8080",
    timeout_config=(5, 15)
)

if client.is_ready():
    print("Weaviate client connected!")
else:
    print("Client not ready.")

Python

The weaviate-client version – 3.26.7 used for connecting to EC2 instance. i have tried with version 4 but i am facing issue while connecting to weaviate, so i opted for that specific version.

Step 4: Ensure Schema Exists

Before uploading data, make sure your Weaviate schema is set up. For document chunking, you might use:

class_definition = {
    "class": "DocumentChunk",
    "description": "A chunk of a document with metadata",
    "vectorizer": "none",
    "properties": [
        {"name": "text", "dataType": ["text"]},
        {"name": "filename", "dataType": ["string"]},
        {"name": "page_number", "dataType": ["int"]},
        {"name": "chunk_index", "dataType": ["int"]}
    ]
}
client.schema.create_class(class_definition)

Python

Step 5: Upload and Search Documents

Our app lets you upload PDFs, chunk them, embed with Azure OpenAI, and store in Weaviate:

# Extract and chunk PDF
chunks = extract_pdf_chunks(file, file.name)
# Embed and upload
upload_chunks_to_weaviate(client, chunks)

Python

To search:

results = hybrid_search(client, "What is vector search?")
for r in results:
    print(r["text"])

Python

Best Practices and Common Pitfalls

Mistake	Solution
Port 8080 not open	Update EC2 security group
Wrong Weaviate URL	Use public IP, not localhost
Client not ready	Check Weaviate logs and health endpoint
Large file upload fails	Chunk files and batch uploads

Pro Tips:

Always use environment variables for sensitive info (API keys, endpoints).
Use batch uploads for efficiency.
Monitor EC2 and Weaviate logs for troubleshooting.

Conclusion

Connecting to a Weaviate instance deployed on an EC2 server doesn’t have to be daunting. By following these steps, you can unlock the full power of vector search, RAG, and LLM applications in your projects. Remember to secure your EC2 instance, monitor your connections, and leverage the flexibility of Weaviate for your data science workflows.