AdoptAI Infra

AdoptAI의 로컬 개발 및 배포 환경을 관리하는 Docker Compose 구성입니다. 기본 로컬 환경은 실제 STT/Vision 모델 대신 mock 서비스를 사용하므로, 모델이나 GCP 자격증명 없이 FE와 BE를 함께 실행할 수 있습니다.

빠른 시작 (Windows PowerShell)

Windows에는 make가 기본으로 설치되어 있지 않습니다. 따라서 PowerShell에서는 아래 Docker Compose 명령을 사용하세요. make 설치 여부와 관계없이 같은 결과입니다.

1. 사전 조건

• Docker Desktop이 실행 중이어야 합니다. Compose v2가 포함된 버전이 필요합니다.
• 이 저장소와 서비스 저장소가 같은 상위 폴더에 있어야 합니다.

adoptai/
├── BE/
├── FE/
├── STT/
├── VISION/
└── infra/     # 이 저장소

현재 폴더가 infra인지와 Docker Compose를 사용할 수 있는지 확인합니다.

Get-Location
docker compose version

2. 환경 파일 만들기

Copy-Item deploy/.env.example deploy/.env

mock 로컬 환경은 .env의 S3, GCP, 소셜 로그인 값을 비워 두어도 실행됩니다. 운영용 비밀값은 절대 커밋하지 마세요.

3. 로컬 환경 실행

infra 폴더에서 실행합니다.

docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.local.yml --profile ml up -d

이는 Linux/macOS에서의 make local과 동일합니다. 첫 실행에는 FE, BE, mock 이미지를 빌드하므로 시간이 걸릴 수 있습니다.

실행 상태를 확인합니다.

docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.local.yml --profile mock ps

접속 주소:

• 앱: http://localhost/
• FE 직접 접속: http://localhost:3000/
• BE API 문서: http://localhost:8000/docs
• Postgres: localhost:5432 (adoptai / adoptai)

4. 로그 보기와 종료

# 로그 보기 (Ctrl+C는 로그 보기만 종료하며 컨테이너는 계속 실행됨)
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.local.yml --profile mock logs -f

# 컨테이너와 네트워크 종료 (볼륨의 DB 데이터는 유지됨)
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.local.yml down

# ML 프로필까지 함께 내릴 때
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.local.yml --profile ml down

docker compose down만 입력하면 no configuration file provided: not found 오류가 납니다. 반드시 -f 옵션으로 파일 경로를 지정해야 합니다.

처음 저장소를 받는 경우

서비스 저장소를 아직 받지 않았다면, 이 저장소의 상위 폴더에 나란히 clone합니다.

git clone https://github.com/AI-Rookie-AdoptAI/AdoptAI-BE ../BE
git clone https://github.com/AI-Rookie-AdoptAI/AdoptAI-FE ../FE
git clone https://github.com/AI-Rookie-AdoptAI/AdoptAI-STT ../STT
git clone https://github.com/AI-Rookie-AdoptAI/AdoptAI-VISION ../VISION

Git Bash 또는 WSL을 사용 중이면 다음 스크립트로도 같은 작업을 할 수 있습니다.

./scripts/bootstrap.sh

이미 clone된 저장소는 스크립트가 건너뜁니다. 이 스크립트는 Bash용이므로 PowerShell에서 ./scripts/bootstrap.sh를 직접 실행하면 안 됩니다.

Make를 사용할 수 있는 환경

GNU Make가 설치된 macOS/Linux, 또는 Make가 PATH에 등록된 Windows 터미널에서는 아래 별칭을 사용할 수 있습니다.

make local       # mock으로 로컬 실행
make local-ml    # 실제 STT/Vision 모델 포함
make logs        # 전체 로그 보기
make down        # 종료

Windows PowerShell에서 'make' ... 인식되지 않습니다 오류가 나면 Make가 설치되어 있지 않은 것입니다. 설치하지 않아도 위의 Docker Compose 명령으로 개발을 계속할 수 있습니다. make bootstrap과 make sync는 Bash 스크립트를 실행하므로 Windows에서는 Git Bash 또는 WSL에서 실행하세요.

