# 솜사탕클라우드 AI 컨텍스트

기능 검증 기준: 2026-07-24 KST

이 문서는 AI가 솜사탕클라우드에 배포할 애플리케이션을 준비하고 문제를 분석할 때 사용하는 고객용 제품 컨텍스트입니다. 이 문서에 없는 기능은 지원된다고 추측하지 말고 현재 대시보드나 공식 Docs에서 다시 확인하세요.

## 제품 소개

솜사탕클라우드는 GitHub 저장소의 웹 애플리케이션을 빌드하고 실행해 HTTPS 주소로 공개할 수 있게 해주는 한국어 클라우드 배포 플랫폼입니다.

주 사용자는 바이브코딩으로 웹앱을 만든 창업자와 클라우드 운영 경험이 많지 않은 개발자입니다.

## 현재 주요 기능

- 이메일 또는 GitHub 로그인
- GitHub App을 통한 저장소와 실제 브랜치 선택
- GitHub 저장소의 수동 배포와 선택한 브랜치 push 자동 배포
- 빌드 명령, 시작 명령, Root Directory와 Healthcheck Path 설정
- HTTPS 기본 서비스 주소 제공
- 서비스별 환경변수 저장
- 관리형 PostgreSQL 생성, 외부 접속정보 확인과 서비스별 연결
- 사용자 도메인과 HTTPS 연결
- 같은 프로젝트 서버 서비스 사이의 관리형 내부 연결
- 배포 상태, 빌드 로그와 런타임 로그 확인
- 실패 배포 재시도와 과거 정상 배포로 롤백
- 배포된 웹페이지를 확인하는 AI 하자점검 베타
- 결제 화면에서 기능별 사용량, 한도, 남은 양 또는 초과량 확인

## 기본 사용 흐름

1. 솜사탕클라우드 계정과 GitHub를 연결합니다.
2. 프로젝트를 만들고 GitHub 저장소, 빈 서비스 또는 PostgreSQL 중 첫 리소스를 선택합니다.
3. 저장소와 GitHub에서 확인된 실제 브랜치를 선택합니다.
4. 모노레포라면 Root Directory를 앱 폴더로 지정합니다.
5. 필요한 build/start 명령과 환경변수 이름을 확인합니다.
6. 배포를 시작합니다.
7. 배포가 `ACTIVE`가 되면 제공된 HTTPS 주소에서 핵심 기능을 확인합니다.
8. 필요하면 PostgreSQL, 사용자 도메인 또는 내부 서비스 연결을 추가하고 다시 배포합니다.

프로젝트 화면 상단의 `활동`에서 배포 기록을 확인하고, `새 리소스`에서 서비스나 PostgreSQL을 추가합니다. AI 하자점검, 데이터베이스, 도메인과 프로젝트 설정은 `더보기` 메뉴에 있습니다. 서비스나 DB를 선택하면 오른쪽 플로팅 패널에서 상세 설정을 확인합니다.

## 애플리케이션 실행 조건

웹 서버는 플랫폼이 주입한 `PORT` 환경변수를 사용하고 외부 접속이 가능하도록 `0.0.0.0`에 바인딩해야 합니다.

Node.js 예시:

```js
const port = Number(process.env.PORT || 3000);
app.listen(port, "0.0.0.0");
```

정상 확인 경로가 `/`가 아니라면 인증 없이 빠르게 응답하는 Healthcheck Path를 별도로 설정할 수 있습니다.

## 저장과 실제 적용 상태

환경변수, Root Directory, Build Command, Start Command와 Healthcheck Path는 저장만으로 실행 중인 서비스에 적용되지 않습니다.

- `저장 전 변경사항`: 화면에서 편집했지만 아직 저장하지 않은 상태
- `배포 적용 대기`: 저장됐지만 현재 `ACTIVE` 배포에는 적용되지 않은 상태
- `현재 서비스에 적용`: 변경 이후 시작한 새 배포가 성공해 `ACTIVE`가 된 상태

변수나 설정 탭의 `배포 준비하기`는 배포 탭으로 이동하는 동작입니다. 배포 탭에서 기본 확인을 마친 뒤 `변경 N개 적용` 또는 배포 버튼을 눌러야 실제 새 배포가 생성됩니다.

Auto Deploy 설정은 저장 이후 선택한 GitHub 브랜치에 들어오는 push부터 적용되며, Auto Deploy 설정 변경 자체가 즉시 새 배포를 시작하지는 않습니다.

