EVA App Installation

이 가이드는 Kubernetes 환경에서 EVA App을 빠르고 안정적으로 설치할 수 있도록 안내합니다.

🛠️ 사전 준비 사항

설치를 시작하기 전에 아래의 도구들이 준비되어 있는지 확인해 주세요.

• Kubernetes 클러스터: EVA가 구동될 클러스터가 필요합니다.
• kubectl 설치: 설치 가이드 바로가기
• Helm 설치: 설치 가이드 바로가기
• AWS CLI 설정: ECR 이미지 접근 권한을 위해 AWS 자격 증명이 필요합니다. 터미널에서 아래 명령어를 입력하여 설정해 주세요.

aws configure
# 안내에 따라 AWS Access Key ID, Secret Access Key 등을 입력합니다.

---

🚀 EVA App 설치하기

1단계: Helm 저장소 등록

먼저 EVA App 배포를 위한 Helm 레포지토리를 추가합니다.

helm repo add eva-app https://mellerikat.github.io/eva-app
helm repo update

2단계: 설정 파일(values.yaml) 준비

설치 시 필요한 기본 설정 템플릿을 현재 폴더에 다운로드합니다.

helm show values eva-app/eva-app > values.yaml

3단계: 사용자 환경에 맞춰 설정 업데이트

다운로드한 values.yaml 파일을 열어 환경에 맞는 설정을 수정해야 합니다. On-premise(자체 서버)와 Cloud(AWS) 환경에 따라 주요 설정값이 다르니 아래 표 및 하단 예제를 참고해 주세요.

EVA-APP Application Values

Category	Key	Default	Description
vision	app.vision.ml	-	VM 서비스 엔드포인트 URL
agent	app.agnet.llm	-	LLM 서비스 엔드포인트 URL
agent	app.agent.vlm	-	VLM 서비스 엔드포인트 URL
agent	app.agent.requestTimeoutSeconds	30	에이전트 요청 타임아웃 (초)
app	app.backendHost	-	백엔드 서버 호스트
app	app.backendPort	-	백엔드 서버 포트
app	app.backendSecure	-	HTTPS 사용 여부
app	app.browserTitleName	EVA	브라우저 탭 제목
app	app.infraProvider	onprem	인프라 제공자 타입 (onprem / ncp / aws)
app	app.jwtSecret	Secret	JWT 서명에 사용되는 비밀 키
lifeCycle	app.lifeCycle.analysisRetentionDays	None	알림 및 분석 데이터 보관 기간 (일)
license	app.license.activation_mode	online	라이선스 활성화 방식 (online 또는 offline)
license	app.license.product_code	eva	라이선스 제품 코드
license	app.license.api_key	...	라이선스 API 키
license	app.license.shared_key	...	라이선스 공유 키
pipeline	app.pipeline.detector.workerNum	16	Detector 파이프라인 동시 처리 워커 수
pipeline	app.pipeline.streamer.annotationColorMode	GRAY	어노테이션 색상 모드
pipeline	app.pipeline.streamer.dispatcherFaceAnonymizerEnabled	True	디스패처에서 얼굴 비식별화 사용 여부
pipeline	app.pipeline.ingester.ingesterStreamFPSForGrab	30.0	스트림 프레임 캡처 기준 FPS
pipeline	app.pipeline.perceptor.queueSize	100	Perceptor 작업 큐 크기
pipeline	app.pipeline.perceptor.workerNum	2	Perceptor 워커 개수
session	app.accessTokenExpireMinutes	1440	액세스 토큰 만료 시간 (분)
session	app.uiSessionTimeoutMinutes	60	UI 세션 만료 시간 (분, 0이면 제한 없음)

EVA-APP Resource Values