실제 모델로 통합 테스트

실제 STT/Vision CPU 추론을 포함해 실행하려면 deploy/.env에 Vertex AI 관련 값을 설정하고 GCP 서비스 계정 JSON 경로를 준비해야 합니다.

docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.local.yml --profile ml up -d

필요한 값과 형식은 deploy/.env.example을 참고하세요.

• GCP_PROJECT_ID
• GCP_LOCATION
• GCP_CREDENTIALS_FILE — 호스트의 서비스 계정 JSON 경로
• STT_INTERNAL_API_KEY — BE와 STT에서 같은 값을 사용

첫 모델 실행은 모델 다운로드 때문에 용량과 시간이 더 필요합니다.

업로드 저장소

기본 로컬 환경은 파일을 Docker 볼륨에 저장하고 /static으로 서빙합니다. 아래 세 값이 모두 채워졌을 때만 Supabase Storage의 S3 호환 엔드포인트를 사용합니다.

S3_ENDPOINT_URL=https://<project-ref>.storage.supabase.co/storage/v1/s3
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

추가로 SUPABASE_URL, public 버킷 이름(S3_BUCKET), 실제 Supabase 프로젝트 리전(S3_REGION)을 맞춰야 합니다. S3 키는 Supabase의 Storage → S3 Access Keys에서 발급하며, anon/service key가 아닙니다. 리전이 다르면 SigV4 서명 검증에 실패합니다.

자주 발생하는 문제

증상	확인할 사항
make를 찾을 수 없음	정상입니다. Windows PowerShell에서는 이 문서의 docker compose ... 명령을 사용하세요.
docker 또는 docker compose를 찾을 수 없음	Docker Desktop을 설치·실행한 뒤 새 PowerShell 창을 여세요.
build context ... FE/BE ... not found	BE, FE, STT, VISION이 infra와 같은 상위 폴더에 있는지 확인하세요.
env file ... deploy/.env not found	Copy-Item deploy/.env.example deploy/.env를 먼저 실행하세요.
포트 80/3000/5432/8000 충돌	해당 포트를 사용 중인 프로세스 또는 기존 컨테이너를 종료한 뒤 다시 실행하세요.

배포 구성 확인

실제 컨테이너를 시작하지 않고 배포용 Compose 구성을 렌더링합니다.

docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.prod.yml --env-file deploy/versions.env --profile ml config

make prod-config은 위 명령 전에 Bash 기반 버전 검증 스크립트도 실행합니다. Windows에서 동일 검증까지 수행하려면 Git Bash 또는 WSL에서 make prod-config를 사용하세요.

CI/CD 상태와 필요한 GitHub/AWS 설정

각 서비스 저장소의 main push는 이미지를 GHCR에 push한 뒤 Infra 저장소에 repository_dispatch를 보냅니다. Infra의 deploy.yml은 받은 태그로 deploy/versions.env를 갱신합니다.

실제 동작 전 다음 설정이 필요합니다.

항목	위치	용도
INFRA_DISPATCH_PAT	FE/BE/STT/VISION repository 또는 organization secret	Infra repository dispatch 및 versions.env 갱신 인증. Infra에 contents:write, metadata:read 권한이 필요합니다.
GITHUB_TOKEN	각 서비스 GitHub Actions	GHCR 이미지 push. workflow의 packages: write 권한을 사용합니다.
AWS_DEPLOY_ROLE_ARN	Infra secret	GitHub Actions OIDC로 AssumeRole할 IAM 역할 ARN
AWS_REGION	Infra variable	배포 리전
EC2_TAG_NAME	Infra variable	SSM 대상 EC2의 Name 태그 값
/adoptai/ghcr-read-pat	AWS SSM Parameter Store SecureString	EC2의 GHCR 이미지 pull용 read-only PAT

현재 Terraform 모듈과 Terraform workflow는 아직 구성되어 있지 않습니다. 따라서 EC2/IAM 인프라가 준비되기 전에는 deploy-to-ec2 단계가 성공하지 않습니다.