> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baeum.ai.kr/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenSearch

오픈소스 **전문 검색(Full-text Search) 엔진**입니다. AWS에서 Elasticsearch를 기반으로 개발했으며, Elasticsearch와 호환되는 API를 제공합니다.

## 어디에 쓰이나요?

* **전문 검색**: 문서, 게시글, 상품 등에서 키워드로 검색 (형태소 분석, 유사어 검색 지원)
* **로그 분석**: 서버 로그, 애플리케이션 로그를 수집하고 분석 (ELK 스택의 E를 대체)
* **실시간 분석**: 대량의 데이터를 실시간으로 집계하고 시각화

일반적인 데이터베이스(PostgreSQL 등)의 `LIKE` 검색은 데이터가 많아지면 느려집니다. OpenSearch는 데이터를 **역인덱스(Inverted Index)** 구조로 저장하여, 수백만 건의 문서에서도 빠른 검색이 가능합니다.

**OpenSearch Dashboards**는 OpenSearch에 저장된 데이터를 시각화하고 관리할 수 있는 웹 UI입니다.

## Docker Compose

```yaml docker-compose.yml theme={null}
services:
  opensearch:
    image: opensearchproject/opensearch:2
    container_name: opensearch
    restart: unless-stopped
    ports:
      - "9200:9200"
      - "9600:9600"
    environment:
      - discovery.type=single-node
      - OPENSEARCH_INITIAL_ADMIN_PASSWORD=Admin1234!
      - bootstrap.memory_lock=true
      - "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - opensearch_data:/usr/share/opensearch/data

  opensearch-dashboards:
    image: opensearchproject/opensearch-dashboards:2
    container_name: opensearch-dashboards
    restart: unless-stopped
    ports:
      - "5601:5601"
    environment:
      - OPENSEARCH_HOSTS=["https://opensearch:9200"]
    depends_on:
      - opensearch

volumes:
  opensearch_data:
```

<Note>
  OpenSearch 2.12 이상에서는 `OPENSEARCH_INITIAL_ADMIN_PASSWORD` 환경 변수가 필수입니다. 비밀번호는 대문자, 소문자, 숫자, 특수문자를 포함해야 합니다.
</Note>

## 실행

```bash theme={null}
docker compose up -d
```

## 접속 확인

```bash theme={null}
curl -k -u admin:Admin1234! https://localhost:9200
```

<Warning>
  기본적으로 자체 서명 인증서를 사용하므로 `-k` 옵션이 필요합니다.
</Warning>

## 기본 정보

| 항목            | 값          |
| ------------- | ---------- |
| REST API 포트   | 9200       |
| 성능 분석 포트      | 9600       |
| Dashboards 포트 | 5601       |
| 기본 사용자        | admin      |
| 기본 비밀번호       | Admin1234! |

## 환경 변수

| 변수                                  | 설명                                  |
| ----------------------------------- | ----------------------------------- |
| `discovery.type`                    | 클러스터 모드 (single-node 또는 multi-node) |
| `OPENSEARCH_INITIAL_ADMIN_PASSWORD` | admin 계정 비밀번호 (2.12+)               |
| `OPENSEARCH_JAVA_OPTS`              | JVM 힙 메모리 설정                        |
| `plugins.security.disabled`         | true로 설정하면 보안 플러그인 비활성화             |

## 보안 비활성화 (개발 환경)

개발 환경에서는 보안 플러그인을 비활성화하여 HTTP로 접속할 수 있습니다.

```yaml theme={null}
environment:
  - plugins.security.disabled=true
```

이 경우 `http://localhost:9200`으로 인증 없이 접속할 수 있습니다.

## 사전 요구사항

호스트 시스템에서 `vm.max_map_count` 값을 설정해야 합니다.

```bash theme={null}
sudo sysctl -w vm.max_map_count=262144
```

영구 적용하려면 `/etc/sysctl.conf`에 추가합니다.

```bash theme={null}
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf
```

## 라이선스

| 구분     | 내용                                  |
| ------ | ----------------------------------- |
| 라이선스   | Apache License 2.0                  |
| 개인 사용  | 자유롭게 사용 가능                          |
| 상업적 사용 | 자유롭게 사용 가능, 수정/재배포/상업적 서비스 제공 모두 가능 |

## 참고

* [OpenSearch Docker 설치 가이드](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/docker/)
* [OpenSearch 공식 문서](https://opensearch.org/docs/latest/)

## 설치 점검 목록

* `docker compose up -d` 후 `docker compose ps`로 컨테이너 상태를 확인했습니다.
* 기본 포트/계정/비밀번호를 문서대로 점검했습니다.
* 운영용으로 사용할 때 기본 비밀번호/시크릿 값을 변경했습니다.
* 장애 분석을 위해 `docker compose logs -f` 확인 방법을 숙지했습니다.

## 문제 해결 가이드

* 컨테이너가 실행되지 않으면 `docker compose logs -f`로 오류 원인을 먼저 확인합니다.
* 포트 충돌이 나면 기존 프로세스를 종료하거나 포트 매핑 값을 변경합니다.
* 이미지 pull 실패 시 네트워크 연결 및 레지스트리 접근 권한을 확인합니다.
* 설정 변경 후 문제가 지속되면 `docker compose down` 후 다시 `up -d`로 재기동합니다.

## 관련 문서

<CardGroup cols={2}>
  <Card title="Setup 홈" icon="house" href="/setup/index">
    운영체제별 설치 흐름을 다시 확인합니다.
  </Card>

  <Card title="다음: Qdrant" icon="arrow-right" href="/stacks/qdrant">
    다음 설치 단계를 이어서 진행합니다.
  </Card>
</CardGroup>