도움말

① 깃허브 저장소 연결 (push 할 때마다 자동 배포)

1. 로그인 — 깃허브 계정으로 들어옵니다(x-y.net 계정도 됨).
2. 「내 사이트」에서 새 사이트를 누르고, chiwaa 가 저장소를 읽을 수 있게 깃허브에서 허용합니다.
3. 저장소와 사이트 이름을 고릅니다. 빌드 명령·결과 폴더는 비워 두면 저장소를 보고 정합니다(아래 「빌드 자동 인식」).
4. 연결한 브랜치(보통 main)에 push 하면 빌드해서 바뀝니다. 다른 브랜치에 push 하면 이름--브랜치.chiwaa.com 미리보기가 따로 생기고, PR 의 chiwaa 상태 「Details」에 그 주소가 걸립니다(사이트당 10개, 브랜치를 지우면 함께 지움). 실패하면 이전 버전이 그대로 열리고, 사이트 화면 맨 위에 원인과 고칠 방법(AI 에게 붙여 넣을 말 포함)이 나옵니다.

② CLI (깃허브 없이 폴더에서 바로)

Node.js 18 이상이면 설치 없이 npx 로 실행됩니다. 프로젝트 폴더에서:

1. npx chiwaa login — 브라우저가 열리면 코드를 확인하고 「승인」을 누릅니다(처음 한 번만). 승인한 뒤 터미널(또는 AI)에 「로그인했습니다」가 나올 때까지 기다리세요. 중간에 끊겼으면 같은 명령을 다시 실행하면 다시 승인하지 않아도 이어집니다.
2. npx chiwaa deploy — 처음이면 사이트 이름을 정하고 .chiwaa.json 에 기억합니다. 다음부터는 이 한 줄. 미리보기는 --preview.

· package.json 에 build 가 있으면 내 컴퓨터에서 빌드하고 결과 폴더를 올립니다. 다른 폴더는 --dir, 빌드 생략은 --no-build.
· 잘못 올렸으면 npx chiwaa rollback 으로 바로 전 버전으로 돌아갑니다. 남은 버전은 npx chiwaa versions.
· 사이트 이름은 영문 소문자·숫자·하이픈 2~30자입니다. 예: my-app, docs-2026

CLI 명령 모음

한 번 올린 사이트 폴더에서 실행하세요. <표>·<이름>은 쓸 이름으로 바꾸고, 대괄호로 적은 부분은 생략해도 됩니다.

권한은 public(누구나), owner(주인만)입니다. 개인정보가 있는 문의 표는 --read owner로 만드세요. 사진은 먼저 npx chiwaa db on으로 글 저장 기능을 켜고 씁니다.

서버 함수는 사이트 폴더 맨 위 api/에 두고 npx chiwaa deploy로 함께 올립니다. 미리보기도 실제 사이트의 DB를 함께 씁니다.

DB 끄기·표·글·사진 지우기처럼 저장된 데이터가 사라지는 일은 CLI가 아니라 chiwaa.kr 사이트 화면의 「DB」에서 하세요.

③ AI 에이전트 · CI

Claude Code·Codex·Cursor 에 「chiwaa 에 배포해 줘. 방법은 https://chiwaa.kr/llms.txt」라고 하면 됩니다. 에이전트는 llms.txt 의 명령·규칙을 따르고, 첫 배포 때 폴더에 AGENTS.md(Claude Code 용 CLAUDE.md 포함)를 만들어 다음부터는 그것을 읽습니다. 로그인 승인을 기다리다 에이전트가 응답을 끝내도, 승인 뒤 명령을 다시 실행하면 이어서 로그인됩니다.

예: 「이 Next.js 프로젝트를 chiwaa 에 배포하고 미리보기 주소로 먼저 확인해 줘. 방법은 https://chiwaa.kr/llms.txt」

CI(GitHub Actions 등): API 토큰 화면에서 토큰을 만들어 CI 비밀값 CHIWAA_TOKEN 으로 넣고 npx chiwaa deploy --name 이름 --yes 를 실행합니다(GitHub Actions 예가 그 화면에 있음). 토큰은 로그나 저장소에 남기지 마세요.

빌드 자동 인식

· 깃허브 연결에서 빌드 설정을 비워 두면 저장소를 봅니다. Vite·React(CRA)·Vue·Astro·Angular·Parcel·Next.js 를 알아보고 잠금 파일에 맞춰 npm·pnpm·yarn 으로 빌드합니다.
· Node 판: .nvmrc → .node-version → package.json 의 engines.node 순서로 읽어 18·20·22·24 중 맞는 가장 높은 판으로 빌드합니다(없으면 22, lts/iron 같은 이름도 됨).
· 앱이 하위 폴더(예: web/, landing/)에 있어도 두 단계까지 찾습니다. 앱이 여러 개면 고르지 않고 알려 줍니다.
· Next.js: 서버 기능이 없으면 output: 'export' 를 빌드 동안만 덧씌워 정적 사이트로 만듭니다(내 next.config 는 바뀌지 않음). API 라우트·middleware·서버 액션이 있으면 standalone 으로 빌드해 컨테이너로 돌립니다(아래 「컨테이너」).
· 결과에 index.html 이 없으면 올리지 않습니다(소스가 공개되지 않게). 실행 파일·.env 는 빼고 올립니다.
· 주소 규칙: 파일 없는 주소는 index.html(SPA), /about → about.html, _redirects(Netlify 형식) 지원.

DB (게시판·문의·방명록 같은 글 저장)

