Docker 설치

Docker 설치 (Docker Installation)

Weaviate를 가장 간단하게 올려 보는 방법은 Docker를 쓰는 거예요. 기본 설정만으로도 명령 한 줄이면 컨테이너가 떠서 바로 localhost:8080로 요청을 받아 줍니다. 다만 실제 운영으로 넘어가면 데이터를 어디에 저장할지, 어떤 모듈(벡터라이저)을 켤지 같은 걸 결정해야 하니까, 그때는 docker-compose.yml을 직접 만들어 구성하게 돼요.

출처: 공식문서 — Docker

기본 설정으로 바로 실행

기본 설정으로 Weaviate를 Docker로 띄우려면 셸에서 다음 명령을 실행하면 됩니다.

docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:1.39.0

이 명령은 컨테이너 안에 다음 기본 환경변수를 설정해요.

• PERSISTENCE_DATA_PATH — 기본값 ./data
• AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED — 기본값 true
• QUERY_DEFAULTS_LIMIT — 기본값 10

참고로 Weaviate는 기본적으로 텔레메트리(운영 데이터)를 수집해요. 끄는 방법은 텔레메트리 페이지에서 다룹니다.

docker-compose.yml로 커스터마이즈

구성을 바꾸고 싶으면 docker-compose.yml 파일을 만들어 쓰면 됩니다. 공식 샘플에서 시작하거나, 대화형 Configurator로 파일을 생성할 수도 있어요. 이 스타터 컴포즈 파일은 다음을 지원합니다.

• OpenAI·Cohere·Google·Anthropic 같은 API 기반 모델 제공자 연동(임베딩·생성·리랭커 통합 포함)
• 벡터라이저 없이 미리 벡터화된 데이터 검색
• weaviate_data라는 영구 볼륨을 컨테이너 안 /var/lib/weaviate에 마운트해 데이터 저장

익명 접근으로 실행

아래 코드를 docker-compose.yml로 저장하면 익명 접근이 켜진 상태로 실행돼요.

services:
  weaviate:
    command:
    - --host
    - 0.0.0.0
    - --port
    - '8080'
    - --scheme
    - http
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.0
    ports:
    - 8080:8080
    - 50051:50051
    volumes:
    - weaviate_data:/var/lib/weaviate
    restart: on-failure:0
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      CLUSTER_HOSTNAME: 'node1'
volumes:
  weaviate_data:

경고: 익명 접근은 개발·평가 목적 외에는 권장하지 않아요. 운영에서는 인증·권한을 켜는 편이 안전합니다.

인증·권한을 켠 버전에서는 AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false', AUTHENTICATION_APIKEY_ENABLED 등을 설정합니다.

구성이 마음에 들면 다음으로 시작합니다.

docker compose up -d

HTTP와 gRPC 둘 다 접근하려면 각 포트(기본 HTTP 8080, gRPC 50051)를 노출해야 해요. 도메인으로 서비스하려면 리버스 프록시가 두 포트를 모두 포워딩하게 하면 됩니다. 대부분의 Weaviate 클라이언트와 호환되도록, gRPC 트래픽은 grpc- 접두사를 붙인 서브도메인을 쓰는 걸 권장해요. 예를 들어 도메인이 weaviate.example.com이라면:

• weaviate.example.com → localhost:8080 (HTTP)
• grpc-weaviate.example.com → localhost:50051 (gRPC, 보통 h2c)

영구 볼륨 설정

데이터 손실을 막고 읽기·쓰기 속도를 높이려면 영구 볼륨을 설정하는 게 좋아요. 종료할 때는 docker compose down을 실행해야 메모리의 파일이 전부 디스크로 기록됩니다.

named volume 사용 시:

services:
  weaviate:
    volumes:
    - weaviate_data:/var/lib/weaviate
    # 등
volumes:
  weaviate_data:

docker compose up -d 후 Docker가 weaviate_data named volume을 만들고, 컨테이너 안 PERSISTENCE_DATA_PATH에 마운트해요.

호스트 바인딩 사용 시:

services:
  weaviate:
    volumes:
    - /var/weaviate:/var/lib/weaviate
    # 등

호스트의 /var/weaviate를 컨테이너 안 PERSISTENCE_DATA_PATH에 마운트합니다.

모듈 없이 실행

