Weaviate Setup
This guide explains how to set up a local Weaviate instance for development with Artemis. Weaviate is a vector database that is used by the EduTelligence suite (Iris/Pyris) for storing and retrieving embeddings.
In the future Artemis will also directly communicate with Weaviate to offer a global keyword and semantic search across all entities (lectures, exercises, chats, ...).
Setting up Weaviate is only required when running Pyris locally for Iris functionality or developing the global search feature. If you only need basic Artemis features without AI assistance, you can skip this setup.
Prerequisites
- Docker and Docker Compose installed on your machine
- At least 2GB of available disk space for data storage
Quick Start
All commands in this guide should be run from the docker directory.
cd docker
Starting Weaviate
Start the Weaviate service:
docker compose -f weaviate.yml up -d
This will start Weaviate with the following configuration:
| Service | Port | Description |
|---|---|---|
| REST API | 8001 | HTTP REST interface |
| gRPC | 50051 | gRPC interface |
The configuration should be kept aligned with the settings in the edutelligence/iris repository.
Verifying the Installation
Check that Weaviate is running correctly:
curl -v http://localhost:8001/v1/.well-known/ready
You should receive a response indicating the service is ready.
Stopping Weaviate
To stop the Weaviate service:
docker compose -f weaviate.yml down
Configuration
Default Configuration
The default configuration is stored in docker/weaviate/default.env:
QUERY_DEFAULTS_LIMIT=25
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true
PERSISTENCE_DATA_PATH=/var/lib/weaviate
DEFAULT_VECTORIZER_MODULE=none
ENABLE_MODULES=
CLUSTER_HOSTNAME=artemis
LIMIT_RESOURCES=true
DISK_USE_WARNING_PERCENTAGE=80
Configuration Options
| Variable | Default | Description |
|---|---|---|
QUERY_DEFAULTS_LIMIT | 25 | Default limit for query results |
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED | true | Allow anonymous access (development only) |
PERSISTENCE_DATA_PATH | /var/lib/weaviate | Path for data persistence inside container |
DEFAULT_VECTORIZER_MODULE | none | Default vectorizer (none for external embeddings) |
ENABLE_MODULES | (empty) | Additional modules to enable |
CLUSTER_HOSTNAME | artemis | Hostname for the Weaviate cluster node |
LIMIT_RESOURCES | true | Enable resource limiting |
DISK_USE_WARNING_PERCENTAGE | 80 | Warn when disk usage exceeds this percentage |
Data Persistence
By default, Weaviate data is persisted in .docker-data/weaviate-data. You can customize this by setting the WEAVIATE_VOLUME_MOUNT environment variable:
export WEAVIATE_VOLUME_MOUNT=/path/to/your/data
docker compose -f weaviate.yml up -d
Anonymous access is enabled by default for development convenience. For production deployments, configure proper authentication.
Integration with Pyris
When running Weaviate locally, configure the Weaviate connection in your application.local.yml:
weaviate:
host: "localhost"
port: "8001"
grpc_port: "50051"
Ensure that Weaviate is running before starting Artemis. Artemis will connect to Weaviate to store and retrieve embeddings for global search functionality, e.g., retrieving lecture content.
Troubleshooting
Port Conflicts
If port 8001 or 50051 is already in use, create or edit docker/.env (which is gitignored) and set custom ports:
WEAVIATE_REST_PORT=8002
WEAVIATE_GRPC_PORT=50052
Remember to update the Pyris configuration accordingly.
Container Not Starting
Check the container logs for errors:
docker compose -f weaviate.yml logs weaviate
Resetting Data
To completely reset Weaviate data:
docker compose -f weaviate.yml down
rm -rf .docker-data/weaviate-data
docker compose -f weaviate.yml up -d
This will delete all stored embeddings and require re-indexing of lecture content.