코덱스 툴 사용법 11: Sites로 웹앱을 저장하고 배포하기 | DAKER 커뮤니티

코덱스 툴 사용법 11: Sites로 웹앱을 저장하고 배포하기

코덱스로 랜딩 페이지, 내부 도구, 작은 게임을 만들다 보면 마지막에 같은 문제가 반복된다. 코드는 만들어졌는데 누군가에게 보여 주려면 빌드, 호스팅, 접근 권한, 환경 변수를 따로 챙겨야 한다. 이 단계가 길어지면 바이브코딩의 속도가 배포 문턱에서 멈춘다.

Codex Sites는 이 문턱을 낮추는 기능이다. OpenAI 공식 Codex 매뉴얼 기준으로 Sites는 Codex가 웹사이트, 웹앱, 게임을 만들고 저장하고 배포하고 점검할 수 있게 해 주는 OpenAI 호스팅 워크플로다. 중요한 점은 "만든다"보다 "저장과 배포를 나눈다"는 데 있다.

아래 Mermaid 다이어그램은 Sites를 요청할 때의 판단 흐름이다. 게시 본문에서는 같은 흐름을 SVG 이미지로도 볼 수 있다.

1. Sites는 "미리보기 링크"가 아니라 production 배포다

Sites를 처음 쓸 때 가장 조심해야 할 문장은 이것이다. 공식 매뉴얼은 모든 Sites deployment URL이 production deployment라고 설명한다. 즉 "일단 링크 하나 뽑아서 볼게요"라고 생각하고 배포하면, 그 URL은 이미 배포된 결과물이다.

검토가 필요하다면 이렇게 요청하는 편이 안전하다.

이 React 도구를 Sites에 맞게 빌드 가능한지 확인해줘.
아직 deploy하지 말고, review할 수 있도록 version만 저장해줘.
저장 후 어떤 커밋과 빌드 결과가 연결됐는지 요약해줘.

핵심은 deploy라는 말을 아끼는 것이다. 화면, 문구, 데이터 저장 방식, 접근 권한을 보기 전에는 version 저장에서 멈춘다. 공유할 준비가 끝났을 때만 배포를 요청한다.

2. .openai/hosting.json은 프로젝트 연결 정보다

Sites 프로젝트는 로컬 소스와 OpenAI가 관리하는 호스팅을 연결한다. 공식 매뉴얼은 이 연결 정보와 선택한 저장소 바인딩 이름이 .openai/hosting.json에 저장된다고 설명한다. 새 starter 프로젝트는 처음에 project_id가 비어 있을 수 있고, Sites가 hosted project를 만들면 이후 연결된다.

이 파일에 적어야 하는 것은 "어떤 hosted project와 어떤 binding 이름을 쓰는가"다. 비밀값을 적는 곳이 아니다.

{
  "project_id": "",
  "d1": "DB",
  "r2": null
}

실무에서는 이 파일을 보면 두 가지를 바로 확인한다. 첫째, 이 로컬 프로젝트가 Sites와 연결됐는가. 둘째, D1이나 R2 같은 durable storage를 실제로 쓰는가. 저장소가 필요 없는데 들어가 있다면 설계를 다시 보는 편이 좋다.

3. 사이트 모양을 먼저 고른다

Sites는 Cloudflare Worker와 호환되는 ES module 출력물을 호스팅하는 흐름으로 설명된다. 그래서 기존 프로젝트를 무작정 배포하기보다, Codex에게 먼저 "이 프로젝트가 호환되는 산출물을 만들 수 있는지" 확인하게 하는 것이 안전하다.

요청은 기능 요구사항 기준으로 쓰는 편이 낫다.

이 도구는 로그인 없는 공개 계산기야.
사용자가 입력한 값은 브라우저 안에서만 쓰고, 서버에 저장하지 않아.
Sites starter 또는 현재 프로젝트 중 더 작은 쪽으로 구성하되,
durable storage는 요청하지 마.

반대로 저장이 필요한 경우에는 명확히 말한다.

사용자가 제출한 신청 기록을 나중에 다시 볼 수 있어야 해.
파일 업로드는 없고, 구조화된 행 데이터만 저장하면 돼.
Sites에서 D1이 필요한지 확인하고, 필요한 경우에만 binding을 추가해줘.

공식 매뉴얼 기준으로 구조화된 지속 데이터에는 D1, 이미지나 문서 같은 파일에는 R2가 맞다. 일시적인 UI 상태, 예를 들어 테마 선택이나 닫은 배너 같은 것은 보통 durable storage 요청 사유가 아니다.

4. 접근 권한은 처음부터 좁게 시작한다

Sites에서 배포 URL이 production이라는 점을 이해했다면, 다음 질문은 "누가 볼 수 있는가"다. 공식 매뉴얼은 owner와 workspace admins만 접근하는 admins_only, workspace 전체가 접근하는 workspace_all, 특정 사용자나 그룹을 고르는 custom 같은 접근 모드를 안내한다.