같은 서비스의 배포가 이미 진행 중일 때 Auto Deploy push가 들어오면 가장 최신 커밋 한 건이 `다음 배포 대기`로 남습니다. 기다리는 동안 push가 더 들어오면 대기 중인 배포가 최신 커밋으로 갱신되며 중간 push마다 별도 빌드를 만들지는 않습니다. 선행 배포가 성공하거나 실패하면 대기 중인 최신 배포가 자동으로 시작됩니다.

## GitHub와 브랜치

- GitHub 계정 연결과 GitHub App 저장소 접근 범위는 서로 다릅니다.
- private 저장소가 보이지 않으면 GitHub App 설치 범위와 현재 로그인한 GitHub 계정을 확인합니다.
- 서비스 생성과 설정에서는 GitHub에서 조회된 실제 브랜치를 선택합니다.
- 빈 서비스는 서비스의 배포 탭에서 `소스 연결하기`를 누르거나 설정의 소스 영역에서 저장소와 실제 브랜치를 처음 연결합니다.
- 브랜치를 변경해 저장해도 즉시 배포되지는 않습니다. 이후 수동 배포와 Auto Deploy의 소스 기준이 바뀝니다.
- Auto Deploy가 진행 중 배포와 겹치면 프로젝트 화면에서 현재 배포와 `다음 배포 대기`를 함께 확인할 수 있습니다. 대기 중 추가 push가 반영된 횟수와 최종 실행할 최신 커밋도 배포 기록에서 확인합니다.
- GitHub 연결을 해제해도 기존 배포 리소스가 자동 삭제되지는 않지만 새 소스 조회와 배포에는 재연결이 필요합니다.

## 환경변수와 비밀값

- 비밀번호, API 키, 토큰과 DB 접속정보는 코드나 GitHub 저장소에 넣지 말고 서비스 환경변수로 저장합니다.
- 브라우저에 포함되는 변수에는 서버 전용 비밀값을 넣지 않습니다.
- 로그에는 환경변수 값 대신 키의 존재 여부만 기록합니다.
- 환경변수 변경은 새 배포가 성공해야 현재 서비스에 적용됩니다.

현재 환경변수는 앱의 빌드와 실행 과정에서 모두 사용될 수 있습니다. Build/Runtime 범위가 분리되어 있다고 가정하지 마세요.

## 관리형 PostgreSQL

- 프로젝트에 PostgreSQL을 생성한 뒤 `ACTIVE` 상태를 기다립니다.
- 프로젝트에 서비스가 정확히 1개면 새 DB가 그 서비스에 자동 연결됩니다.
- 서비스가 없거나 2개 이상이면 DB를 사용할 서비스를 직접 선택합니다.
- 연결된 서비스만 다음 배포에서 DB 환경변수를 받습니다.
- 한 서비스에 연결된 활성 DB가 1개면 기본 키는 `DATABASE_URL`입니다.
- 한 서비스에 연결된 활성 DB가 2개 이상이면 `DATABASE_URL_<DB_NAME>` 형태의 키를 사용합니다.
- 사용자가 같은 키의 환경변수를 직접 등록했다면 충돌이 없는 정상 연결에서는 사용자 값이 우선합니다.

DB 이름은 환경변수 키를 만들 때 대문자, 숫자와 밑줄로 정규화됩니다. 예를 들어 `orders-db`와 `orders_db`는 모두 `DATABASE_URL_ORDERS_DB`가 됩니다. 같은 서비스에 이런 DB 두 개를 연결하려 하면 저장이 거부됩니다. 기존 연결에서 같은 키 충돌이 발견되면 사용자 변수가 있어도 조용히 덮어쓰지 않고 배포를 중단합니다.

DB의 실제 사용 용량은 `pg_database_size` 측정값으로 표시됩니다. `미수집`은 `0GB`가 아니며 지연·일부 수집 상태와 측정 시각을 함께 확인해야 합니다.

솜사탕클라우드는 애플리케이션 ORM migration을 자동 실행하지 않습니다. 앱이 migration을 실행한다면 재시도와 동시 배포에도 안전한지 별도로 확인하세요.

## 도메인과 내부 서비스 연결

기본 HTTPS 주소에서 앱이 정상 작동하는지 먼저 확인한 뒤 사용자 도메인을 연결하세요. 대시보드에 표시된 DNS 레코드를 설정하고 DNS 전파와 HTTPS 상태를 확인합니다.

같은 프로젝트의 서버 서비스끼리는 호출할 서비스의 `연결` 설정에서 대상 서비스를 고를 수 있습니다. 별칭이 `API`라면 호출하는 서비스의 다음 배포에 `SOMSATANG_PRIVATE_API_URL` 같은 서버 전용 변수가 추가됩니다. 이 주소는 브라우저 코드에 노출하지 말고 서버 런타임에서만 사용하세요.

