langfuse 설치 (self-hosted)

Langfuse는 애플리케이션의 성능 및 상태를 모니터링하고 분석하는 데 도움을 주는 오픈소스 도구이다. 여기서는 Langfuse를 self-hosted 환경에서 설치하고 구성하는 방법을 단계별로 알아보자.

사전 준비

1. 서버 환경 준비

Langfuse를 설치하기 위해서는 Linux 기반의 서버가 필요하다. 최소 요구 사항은 다음과 같다.

• CPU: 2개 이상의 vCPU
• RAM: 4GB 이상
• 디스크: 20GB 이상의 여유 공간

2. Docker 및 Docker Compose 설치

Langfuse는 Docker 컨테이너로 배포할 수 있다. 이를 위해 Docker와 Docker Compose가 설치되어 있어야 한다.
여기서는 centos 9에서 설치를 한다.

Docker 설치

sudo yum install -y yum-utils

sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

sudo yum install docker-ce docker-ce-cli containerd.io docker-compose-plugin -y

sudo systemctl start docker

sudo systemctl enable docker

Langfuse 설치

1. Langfuse 리포지토리 복제

Langfuse의 공식 리포지토리에서 코드를 클론합니다. 이 작업은 Langfuse를 실행할 디렉토리에서 수행한다.

git clone https://github.com/langfuse/langfuse.git
cd langfuse

2. Docker Compose 설정 파일 편집

Langfuse는 Docker Compose를 통해 여러 서비스를 실행한다. 기본적으로 제공된 docker-compose.yml 파일을 수정하여 필요한 설정을 적용한다.

services:
  langfuse-server:
    image: langfuse/langfuse:2
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres
      - NEXTAUTH_SECRET=mysecret
      - SALT=mysalt
      - ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000 # generate via `openssl rand -hex 32`
      - NEXTAUTH_URL=http://localhost:3000
      - TELEMETRY_ENABLED=${TELEMETRY_ENABLED:-true}
      - LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES=${LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES:-false}

위의 docker-compose.yml 파일에서 다음과 같은 설정을 수정해야 한다.

• POSTGRES_USER와 POSTGRES_PASSWORD를 적절한 값으로 변경한다.
• LANGFUSE_DATABASE_URL에서 데이터베이스 접속 정보를 수정한다.

내부망에서 사용하는 거라면 그냥 사용해도 무방할 듯 하다.

• NEXTAUTH_URL의 URL을 사용할 IP정보로 변경한다.
  • NEXTAUTH_URL: localhost ==> 실제 IP

3. Docker Compose로 Langfuse 실행

설정이 완료되었으면, Docker Compose를 사용하여 Langfuse를 실행한다. 실행할 때 postgresql DB도 같이 설치가 된다.

docker compose up -d

이 명령어는 Langfuse와 관련된 모든 서비스를 백그라운드에서 실행한다. 실행 후 몇 분 안에 Langfuse가 설정한 포트에서 실행되고 있는지 확인할 수 있다.

4. Langfuse에 접속

브라우저를 열고 서버의 IP 주소 또는 도메인에 접속한다. 기본적으로 http://your-server-ip:3000에 접속하여 Langfuse 대시보드에 접속할 수 있다.

http://your-server-ip:3000

유지보수 및 모니터링

1. 로그 모니터링

Langfuse와 관련된 Docker 컨테이너의 로그를 확인하려면 다음 명령어를 사용할 수 있다.

sudo docker compose logs -f

이 명령어는 실시간 로그를 보여주며, 문제가 발생했을 때 유용하다.

2. 서비스 재시작

서비스를 재시작하거나 업데이트가 필요할 때는 다음 명령어를 사용하여 Docker Compose를 다시 시작할 수 있다.

sudo docker compose down
sudo docker compose up -d

3. 데이터베이스 백업 및 복구

데이터베이스의 백업을 주기적으로 수행하여 데이터를 안전하게 보관할 수 있다. PostgreSQL을 사용하는 경우, pg_dump를 사용하여 백업할 수 있다.

docker exec -t langfuse_db_1 pg_dump -U username -F c -b -v -f /var/lib/postgresql/data/langfuse_backup.sql langfuse

복구할 때는 다음 명령어를 사용할 수 있다.

docker exec -i langfuse_db_1 pg_restore -U username -d langfuse /var/lib/postgresql/data/langfuse_backup.sql

langfuse 업데이트 방법

사용하던 langfuse의 버전을 업데이트 하는 방법은 간단하다.

# 컨테이너 중지
docker compose down

# 업데이트
docker pull langfuse/langfuse:2

# 컨테이너 시작
docker compose up -d

이렇게 하면 최신 업데이트가 적용이 된다.

참고

• https://github.com/langfuse/langfuse/blob/main/README.md