Category	Key	Default	Description
database	database.name	eva	애플리케이션에서 사용하는 데이터베이스 이름
database	database.type	internal	데이터베이스 유형 (internal: 클러스터 내 MySQL, external: 외부 DB)
database	database.service.nodePort	32060	내부 MySQL 서비스용 NodePort
database	database.internal.user	...	내부 데이터베이스 사용자 계정
database	database.internal.password	...	내부 데이터베이스 사용자 비밀번호
database	database.external.host	dbhost	외부 데이터베이스 호스트 주소
database	database.external.port	3306	외부 데이터베이스 포트
database	database.external.user	...	외부 데이터베이스 사용자 계정
database	database.external.password	...	외부 데이터베이스 사용자 비밀번호
image	image.repository	(env-specific)	eva-app 컨테이너 이미지 저장소
image	image.pullPolicy	IfNotPresent	이미지 pull 정책
image	image.tag	appVersion	이미지 태그 (기본값: chart appVersion)
imagePullSecrets	imagePullSecrets.enabled	true	이미지 pull secret 사용 여부
imagePullSecrets	imagePullSecrets.existingSecret	""	기존 image pull secret 이름
imagePullSecrets	imagePullSecrets.create	true	Helm에서 image pull secret 생성 여부
imagePullSecrets	imagePullSecrets.nameOverride	""	image pull secret 이름 오버라이드
imagePullSecrets	imagePullSecrets.account	339713051385	AWS ECR 계정 ID
imagePullSecrets	imagePullSecrets.region	ap-northeast-2	AWS ECR 리전
imagePullSecrets	imagePullSecrets.password	ECR Login Password	ECR 로그인 비밀번호
nodeSelector	nodeSelector	""	파드 스케줄링을 위한 노드 선택 조건
pv	pv.create	false	Helm을 통해 PersistentVolume 생성 여부
pv	pv.nameOverride	""	PersistentVolume 이름 오버라이드
pv	pv.annotations	""	PersistentVolume에 추가할 어노테이션
pv	pv.csi.driver	efs.csi.aws.com	CSI 드라이버 이름
pv	pv.csi.volumeHandle	fs-00000000000000000	CSI 볼륨 핸들
pv	pv.storageClassName	efs-sc-eva-app	PersistentVolume용 StorageClass 이름
pv	pv.storage	30Gi	PersistentVolume 스토리지 크기
persistence	persistence.type	hostPath	스토리지 유형 (pvc 또는 hostPath)
persistence	persistence.hostPath.path	""	hostPath 볼륨 마운트 경로
persistence	persistence.pvc.nameOverride	""	PersistentVolumeClaim 이름 오버라이드
persistence	persistence.pvc.annotations	""	PersistentVolumeClaim 어노테이션
persistence	persistence.pvc.existingClaim	""	사용할 기존 PVC 이름
persistence	persistence.pvc.storageClassName	efs-sc-eva-app	PVC용 StorageClass 이름
persistence	persistence.pvc.storage	30Gi	PersistentVolumeClaim 스토리지 크기
replicaCount	replicaCount	1	eva-app 파드 replica 개수
resources	resources	dict	컨테이너 리소스 요청 및 제한 설정
serviceAccount	serviceAccount.create	true	ServiceAccount 자동 생성 여부
serviceAccount	serviceAccount.name	""	ServiceAccount 이름
serviceAccount	serviceAccount.existingServiceAccount	""	기존 ServiceAccount 사용 여부
secret	secret.nameOverride	""	Kubernetes Secret 이름 오버라이드
secret	secret.data	""	Kubernetes Secret 데이터
service	service.nodePort	32010	eva-app 서비스 NodePort
service	service.internal.enabled	true	내부 서비스 사용 여부
tolerations	tolerations	[]	파드 toleration 설정
volumes	volumes.dshm.size	8Gi	/dev/shm 공유 메모리 크기

📂 On-premise 환경 values.yaml 설정 예시 (클릭)

# ============================================================
# On-Premise 환경용 values 오버라이드 파일
#
# 사용법:
#   helm install eva-app -n eva-app . -f values.yaml -f platform/onpremise/values.yaml
#   helm upgrade  eva-app -n eva-app . -f values.yaml -f platform/onpremise/values.yaml
# ============================================================

app:
  backendHost: "10.158.2.0"        # On-Premise 서버 IP
  backendSecure: false

  # On-Premise 환경
  infraProvider: onprem

  jwtSecret: secret

  vision:
    ml: "http://eva-vision.eva-vision:8000"

  agent:
    llm: "http://eva-agent.eva-agent"
    vlm: "http://eva-agent.eva-agent"

  license:
    activation_mode: "online"
    product_code: "eva"

    api_key: ""
    shared_key: ""