## 로그와 배포 복구

- 배포가 실패하면 실패 단계와 마지막 오류, Build Log와 Runtime Log를 확인합니다.
- 설정이나 일시 오류를 수정했다면 실패 배포를 재시도할 수 있습니다.
- 새 버전에서 문제가 생겼다면 과거 `ACTIVE` 배포를 대상으로 롤백할 수 있습니다.
- 재시도와 롤백은 모두 새 배포로 처리되며 배포 사용량에 포함됩니다.
- 다른 배포가 진행 중이면 같은 서비스에서 새 재시도나 롤백을 시작할 수 없습니다.

롤백은 과거 빌드 이미지 또는 소스 revision을 기준으로 새 배포를 만드는 기능입니다. 현재 환경변수, DB 연결, 내부 서비스 연결과 일부 현재 실행 설정이 사용될 수 있으며 DB schema, DB 데이터와 외부 API 상태는 복원하지 않습니다.

## AI 하자점검

현재 AI 하자점검 베타는 배포된 공개 웹페이지의 성능, SEO, 접근성, 보안과 응답 오류를 보조적으로 확인합니다.

이 기능은 GitHub 저장소 전체를 분석하는 코드리뷰 기능이 아닙니다. 인증, 결제, 개인정보와 데이터 변경 흐름은 직접 테스트해야 합니다.

## 사용량과 리소스

결제 화면에서 현재 플랜과 기능별 사용량, 한도, 남은 양 또는 초과량과 측정 상태를 확인합니다.

- CPU와 메모리 한도는 서비스마다 각각 제공되는 양이 아니라 프로젝트의 활성 서비스 전체에 배분되는 최대 총량입니다.
- 현재 CPU·메모리 화면은 할당/request와 플랜 한도를 표시합니다. 실제 런타임 CPU·메모리 계측은 준비 중입니다.
- 고객이 CPU와 메모리를 직접 조절하는 기능은 현재 제공하지 않습니다.
- 미수집 값은 0으로 간주하지 않습니다.
- 막대가 100%에서 멈춰도 실제 초과율과 초과량은 별도로 표시될 수 있습니다.
- 초과 표시 자체가 자동과금, 즉시 제한 또는 소급과금을 의미하지는 않습니다. 계정별 결제 화면의 안내를 확인하세요.

정확한 가격, 세금, 결제 주기, 다음 결제일과 계정별 정책은 현재 결제 화면과 공식 정책 원문을 우선합니다.

## 현재 지원 경계

다음 기능을 현재 제공한다고 가정하지 마세요.

- 고객이 직접 실행하는 PostgreSQL 시점 복구 또는 전체 self-service restore
- 애플리케이션 롤백을 통한 DB 데이터 복원
- 고객용 staging 또는 PR preview environment
- 고객이 직접 설정하는 replica, 멀티리전 또는 autoscaling
- 고객용 런타임 CPU·메모리 상세 메트릭과 자동 알림
- GitHub 저장소 전체를 대상으로 하는 AI 코드리뷰

지원 여부가 불분명하면 현재 대시보드와 공식 Docs를 확인하고, 그래도 확인되지 않으면 솜사탕클라우드 지원 채널에 문의하세요.

## AI가 배포를 도울 때 확인할 사항

1. 저장소에서 실제 앱이 있는 Root Directory를 찾습니다.
2. package script, Procfile 또는 프레임워크 실행 파일을 기준으로 build/start 명령을 확인합니다.
3. 서버가 `PORT`를 사용하고 `0.0.0.0`에 바인딩되는지 확인합니다.
4. 필요한 환경변수의 이름만 목록으로 정리합니다.
5. secret이 코드, 커밋, 로그 또는 대화에 포함되지 않았는지 확인합니다.
6. DB migration과 애플리케이션 배포·롤백의 책임을 분리합니다.
7. 설정 변경 뒤 새 배포가 `ACTIVE`가 되어야 적용된다는 점을 안내합니다.
8. 지원 문서에 없는 기능은 임의로 가정하지 않습니다.

## 보안 주의사항

AI, 이메일, 채팅, 이슈 또는 스크린샷에 다음 값을 보내지 마세요.

- 비밀번호
- API 키와 access token
- 세션 쿠키
- GitHub token
- 카드정보와 billing key
- 전체 `DATABASE_URL`
- private key
- 실제 환경변수 값

문제 해결에는 환경변수의 키 이름, 배포 상태, 오류 문구, 사용한 브랜치와 명령만 먼저 공유하세요.