셀프 호스팅

셀프 호스팅 설치본은 사용자가 관리하는 호스트에서 Ephemeral 엔진과 실행 대시보드를 구동하고, 워커는 사용자의 AWS 계정에 있는 microVM에서, 모델은 사용자의 모델 공급자를 통해 실행합니다. Docker 이미지 하나와 그 문서를 받게 되며, 필요한 나머지 파일은 모두 이미지에서 내보낼 수 있습니다. Ephemeral의 배포 라이선스가 필요합니다.

실행하는 구성 요소

고객용 웹사이트, 계정, 결제 서비스는 셀프 호스팅 설치본에 포함되지 않으며, 소스 코드도 포함되지 않습니다. 사용자는 엔진 API 키로 대시보드에 로그인합니다.

이미지에는 운영자 가이드 전체가 들어 있습니다. 아래 단계는 그 요약입니다. 정확한 명령, 예상 출력, 업그레이드, 백업, 문제 해결은 가이드를 따르세요.

docker run --rm ephemer.al/ephemeral/self-hosted:VERSION setup docs > SELF-HOSTING.md

시작하기 전에

• Docker Compose 2.24 이상이 포함된 Docker, 그리고 Session Manager 플러그인이 설치된 AWS CLI v2.
• Lambda microVM을 사용할 수 있는 리전의 AWS 계정, 그리고 IAM 역할이 포함된 CloudFormation 스택을 만들 수 있는 권한.
• 호스트에 연결할 수 있는 도메인 이름.
• OpenAI 호환 추론 엔드포인트와 API 키.
• 조직의 사용 권한. 계약을 체결하면 Ephemeral이 부여합니다. 배포 라이선스를 참고하세요.

설치

1. 설치본 등록

   고객 포털에서 배포를 열고 production-eu와 같은 이름으로 이 설치본을 등록합니다. 머신 ID와 라이선스 토큰은 Ephemeral이 만듭니다. 라이선스 파일 다운로드를 선택해 토큰, 머신 ID, 배포 ID를 보관하세요. 토큰은 한 번만 표시됩니다.

2. 이미지 가져오기

   배포 ID를 사용자 이름으로, 라이선스 토큰을 비밀번호로 사용해 레지스트리에 로그인한 다음 릴리스를 가져옵니다. 버전에는 앞에 v를 붙이지 않습니다.

   터미널

   export EPHEMERAL_VERSION=0.1.0
   read -rs LICENSE_TOKEN
   printf '%s' "$LICENSE_TOKEN" | docker login ephemer.al -u dep_YOUR_DEPLOYMENT_ID --password-stdin
   docker pull ephemer.al/ephemeral/self-hosted:$EPHEMERAL_VERSION

3. 설치 파일 내보내기

   터미널

   mkdir -p ephemeral && cd ephemeral
   docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/out" \
     ephemer.al/ephemeral/self-hosted:$EPHEMERAL_VERSION setup all /out

   파일	용도
   compose.yaml	PostgreSQL, 애플리케이션, Caddy. 이 릴리스에 고정되어 있습니다
   compose.evaluation.yaml	AWS 없이 컴퓨터 한 대에서 사용해 보기 위한 오버라이드
   Caddyfile	인그레스 라우트
   .env	새로 생성된 시크릿이 들어 있는 설정. 이후에 다시 내보내도 덮어쓰지 않습니다
   ephemeral-aws.yaml	AWS 리소스용 CloudFormation 템플릿
   ephemeral-worker-VERSION.zip	AWS가 microVM 이미지로 빌드하는 컴파일된 워커
   SELF-HOSTING.md	운영자 가이드

4. AWS 리소스 만들기

   워커 ZIP을 계정의 비공개 S3 버킷에 업로드한 다음 스택을 만듭니다. 스택은 격리된 워커 서브넷이 있는 VPC, DNS 방화벽, microVM 이미지와 네트워크 커넥터, 암호화된 스토리지 버킷, 최소 권한의 호스트 IAM 역할을 만들고, 기본적으로 Elastic IP와 암호화된 데이터 볼륨이 있는 t4g.small Amazon Linux 호스트도 만듭니다. 워커 이미지를 빌드하는 데 15~30분이 걸리며, 스택은 비용이 발생하는 리소스를 만듭니다.

   터미널

   aws s3 cp "ephemeral-worker-$EPHEMERAL_VERSION.zip" "s3://YOUR_ARTIFACT_BUCKET/"
   aws cloudformation create-stack --stack-name ephemeral \
     --template-body file://ephemeral-aws.yaml --capabilities CAPABILITY_IAM \
     --parameters ParameterKey=Domain,ParameterValue=ephemeral.example.com \
       ParameterKey=WorkerArtifactBucket,ParameterValue=YOUR_ARTIFACT_BUCKET \
       ParameterKey=WorkerArtifactKey,ParameterValue="ephemeral-worker-$EPHEMERAL_VERSION.zip" \
       ParameterKey=HostImageId,ParameterValue=AL2023_ARM64_AMI
   aws cloudformation wait stack-create-complete --stack-name ephemeral
   aws cloudformation describe-stacks --stack-name ephemeral \
     --query "Stacks[0].Outputs[?OutputKey=='EngineEnvironment'].OutputValue" --output text | tr ' ' '\n'

   마지막 명령은 엔진용 AWS 설정을 출력합니다. 도메인의 DNS A 레코드를 스택 출력 HostPublicIp로 지정하세요.

