워크샵의 질문을,
한곳에서 함께.

링크 하나로, 바로 참여하세요.

입장 화면은 워크샵의 설정에 따라 달라집니다. 닉네임 입력란이 보이면 아래 순서대로 참여하세요.

1. 운영자가 공유한 공용 링크 열기

   현재 워크샵 참가자 입장을 엽니다. 별도로 배포한 워크샵은 해당 AppUrl로 접속합니다. 닉네임 모드에서는 모든 참가자가 같은 주소를 사용합니다.

2. 워크샵에서 사용할 닉네임 입력

   예: 구름고래, 3조-민트. 닉네임은 다른 참가자에게 표시되므로 실명 대신 워크샵용 이름을 권장합니다.

3. 입장 버튼 누르기

   참가자용 AWS 계정이나 Cognito ID·비밀번호 없이 입장합니다. 먼저 공지를 확인하고 질문 채널로 이동하세요.

채널과 질문 사용하기

Enter로 보내고 Shift + Enter로 줄을 바꿉니다. Markdown 코드 블록을 사용하면 오류 로그와 명령어를 읽기 쉽게 전달할 수 있습니다. 상단에서 한국어·영어와 다크·프로젝터 모드를 전환할 수 있습니다.

파일 첨부와 미리보기

입력창의 📎 버튼으로 파일을 선택하고 짧은 설명을 작성한 뒤 보내기를 누르세요. 채널 입력창에는 클립보드 이미지도 붙여넣을 수 있습니다. 이미지·PDF·HTML은 채팅 안에서 미리 볼 수 있고, 스레드 답글과 운영자 메시지에도 첨부할 수 있습니다.

HTML 미리보기에서는 스크립트가 실행되지 않습니다. 파일을 올렸다는 것만으로 AI의 참고 문서가 되지는 않습니다. AI 문서는 운영자가 별도로 등록합니다.

AI 도우미에게 물어보기

왼쪽의 AI 도우미를 열고 랩 가이드에 대한 질문을 입력하세요. 답변은 생성되는 대로 표시되며, 참고 문서가 있으면 함께 표시됩니다. 도움됨 또는 가이드에 없음으로 피드백을 남길 수 있습니다.

닉네임과 재접속, 알아둘 점.

운영자는 닉네임과 별도의 참가자 ID를 함께 확인합니다. 닉네임으로 입장해도 운영자 권한이 부여되지 않으며, 운영자는 항상 별도 로그인 경로를 사용합니다.

워크샵 계정에 배포하기.

앱은 CloudFront·WAF → ALB → ECS Fargate 구조로 실행되며, DynamoDB에 상태를 저장합니다. Cognito는 운영자 인증에, S3는 첨부·가이드·내보내기에, Bedrock은 AI 답변에 사용합니다. GitHub Pages에는 이 설명서가 게시되고 실제 앱은 AWS에서 실행됩니다.

1. 배포 환경 준비

Git, Node.js 22, npm, AWS CLI, 실행 중인 Docker와 linux/arm64 이미지 빌드 환경이 필요합니다. x86 호스트라면 Docker의 ARM 빌드 지원도 준비하세요. 사용할 AWS 프로필에 CDK 리소스를 생성할 권한과 선택한 리전의 Bedrock 모델 접근 권한이 있어야 합니다.

다음 예제는 Bash 기준입니다. 값을 실제 환경으로 바꾸고 같은 터미널에서 순서대로 실행하세요. 루트의 npm ci는 공통 lockfile과 npm workspaces 설정에 따라 app·infra·web 의존성을 함께 설치합니다.

git clone https://github.com/Atom-oh/aws-workshop-chat.git
cd aws-workshop-chat
npm ci

WORKSHOP_AWS_PROFILE="your-workshop-profile"
WORKSHOP_REGION="ap-northeast-2"
WORKSHOP_BEDROCK_REGION="us-east-1"
WORKSHOP_NAME="my-workshop"
WORKSHOP_MODEL_ID="REPLACE_WITH_ACCESSIBLE_MODEL_OR_INFERENCE_PROFILE_ID"