## On-Premise는 내부 MySQL Pod 사용
database:
  name: "eva"
  type: "internal"
  internal:
    service:
      nodePort: 32060
    password: passwd
    user: root


imagePullSecrets:
  enabled: true
  create: true
  password: "ECR Login Password"   # aws ecr get-login-password --region ap-northeast-2


## On-Premise는 hostPath로 로컬 스토리지 마운트
persistence:
  type: hostPath
  hostPath:
    path: "" # On-Premise 서버의 실제 경로, default는 /{RELEASE_NAME}


## On-Premise는 PV 별도 생성 불필요 (hostPath 사용)
pv:
  create: false


## On-Premise는 ServiceAccount 생성 필요
serviceAccount:
  create: true

☁️ Cloud(AWS EKS) 환경 values.yaml 설정 예시 (클릭)

# ============================================================
# Cloud (AWS) 환경용 values 오버라이드 파일
#
# 사용법:
#   helm install eva-app -n eva-app . -f values.yaml -f platform/cloud/values.yaml
#   helm upgrade  eva-app -n eva-app . -f values.yaml -f platform/cloud/values.yaml
# ============================================================

app:
  backendHost: "your-alb-or-domain.example.com"
  backendSecure: true # HTTPS 사용 시 true

  # Cloud 환경 (ncp 또는 aws)
  infraProvider: aws

  jwtSecret: secret

  agent:
    llm: "http://eva-agent.eva-agent"
    vlm: "http://eva-agent.eva-agent"

  vision:
    ml: "http://eva-vision.eva-vision:8000"

  license:
    activation_mode: "online"
    product_code: "eva"

    api_key: ""
    shared_key: ""


## Cloud는 외부 RDS 등 managed DB 사용 권장
database:
  name: "eva"
  type: "external"
  external:
    host: "your-rds-endpoint.rds.amazonaws.com"   # RDS 엔드포인트로 수정
    port: 3306
    password: passwd
    user: root


## ECR 인증 설정
## eks(aws) 내에서는 serviceAccount와 IRSA로 ECR 인증 처리 가능하므로, imagePullSecrets는 disabled 처리 가능
## nks(ncp) 내에서는 imagePullSecrets 사용해야함.
imagePullSecrets:
  enabled: true
  create: true
  password: "ECR Login Password"   # aws ecr get-login-password --region ap-northeast-2


## Cloud는 특정 노드 그룹에 배치
nodeSelector: {}
  # nodegroup: "ng-an2-eva-app"


## Cloud는 PV를 별도 생성하여 EFS에 연결
pv:
  create: true
  csi:
    driver: efs.csi.aws.com
    volumeHandle: fs-00000000000000000   # 실제 EFS FileSystem ID로 수정
  storageClassName: efs-sc-eva-app
  storage: 30Gi


## Cloud는 EFS 등 PVC 기반 스토리지 사용
persistence:
  type: pvc
  pvc:
    storageClassName: efs-sc-eva-app
    storage: 30Gi


## Cloud는 IRSA 등으로 ServiceAccount 관리 (필요에 따라 수정)
## eks(aws)는 권한을 부여받은 serviceAccount와 연결해야하므로, create: false로 설정하고 existingServiceAccount에 이름 입력
serviceAccount:
  create: false
  existingServiceAccount: ""

⚙️ Default values.yaml (클릭)

# eva-app의 기본 values 설정 파일입니다.
# YAML 형식의 파일입니다.
# 템플릿에 전달될 변수를 선언합니다.

## 온프레미스(On‑premise) 환경에서 설치하는 경우,
## database.type을 "internal"로,
## serviceAccount.create를 true로 설정하세요.
## persistence.type을 "hostPath"로 설정하여 데이터 볼륨을 마운트합니다.