5. 호스트 설정

   aws ssm start-session --target과 스택 출력 HostInstanceId로 접속한 다음, /srv/ephemeral/install에서 레지스트리 로그인과 내보내기를 다시 수행합니다. .env에서 다음 항목을 수정합니다.

   설정	값
   EPHEMERAL_DOMAIN	호스트 이름. 예: ephemeral.example.com
   EPHEMERAL_LICENSE_TOKEN	첫 번째 단계에서 받은 토큰
   EPHEMERAL_MACHINE_ID	첫 번째 단계에서 등록한 그대로의 머신 ID
   INFERENCE_BASE_URL	OpenAI 호환 엔드포인트
   INFERENCE_API_KEY	해당 엔드포인트의 API 키
   EPHEMERAL_DEFAULT_MODEL	실행에서 모델을 지정하지 않을 때 사용하는 모델
   AWS 설정	스택이 출력한 다섯 줄: AWS_REGION, EPHEMERAL_S3_BUCKET, 그리고 EPHEMERAL_MICROVM_… 값 세 개

   내보내기 과정에서 암호화 마스터 키, 부트스트랩 관리자 키, 데이터베이스 비밀번호가 생성되었습니다. .env의 사본을 시크릿 관리자에 보관하세요. 마스터 키가 없으면 저장된 자격 증명과 실행 페이로드를 읽을 수 없습니다. AWS 자격 증명은 호스트의 인스턴스 프로파일이 제공합니다.

6. 설치본 시작

   Caddy가 HTTPS 인증서를 발급받습니다. PostgreSQL과 내부 API는 외부에 공개되지 않습니다.

   터미널

   docker compose pull
   docker compose up -d

   엔진은 시작할 때 라이선스를 검증하며, 라이선스가 유효하지 않거나 설정된 동시 실행 수가 라이선스를 초과하면 시작을 거부합니다.

7. 첫 조직 만들기

   새 설치본에는 API 키가 없습니다. 설치 디렉터리에서 한 번 실행하되, my-organization을 원하는 조직 ID로 바꾸세요. 부트스트랩 키를 컨테이너 안에서 읽으므로 키가 셸 기록에 남지 않습니다.

   터미널

   docker compose exec -T app node --input-type=module - <<'NODE'
   if (process.env.EPHEMERAL_MODE !== 'self-hosted') {
     throw new Error('Bootstrap requires EPHEMERAL_MODE=self-hosted');
   }
   const adminKey = process.env.EPHEMERAL_ADMIN_KEY;
   if (!adminKey) throw new Error('EPHEMERAL_ADMIN_KEY is not configured');
   const response = await fetch('http://127.0.0.1:8080/admin/organizations', {
     method: 'POST',
     headers: {
       Authorization: `Bearer ${adminKey}`,
       'Content-Type': 'application/json',
     },
     body: JSON.stringify({id: 'my-organization'}),
   });
   const result = await response.json();
   if (!response.ok) throw new Error(result.error || `Bootstrap failed (${response.status})`);
   console.log(JSON.stringify(result, null, 2));
   NODE

   응답에는 조직의 id, 새 소유자 키의 key_id와 role, 그리고 eph_로 시작하는 key 자체가 들어 있습니다. 키는 지금 저장하세요. 나중에 다시 확인할 수 없습니다. 활성 키가 있는 조직에 대해 명령을 다시 실행하면 409를 반환합니다.

8. 로그인

   HTTPS 주소를 열고 엔진 API 키에 키를 입력합니다. 추가 member 키와 admin 키는 API 키에서 만듭니다. 설정 파일의 부트스트랩 관리자 키는 조직을 만드는 데만 쓰이며, 로그인하거나 API를 호출할 수 없습니다.

컴퓨터 한 대에서 사용해 보기

AWS 없이 사용하려면 평가용 오버라이드를 추가하세요. 그러면 에이전트가 로컬 러너로 애플리케이션 컨테이너 안에서 실행되며, 대시보드는 http://localhost:8000에서 일반 HTTP로만 제공됩니다. 라이선스는 여전히 필요하므로 이를 위한 별도의 배포를 등록하세요.

docker compose -f compose.yaml -f compose.evaluation.yaml up -d

호스팅 서비스와의 차이

업데이트와 백업

업그레이드하려면 새 릴리스의 워커 ZIP을 업로드하고 그 키로 스택을 업데이트하세요. 그런 다음 호스트에서 새 릴리스의 파일을 내보내고, .env에 EPHEMERAL_VERSION과 새 EPHEMERAL_MICROVM_IMAGE_VERSION을 설정한 뒤 docker compose up -d를 실행합니다. 진행 중인 실행에는 끝날 때까지 최대 5분을 줍니다. 그 후에도 활성 상태인 실행은 interrupted로 표시되며 다시 시도하지 않으므로 외부 작업이 반복되는 일은 없습니다. 데이터베이스 마이그레이션은 자동으로 실행됩니다.

데이터베이스와 암호화 마스터 키를 모두 백업하세요. 마스터 키를 잃으면 저장된 연결 자격 증명과 실행 페이로드를 읽을 수 없게 됩니다. 스택이 만든 호스트는 매일 데이터베이스를 자신의 S3 버킷에 백업합니다.