aws sts get-caller-identity --profile "$WORKSHOP_AWS_PROFILE"

반환된 계정과 역할이 워크샵 대상인지 확인하세요. WORKSHOP_MODEL_ID는 대상 Bedrock 리전에서 접근 가능한 Converse 지원 모델 또는 추론 프로필 ID로 교체합니다. 위 값은 자리표시자입니다. 워크샵 환경에서 허용되는 리전에 맞춰 WORKSHOP_BEDROCK_REGION도 설정하세요.

2. 가이드 문서와 CDK 설정 준비

저장소의 guide/ 예제 Markdown을 실제 실습 가이드로 교체합니다. 다음은 참가자 120명, 닉네임 입장, 대규모 채널 구성 예제입니다.

cd infra
WORKSHOP_CONTEXT=(
  --context "workshopName=$WORKSHOP_NAME"
  --context "scale=large"
  --context "bedrockModelId=$WORKSHOP_MODEL_ID"
  --context "bedrockRegion=$WORKSHOP_BEDROCK_REGION"
  --context "adminUsername=admin@ws"
  --context "participantPassphrase=legacy-unused-setting"
  --context "participantCount=120"
  --context "participantAuthMode=nickname"
  --context "enableKnowledgeBase=true"
)

WORKSHOP_ACCOUNT="$(aws sts get-caller-identity \
  --profile "$WORKSHOP_AWS_PROFILE" --query Account --output text)"

AWS_REGION="$WORKSHOP_REGION" npx cdk bootstrap \
  "aws://$WORKSHOP_ACCOUNT/$WORKSHOP_REGION" \
  "aws://$WORKSHOP_ACCOUNT/us-east-1" \
  "aws://$WORKSHOP_ACCOUNT/$WORKSHOP_BEDROCK_REGION" \
  --profile "$WORKSHOP_AWS_PROFILE" "${WORKSHOP_CONTEXT[@]}"

각 계정·리전의 CDK bootstrap은 최초 한 번 필요합니다. 앱 리전 외에 CloudFront용 WAF가 배포되는 us-east-1, Knowledge Base가 배포되는 Bedrock 리전도 준비합니다. 이미 bootstrap된 환경은 재사용할 수 있습니다.

3. 배포하고 접속 주소 확인

AWS_REGION="$WORKSHOP_REGION" npx cdk deploy --all \
  --profile "$WORKSHOP_AWS_PROFILE" \
  "${WORKSHOP_CONTEXT[@]}" \
  --outputs-file workshop-outputs.json

변경 내용을 확인해 CDK의 승인을 진행합니다. CDK가 ARM64 컨테이너를 빌드·업로드하고 관련 스택을 배포합니다. 배포가 끝나면 workshop-outputs.json과 터미널 출력에서 아래 값을 확인하세요. 출력 파일에는 운영용 리소스 정보가 있으므로 공개 저장소에 커밋하지 마세요.

4. 참가자를 초대하기 전에 확인

1. OperatorConsoleUrl에서 운영자 로그인 후 가이드 문서를 재인덱싱합니다.
2. 별도 브라우저로 AppUrl을 열어 닉네임 입장, 질문 작성·답글, 파일 첨부를 확인합니다.
3. AI가 실제 가이드에 근거해 답변하는지 확인하고, 운영자의 질문 보드와 내보내기도 점검합니다.
4. 확인이 끝나면 참가자에게 공용 링크를 배포합니다.

docker compose up --build

기존 환경에 닉네임 입장 반영하기.

배포에 사용한 소스의 최신 main을 받고 기존 계정·앱 리전·workshopName·Bedrock 설정·도메인·인원·관리자 설정을 유지하세요. 위의 예제 값을 기존 환경에 그대로 덮어쓰지 마세요. 워크샵 이름이나 리전을 바꾸면 기존 스택 업데이트가 아닌 새 배포가 될 수 있습니다.