##
## 애플리케이션 설정
## 애플리케이션 내부에서 사용되며 환경 변수로 접근 가능한 설정입니다.
#
app:
  ## 애플리케이션 기본 설정
  browserTitleName: "EVA"

  ## 백엔드 호스트 및 보안 설정
  backendHost: "127.0.0.1"
  backendSecure: false

  ## 애플리케이션이 실행되는 인프라 환경 지정 : [ onprem | ncp | aws ]
  infraProvider: onprem

  ## JWT_SECRET
  jwtSecret: secret

  ## Vision 설정
  vision:
    ml: "http://eva-vision.eva-vision:8000"

  ## Agent 설정
  agent:
    llm: "http://eva-agent.eva-agent"
    vlm: "http://eva-agent.eva-agent"

    requestTimeoutSeconds: 30

  ## 분석 데이터 만료 일수
  lifeCycle:
    analysisRetentionDays: 30

  ## 라이선스 설정
  license:
    activation_mode: "online"
    product_code: "eva"

    api_key: ""
    shared_key: ""

  ## 파이프라인에서 detector / perceptor 작업에 사용되는 동시 처리 스레드 수
  pipeline:
    detector:
      workerNum: 16

    ingester:
      ingesterStreamFPSForGrab: 30

    perceptor:
      workerNum: 2
      queueSize: 100

    streamer:
      dispatcherFaceAnonymizerEnabled: "true"
      annotationColorMode: "GRAY" # ["GRAY" | "COLOR"]

  ## 세션 설정
  session:
    uiSessionTimeoutMinutes: 60
    accessTokenExpireMinutes: 1440

  ## eva-app 환경을 위한 추가 설정
  additional: {}
  #  foo: bar


##
## Kubernetes 매니페스트 설정
## Helm 템플릿 변수로 사용되며 Kubernetes 리소스에 반영됩니다.
#

## 데이터베이스 설정
## type을 "internal"로 설정하면 클러스터 내부에 MySQL 파드를 배포합니다.
## type을 "external"로 설정하면 외부 데이터베이스에 연결합니다.
##
database:
  name: "eva"
  type: "internal" # ["internal", "external"]

  internal:
    service:
      nodePort: 32060
    password: passwd
    user: root

  external:
    host: "dbhost"
    port: 3306
    password: passwd
    user: root


image:
  repository: 339713051385.dkr.ecr.ap-northeast-2.amazonaws.com/mellerikat/release/eva-app
  
  # 이미지 pull 정책 설정
  pullPolicy: IfNotPresent
  
  # chart의 appVersion을 기본값으로 사용하는 이미지 태그
  # tag: "latest"


## 이미지 pull secret 설정
## ECR에서 eva-app 이미지를 가져올 때 사용됩니다.
imagePullSecrets:
  # enabled가 true이면 기존 secret을 사용하거나 새로 생성할 수 있습니다.
  enabled: true

  ExistingSecret: "" # eva-app-secret-regcred
  create: true

  ## image pull secret 이름
  ## 기본값: '{{ .Release.Name }}-secret-regcred'
  nameOverride: ""

  account: "339713051385"
  region: "ap-northeast-2"

  # regcred: "regcred/regcred.yaml"
  # dockerconfigjson: "regcred/regcred.json"

  ## 아래 단계를 완료한 후 ECR 비밀번호를 입력하세요.
  ## 1단계. AWS 설정
  ## 2단계. ECR 로그인 비밀번호 획득
  #### $ aws ecr get-login-password --region ap-northeast-2
  password: "ECR Login Password"


nodeSelector: {}
  # 파드를 스케줄링할 노드 그룹 지정
  # nodegroup: "ng-an2-eva-app"


pv:
  create: false
  ## 기본값: 'pv-{{ .Release.Name }}'
  nameOverride: ""

  annotations: {}
    # helm.sh/resource-policy: keep
  
  ## EFS용 CSI 설정 예시
  csi:
    driver: efs.csi.aws.com
    volumeHandle: fs-00000000000000000
  
  storageClassName: efs-sc-eva-app
  storage: 30Gi