모듈이 전혀 없는 Docker Compose 예시예요. 이 경우 가져오기·검색 시점에 모델 추론이 일어나지 않아서, 외부 ML 모델로 만든 벡터를 직접 넣어 줘야 합니다.

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.0
    ports:
    - 8080:8080
    - 50051:50051
    restart: on-failure:0
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      CLUSTER_HOSTNAME: 'node1'

transformers 모듈과 함께 실행

sentence-transformers/multi-qa-MiniLM-L6-cos-v1 모델을 쓰는 예시예요.

services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.39.0
    restart: on-failure:0
    ports:
    - 8080:8080
    - 50051:50051
    environment:
      QUERY_DEFAULTS_LIMIT: 20
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: "./data"
      DEFAULT_VECTORIZER_MODULE: text2vec-transformers
      ENABLE_MODULES: text2vec-transformers
      TRANSFORMERS_INFERENCE_API: http://text2vec-transformers:8080
      CLUSTER_HOSTNAME: 'node1'
  text2vec-transformers:
    image: cr.weaviate.io/semitechnologies/transformers-inference:sentence-transformers-multi-qa-MiniLM-L6-cos-v1
    environment:
      ENABLE_CUDA: 0  # set to 1 to enable
      # NVIDIA_VISIBLE_DEVICES: all  # enable if running with CUDA

transformers 모델은 GPU 전용으로 설계된 신경망이라, GPU 없이도 text2vec-transformers를 돌릴 수는 있지만 더 느려요. GPU가 있으면 ENABLE_CUDA=1로 CUDA를 켜면 됩니다. 이 모듈은 Weaviate v1.2.0 이상이 필요해요.

멀티 노드(클러스터) 구성

여러 호스트 노드를 쓰려면 다음 순서를 따릅니다.

• 노드 하나를 "창립(founding)" 멤버로 구성
• 다른 노드에는 CLUSTER_JOIN 변수 설정
• 각 노드에 CLUSTER_GOSSIP_BIND_PORT, CLUSTER_DATA_BIND_PORT 설정
• 각 노드에 RAFT_JOIN 설정
• 각 노드에 투표자 수만큼 RAFT_BOOTSTRAP_EXPECT 설정
• 선택적으로 각 노드에 CLUSTER_HOSTNAME으로 호스트명 설정

창립 멤버의 환경변수는 대략 이렇게 생겼어요.

weaviate-node-1:  # Founding member service name
  environment:
    CLUSTER_HOSTNAME: 'node1'
    CLUSTER_GOSSIP_BIND_PORT: '7100'
    CLUSTER_DATA_BIND_PORT: '7101'
    RAFT_JOIN: 'node1,node2,node3'
    RAFT_BOOTSTRAP_EXPECT: 3

나머지 멤버는 이렇게 구성합니다.

weaviate-node-2:
  environment:
    CLUSTER_HOSTNAME: 'node2'
    CLUSTER_GOSSIP_BIND_PORT: '7102'
    CLUSTER_DATA_BIND_PORT: '7103'
    CLUSTER_JOIN: 'weaviate-node-1:7100'  # 창립 멤버 노드의 서비스 이름
    RAFT_JOIN: 'node1,node2,node3'
    RAFT_BOOTSTRAP_EXPECT: 3

3노드 레플리케이션용 Docker Compose 파일도 공식 문서에 있어서, 로컬에서 복제 예시를 직접 테스트해 볼 수 있어요. 포트 규칙으로 CLUSTER_DATA_BIND_PORT를 CLUSTER_GOSSIP_BIND_PORT보다 1 높게 둡니다.

docker compose up 출력은 모든 컨테이너 로그를 붙잡아서 꽤 장황해요. Weaviate 로그만 보려면 docker compose up -d && docker compose logs -f weaviate처럼 실행하면 됩니다. 아니면 완전히 분리해서 docker compose up -d 후 {bindaddress}:{port}/v1/meta가 200 OK를 돌려줄 때까지 폴링해도 돼요.

클러스터 호스트명이 시간에 따라 바뀔 수 있는 시스템에서는 단일 노드 배포에 문제가 생길 수 있어요. docker-compose.yml에 CLUSTER_HOSTNAME을 명시해 두면 피할 수 있습니다.

더 알아보기 (Learn more)

• Kubernetes 설치
• 환경변수 레퍼런스
• 복제(Replication)
• 영속화(Persistence)