1. 기존 배포에서 사용한 설정으로 WORKSHOP_CONTEXT를 구성하고 participantAuthMode=nickname을 명시합니다.
2. 아래 cdk diff에서 리소스 변경을 확인하고 cdk deploy --all로 반영합니다.
3. 기존 운영자 로그인과 새 참가자 입장을 확인한 뒤 공용 AppUrl을 다시 안내합니다.

# 저장소 루트에서, 작업 중인 변경을 먼저 정리한 뒤 실행
git switch main
git pull --ff-only
npm ci
cd infra

# 위 안내대로 기존 배포의 변수와 WORKSHOP_CONTEXT를 구성한 상태
AWS_REGION="$WORKSHOP_REGION" npx cdk diff --all \
  --profile "$WORKSHOP_AWS_PROFILE" "${WORKSHOP_CONTEXT[@]}"
AWS_REGION="$WORKSHOP_REGION" npx cdk deploy --all \
  --profile "$WORKSHOP_AWS_PROFILE" "${WORKSHOP_CONTEXT[@]}"

운영은 질문 보드에서 시작하세요.

현재 워크샵 운영자 질문 보드를 엽니다. 별도 배포에서는 AppUrl/operator 또는 입장 화면의 운영자 로그인으로 이동합니다. 배포 출력의 운영자 ID와 Secrets Manager에서 조회한 비밀번호를 사용하세요. 참가자가 닉네임을 사용해도 운영자는 항상 Cognito로 인증합니다.

닉네임 참여 현황의 기준 인원은 목표 인원과 실제 등록 수 중 큰 값입니다. 목표 120명에 125개 ID가 등록되면 기준도 125명이 됩니다. 등록 수는 현재 온라인 인원이나 중복을 제거한 실참석자 수와 다릅니다.

실습 가이드를 AI에 연결하기.

운영자 화면의 랩 가이드 문서는 AI 참고 자료 관리용입니다. 참가자에게 파일 목록을 보여주는 자료실은 아닙니다. 참가자에게도 문서를 배포하려면 공지에 링크나 파일을 따로 게시하세요.

1. 파일 선택으로 실제 가이드 업로드

   KB 사용 시 TXT·Markdown·HTML·Word·CSV·Excel·PDF는 최대 50 MB, JPEG·PNG는 최대 3.75 MB입니다. 채팅 첨부 제한과 다릅니다.

2. 사용 중 / 제외 상태 확인

   해당 워크샵에서 사용할 문서만 활성화합니다. 운영 중 추가한 파일은 이후 CDK 배포에서도 유지됩니다.

3. 지금 재인덱싱 실행

   KB 사용 시 최초 배포 후와 문서 업로드·제외·삭제 후에 실행합니다. 업로드만으로 KB의 수집이 시작되지는 않습니다. 문서별 인덱싱됨 상태와 실패 문서 수를 확인하고 AI 질문으로 결과를 검증하세요.

S3에 직접 업로드할 때는 GuideBucketPath의 guide/ 경로를 사용하고, 출력된 GuideSyncCommand에 배포 프로필을 추가해 실행합니다. 이 명령은 앱 리전이 아닌 Bedrock 리전에서 수집합니다.

종료 전에 결과를 내려받으세요.

운영자 상단에서 지금 내보내기를 누르고 완료 후 다운로드로 xlsx를 저장합니다. Questions, AI_Queries, Participants, Timeline 데이터 시트와 생성 시각·시트별 행 수를 담은 Meta까지 총 5개 시트가 생성됩니다. 참가자 시트에서 ID와 닉네임을 연결해 확인할 수 있습니다.

앱은 15분마다 S3의 exports/latest.xlsx를 갱신하지만, 워크샵 계정 밖에 자동 보관하지는 않습니다. xlsx는 첨부파일 원본을 묶은 백업이 아니므로 필요한 미디어와 가이드도 별도로 저장하세요.

aws sts get-caller-identity --profile "$WORKSHOP_AWS_PROFILE"
AWS_REGION="$WORKSHOP_REGION" npx cdk destroy --all \
  --profile "$WORKSHOP_AWS_PROFILE" "${WORKSHOP_CONTEXT[@]}"

막혔을 때 확인할 것.