persistence:
  type: hostPath # ["pvc", "hostPath"]
 
  ## persistence.type이 "hostPath"인 경우,
  ## 로컬 스토리지를 마운트합니다.
  ##
  hostPath:
    path: "" # "/eva-app"

  pvc:
    ## 기본값: 'pvc-{{ .Release.Name }}'
    nameOverride: ""

    annotations: {}
      # helm.sh/resource-policy: keep

    existingClaim: "" # 이미 생성된 PVC를 사용할 경우 이름 지정

    storageClassName: efs-sc-eva-app
    storage: 30Gi


replicaCount: 1


resources: {}
# requests:
#   nvidia.com/gpu: 1


serviceAccount:
  ## 배포 시 사용할 ServiceAccount 이름
  ## 기본값은 Helm Release 이름입니다.
  ## 온프레미스 환경이고 serviceAccount.create가 true일 때 생성됩니다.
  create: true
  name: "" # eva-app

  existingServiceAccount: ""


secret:
  nameOverride: ""

  ## Secret에 저장될 데이터
  data: {}


service:
  nodePort: 32010
  internal:
    enabled: true


tolerations: []
# - key: "key"
#   operator: "Equal"
#   value: "value"
#   effect: "NoSchedule"
#   tolerationSeconds: 0


volumes:
  ## /dev/shm 용 공유 메모리 볼륨
  dshm:
    size: 8Gi


## 디버그용 설정
## 아래 라인을 활성화하면 파드가 무한 대기(sleep) 상태로 유지됩니다.
# command: ["sleep", "infinity"]
# appVolumeMount:
  # path: /home/$(whoami)/path/to/eva-app/apps/backend/app/app
# webVolumeMount:
  # path: /home/$(whoami)/path/to/eva-app/apps/frontend/dist

4단계: 명령어 실행하여 설치

이제 설정을 적용하여 EVA App을 배포합니다. ECR 로그인 비밀번호를 자동으로 가져와 설치를 진행하는 명령어입니다.

# 1. AWS ECR 로그인 암호 가져오기
ecr_password=$(aws ecr get-login-password --region "ap-northeast-2")

# 2. 전용 네임스페이스 생성
kubectl create namespace eva-app

# 3. Helm 설치 시작
helm install eva-app eva-app/eva-app \
  -n eva-app \
  -f values.yaml \
  --set imagePullSecrets.password="${ecr_password}"

5단계: 설치 결과 확인

설치가 완료되면 터미널에 귀여운 기차 모양의 ASCII 아트와 함께 접속 URL이 출력됩니다.

level=WARN msg="unable to find exact version; falling back to closest available version" chart=eva-app requested="" selected=1.3.2
NAME: eva-app
LAST DEPLOYED: Mon Dec  1 14:12:25 2025
NAMESPACE: eva-app
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None
NOTES:
.  ___   __   __   ___              ___     _ __    _ __
  | __|  \ \ / /  /   \     o O O  /   \   | '_ \  | '_ \
  | _|    \ V /   | - |    o       | - |   | .__/  | .__/
  |___|   _\_/_   |_|_|   TS__[O]  |_|_|   |_|__   |_|__
_|"""""|_| """"|_|"""""| {======|_|"""""|_|"""""|_|"""""|
"`-0-0-'"`-0-0-'"`-0-0-'./o--000'"`-0-0-'"`-0-0-'"`-0-0-'

eva-app has been installed successfully!

Application Details:
  App Version   : 2.2.6
  Chart Version : 1.3.2
  Release Name  : eva-app
  Namespace     : eva-app

You can access "EVA App" using the following URL:
  EVA App        : http://10.158.2.75:32055

You can check helm instance by running:
  $ helm ls -n eva-app

You can check kubernetes objects by running:
  $ kubectl get all -n eva-app

For further information, visit https://mellerikat.com

아래 절차를 통해 DB 마이그레이션이 정상적으로 수행되었는지, 그리고 최신 버전의 스키마가 올바르게 적용되었는지 확인할 수 있습니다.

1. eva-app pod 이름 조회

kubectl get pods -n eva-app

2. 현재 DB에 적용된 Alembic Revision 정보 확인

kubectl exec -it {eva-app-xxxx} -n eva-app -- alembic current

위에서 확인한 Alembic Revision 값이 Release Note 에 있는 각 SW 버전별 Alembic Revision 값과 동일한지 확인합니다.