처음에는 좁게 시작하는 편이 낫다.

이 Sites 프로젝트의 접근 권한을 owner와 workspace admins로 제한해줘.
현재 URL과 access mode를 보여 준 뒤, 내가 확인하기 전까지 workspace_all로 넓히지 마.

내부 공지 페이지나 팀 대시보드라도 초안 단계에서는 공개 범위를 좁혀 둔다. 특히 고객 데이터, 내부 지표, 출시 전 문구가 들어간 사이트는 "팀 전체"도 넓을 수 있다. 최종 audience를 정한 뒤에만 권한을 넓힌다.

5. 환경 변수와 secret은 Sites panel에서 관리한다

로컬 개발에서는 .env가 편하지만, hosted runtime 값은 코드 파일에 넣으면 안 된다. 공식 매뉴얼은 Sites sidebar의 프로젝트 패널에서 hosted environment variables와 secrets를 추가, 수정, 제거하라고 안내한다. .openai/hosting.json에는 secret 값을 저장하지 않는다.

좋은 요청은 이렇게 생겼다.

이 프로젝트는 API_BASE_URL과 ANALYTICS_KEY가 필요해.
로컬 .env.example에는 키 이름만 남기고, 실제 값은 커밋하지 마.
Sites hosted environment 값은 내가 패널에서 넣을 수 있게 필요한 키 목록만 정리해줘.
값을 넣은 뒤에는 승인된 saved version을 다시 deploy해야 한다고 완료 보고에 남겨줘.

여기서 Codex에게 맡길 일은 키 이름 정리, 코드가 환경 변수를 읽는 방식 정리, secret이 커밋되지 않았는지 확인하는 일이다. 실제 비밀값 입력은 권한 있는 사람이 Sites panel에서 처리한다.

6. 배포 전에는 Codex review pane으로 한 번 닫는다

Sites는 빠르지만, 빠른 만큼 검토 루프가 더 중요하다. 공식 매뉴얼은 배포나 접근 권한 확대 전에 Codex review pane에서 소스 변경과 데이터베이스 migration을 확인하고, 빌드 성공과 선택한 saved version을 확인하라고 안내한다.

실무 체크리스트는 이 정도면 충분하다.

Sites는 배포를 대신해 주지만, 공개 판단까지 대신해 주지는 않는다. 사람은 여전히 audience, 데이터 보관, secret, 검토 완료 기준을 소유해야 한다.

7. 바로 붙여 넣는 Sites 프롬프트 템플릿

아래 템플릿은 작은 웹 도구를 만들고 안전하게 공유할 때 그대로 쓸 수 있다.

이 프로젝트를 Codex Sites로 공유 가능한 형태로 준비해줘.

목표:
{누가 어떤 용도로 쓸 웹사이트/웹앱인지}

제약:
- 아직 production deploy하지 않음
- 먼저 Sites-compatible build 가능 여부 확인
- 필요한 경우에만 D1/R2/authentication 요청
- secret 값은 파일에 쓰지 않음
- 접근 권한은 처음에 owner/admins only

완료 기준:
- saved version 생성 또는 생성 불가 사유 보고
- 변경 파일과 storage binding 요약
- 배포 전 review checklist 제공
- deploy가 필요하면 별도 단계로 명확히 제안

이미 배포할 준비가 끝났다면 마지막 문장만 바꾼다.

위 checklist를 통과하면 선택한 saved version을 deploy하고,
production URL과 access mode를 확인해줘.

8. Sites를 쓸 때 피해야 할 습관

첫째, "링크만 하나 만들어 줘"라고 요청하지 않는다. Sites deployment URL은 production URL이다. 둘째, storage를 습관적으로 붙이지 않는다. 저장해야 하는 제품 데이터가 있을 때만 D1이나 R2를 요청한다. 셋째, secret 값을 채팅이나 파일에 붙이지 않는다. 키 이름과 입력 위치만 정리한다.

넷째, 접근 권한을 먼저 넓히지 않는다. owner/admins에서 시작하고, 검토가 끝난 뒤 workspace나 custom audience로 넓힌다. 다섯째, 배포 후 URL만 보고 끝내지 않는다. 어떤 version이 배포됐는지, 누가 접근 가능한지, hosted environment 값이 반영됐는지까지 확인한다.

Senior takeaway: Codex Sites는 웹앱을 빠르게 공개하는 기능이지만, 좋은 사용법은 속도를 늦추는 지점을 정확히 아는 것이다. version 저장으로 후보를 만들고, re

view와 access gate를 통과한 뒤에만 deploy하면 바이브코딩의 빠른 실험이 실제 production 링크로 넘어갈 때도 통제 가능해진다.

Redirecting to 코덱스 툴 사용법 11: Sites로 웹앱을 저장하고 배포하기 | DAKER 커뮤니티...