시작하기
5분 만에 정적 사이트를 AWS에 배포해 보세요.
필요 조건
- Node.js 18 이상
- AWS 계정
- AWS CLI 인증 설정 (
aws configure)
설치
bash
npm install -g scf-deploy설치 없이 바로 사용하려면:
bash
npx scf-deploy initAWS 인증 설정
SCF가 AWS 리소스를 생성하려면 인증 정보가 필요합니다.
1. IAM 사용자 생성 및 Access Key 발급
아직 Access Key가 없다면 AWS 콘솔에서 생성하세요:
- AWS IAM 콘솔에 로그인
- 사용자 → 사용자 생성 클릭
- 사용자 이름 입력 (예:
scf-deploy-user) - 직접 정책 연결 선택 후 아래 권한 추가:
AmazonS3FullAccessCloudFrontFullAccess
- 사용자 생성 완료 후 보안 자격 증명 탭 이동
- 액세스 키 만들기 → CLI 선택
- Access Key ID와 Secret Access Key 저장
🔒 보안 주의: Secret Access Key는 생성 시 한 번만 표시됩니다. 안전하게 보관하세요.
2. AWS CLI 설정
Access Key를 로컬에 등록합니다:
bash
aws configure아래 정보를 입력하세요:
AWS Access Key ID: AKIA... # 발급받은 Access Key ID
AWS Secret Access Key: wJalr... # 발급받은 Secret Access Key
Default region name: ap-northeast-2 # 서울 리전
Default output format: json
설정 확인:
bash
# 인증 정보가 올바른지 테스트
aws sts get-caller-identity정상이면 계정 정보가 출력됩니다:
json
{
"UserId": "AIDA...",
"Account": "123456789012",
"Arn": "arn:aws:iam::123456789012:user/scf-deploy-user"
}3. 인증 방법 선택
SCF는 세 가지 인증 방법을 지원합니다:
| 방법 | 사용 시점 | 명령어 |
|---|---|---|
| AWS CLI 설정 | 로컬 개발 (기본) | aws configure |
| 환경 변수 | CI/CD 환경 | export AWS_ACCESS_KEY_ID=... |
| 프로필 지정 | 여러 AWS 계정 사용 | --profile 옵션 |
환경 변수 사용 (CI/CD)
bash
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=wJalr...
export AWS_REGION=ap-northeast-2
npx scf-deploy deploy프로필 사용 (여러 계정 관리)
bash
# 프로필 추가
aws configure --profile production
# 배포 시 프로필 지정
npx scf-deploy deploy --profile production4. 최소 권한 정책 (권장)
보안을 위해 필요한 권한만 부여하세요:
json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "S3Access",
"Effect": "Allow",
"Action": [
"s3:CreateBucket",
"s3:PutObject",
"s3:GetObject",
"s3:DeleteObject",
"s3:ListBucket",
"s3:PutBucketPolicy",
"s3:PutBucketWebsite",
"s3:GetBucketLocation"
],
"Resource": [
"arn:aws:s3:::my-site-*",
"arn:aws:s3:::my-site-*/*"
]
},
{
"Sid": "CloudFrontAccess",
"Effect": "Allow",
"Action": [
"cloudfront:CreateDistribution",
"cloudfront:UpdateDistribution",
"cloudfront:GetDistribution",
"cloudfront:CreateInvalidation",
"cloudfront:ListDistributions"
],
"Resource": "*"
}
]
}💡 팁: my-site-* 부분을 실제 버킷 이름 패턴으로 변경하세요.
인증 문제 해결
| 에러 메시지 | 원인 | 해결 방법 |
|---|---|---|
Credentials not found | 인증 미설정 | aws configure 실행 |
Access Denied | 권한 부족 | IAM 정책 확인 |
Invalid credentials | 잘못된 키 | Access Key 재발급 |
자세한 문제 해결은 트러블슈팅 가이드를 참고하세요.
첫 번째 배포
1. 프로젝트 초기화
bash
cd your-project
npx scf-deploy initscf.config.ts 파일이 생성됩니다:
typescript
import { defineConfig } from 'scf-deploy';
export default defineConfig({
app: 'my-site',
region: 'ap-northeast-2',
s3: {
bucketName: 'my-site-bucket-abc123',
},
cloudfront: {
enabled: true,
},
});2. 배포 실행
bash
npx scf-deploy deploy실행 결과:
✓ Building project...
✓ AWS credentials verified
✓ S3 bucket ready
↑ Uploading files... [████████████████████] 100%
✓ CloudFront invalidation created
✓ Deployment complete!
URL: https://d1234567890abc.cloudfront.net
빌드 폴더 자동 감지
SCF는 프레임워크에 맞는 빌드 폴더를 자동으로 찾습니다:
| 프레임워크 | 빌드 폴더 |
|---|---|
| Vite, Vue | dist |
| Create React App | build |
| Next.js (정적 빌드) | out |
| Nuxt 3 | .output/public |
직접 지정하려면:
typescript
s3: {
bucketName: 'my-bucket',
buildDir: './dist',
}