사이트 화면의 「DB」에서 켜고 표를 만들면, 사이트에서 /_chiwaa/data/v1/표이름 주소로 글을 저장하고 읽을 수 있습니다. 표를 만들면 붙여 넣을 코드가 함께 나옵니다. 방문자가 남긴 문의처럼 「나만」 읽는 표의 글은 chiwaa.kr → 내 사이트 → 그 사이트 「자세히」 → 「DB」 → 표 이름 줄의 「데이터 보기」를 누르면 보입니다. 글쓴이가 비밀번호로 자기 글을 고치고 지우는 게시판도 됩니다. Supabase 를 쓰는 사이트는 「설정값」에서 주소와 공개 키를 넣으면 됩니다.

사진 (게시판 사진 첨부·상품 사진)

「DB」 화면의 「사진」에서 방문자 사진 올리기를 켜면, 게시판 글쓰기에 사진을 붙일 수 있습니다. 올린 사진은 긴 변 2000px 로 줄이고 촬영 위치(GPS) 정보를 지운 뒤 브라우저에 맞춰 AVIF·WebP 로 보여 줍니다. 글에 쓰지 않은 방문자 사진은 하루 뒤, 글을 지우면 그 글의 사진도 지웁니다. 상품 사진은 같은 화면에서 직접 올리면 자동으로 지우지 않습니다.

서버 함수 (api/*.js)

export default async function (request, env) { return Response.json(...) } 형식의 JS·TS 입니다(Supabase Edge Runtime, V8 격리). 사이트 폴더 맨 위 api/ 에 파일을 두면 https://내사이트/api/파일이름 으로 서버에서 실행됩니다. 결제·로그인 키 같은 비밀값은 코드에 적지 않고 npx chiwaa env set 이름 으로 넣습니다(사이트 화면 「서버 함수」에서도 됩니다). 실행 기록은 npx chiwaa logs.

검증된 견본: 토스 결제 화면 · 결제 승인 · 카카오 로그인. AI 에이전트도 llms.txt 를 보고 이 견본을 씁니다. 결제 대금은 내 토스페이먼츠 계정으로 바로 들어갑니다.

컨테이너 (서버 앱 그대로)

아래 앱은 깃허브 push 든 npx chiwaa deploy 든 정적 파일 대신 컨테이너로 실행됩니다(CLI 는 소스를 보내고 빌드 서버가 빌드 — node_modules·.git·.env*·.gitignore 에 적힌 것은 보내지 않음). 사이트 주소·https·내 도메인·비밀번호 잠금·사이트 DB 는 그대로 씁니다.

· Next.js — API 라우트·middleware·서버 액션·SSR 이 있으면 output: 'standalone' 으로 빌드해 node server.js 로 실행(내 next.config 는 바뀌지 않음).
· Node 서버 — Express·Fastify·Nest 처럼 package.json 의 start 로 뜨는 앱. build 가 있으면 먼저 빌드합니다.
· Dockerfile — 정적 결과가 없고 저장소(앱 폴더) 맨 위에 Dockerfile 이 있으면 그대로 빌드합니다. 파이썬 등은 이 방법으로.
· 앱은 환경변수 PORT(3000)에서 들어야 합니다. 사이트 「설정값」이 빌드와 실행 환경변수로 들어갑니다(Dockerfile 은 ARG 로 받기).
· 요금제별: 무료 1개·256MB, 프로 3개·512MB, 비즈니스 10개·1024MB(컨테이너 하나의 메모리). 브랜치 미리보기는 개수에 넣지 않습니다.
· 무료·프로는 30분 동안 요청이 없으면 잠들고, 다음 요청에서 3초 안팎으로 깨어납니다. 비즈니스는 항상 켜 둡니다.
· 컨테이너는 국내 전용 서버에서 따로 격리되어 돌고, 우리 내부망·메일(25)로는 나갈 수 없습니다. 디스크는 다시 배포하면 사라지니 저장은 사이트 DB·사진 저장·외부 DB 를 쓰세요.
· 사이트 DB: DB 를 켠 사이트의 컨테이너에는 CHIWAA_DB_URL·CHIWAA_DB_SITE·CHIWAA_DB_TOKEN 이 들어갑니다. 주인 권한으로 모든 표를 읽고 씁니다: fetch(CHIWAA_DB_URL + "표이름", { headers: { "X-Chiwaa-Fn-Site": CHIWAA_DB_SITE, "X-Chiwaa-Fn-Token": CHIWAA_DB_TOKEN } })(POST 글쓰기·PATCH /표/번호 고치기·DELETE 지우기). DB 를 켠 뒤 한 번 다시 배포해야 들어갑니다.
· 관리형 Postgres: 사이트 화면 「Postgres 만들기」나 npx chiwaa pg create → 다시 배포하면 컨테이너에 CHIWAA_PG_URL(설정값에 없으면 DATABASE_URL 로도)이 들어갑니다. Postgres 16, 사이트 전용 DB·계정, 컨테이너에서만 접속, 매일 백업 7일, 용량을 넘으면 읽기 전용. 마이그레이션은 앱 시작 명령에(예: prisma migrate deploy && node server.js). 쿼리 하나 30초 한도. 내 PC 에서 SQL: npx chiwaa pg shell(대화형, \dt 표 목록) · npx chiwaa pg query "select …" · --file 001.sql · --json.
· Supabase: supabase-js(https)는 그대로 됩니다. Postgres 에 직접 붙을 때(Prisma·Drizzle 등)는 대시보드의 Connection pooler 주소(aws-0-…pooler.supabase.com)를 쓰세요. 기본 주소 db.….supabase.co 는 IPv6 전용이라 닿지 않습니다.

아직 안 되는 것

PHP·MySQL 은 엑스와이넷 웹호스팅을 쓰세요.