koax 배포 사용설명서

코드를 push하면 <이름>.koax.site 로 자동 배포됩니다 — 사내 GitHub + Railway.

한 줄 요약. ① 회사 이메일로 가입 → ② PowerShell에 irm https://setup.koax.site/koax-git-setup.ps1 | iex 붙여넣기(1회) → ③ 프로젝트에 deploy.json 넣고 git push. 끝나면 https://<저장소명>.koax.site 로 사이트가 뜹니다. SSH 키도, 서버 설정도, 배포 명령도 필요 없습니다.

처음 한 번만 — 준비 (가입 · Git 설치 · 로그인 설정)
배포하기 — 프로젝트 올리기
deploy.json 옵션
수정하고 다시 배포하기
자주 겪는 문제
규칙과 한계 (꼭 읽어주세요)

1. 처음 한 번만 — 준비

1-1. 계정 만들기

브라우저에서 https://git.koces.com 접속 → 회원가입(Register)

회사 이메일로 가입합니다. 허용 도메인: @koces.com, @nhnpayco.com, @kcp.co.kr
(그 외 도메인은 가입이 거부됩니다.)

가입 직후 확인 메일이 옵니다. 메일의 링크를 클릭하면 계정이 활성화됩니다.

확인 메일이 스팸함으로 갈 수 있습니다(발신 주소가 @gmail.com). 받은편지함에 없으면 스팸함을 확인하세요. 관리자 승인은 필요 없습니다 — 메일만 확인하면 바로 로그인됩니다.

1-2. Git 설치

이미 Git이 있으면 건너뛰세요. 없으면 git-scm.com/download/win 에서 설치. (설치 시 기본 옵션 그대로 두면 됩니다 — 로그인에 필요한 Git Credential Manager가 함께 설치됩니다.)

1-3. 브라우저 로그인 설정 (핵심)

이걸 해두면 git push 할 때 GitHub처럼 브라우저 창이 떠서 로그인하고, 이후로는 다시 묻지 않습니다.

PowerShell을 열고 아래 한 줄을 붙여넣습니다. (파일을 받을 필요 없습니다.)

irm https://setup.koax.site/koax-git-setup.ps1 | iex

"설정 완료" 메시지가 나오면 끝입니다. 한 번만 하면 됩니다.

이 스크립트는 SSH 키를 만들거나 비밀번호를 저장하지 않습니다. 다음 git push 때 브라우저 로그인이 뜨도록 준비만 합니다. 실행 전에 내용을 보고 싶으면 브라우저에서 setup.koax.site/koax-git-setup.ps1 을 그대로 열어보세요.

macOS · Linux 를 쓴다면 터미널에서:

curl -fsSL https://setup.koax.site/koax-git-setup.sh | bash

Windows와 달리 mac/Linux는 Git Credential Manager가 git에 포함돼 있지 않습니다. 없으면 스크립트가 설치 방법을 안내하고 멈추니, 안내대로 설치한 뒤 다시 실행하세요.

사내망 정책 등으로 위 한 줄이 막히면, 스크립트 파일 받기를 눌러 아무 폴더에 두고 그 폴더에서 실행해도 됩니다:

powershell -ExecutionPolicy Bypass -File .\koax-git-setup.ps1

(내용만 확인하려면 이쪽에서 브라우저로 바로 볼 수 있습니다.)

2. 배포하기 — 프로젝트 올리기

예시로 정적 웹사이트 하나를 올려봅니다. PowerShell에서:

프로젝트 폴더 만들기

mkdir my-site
cd my-site
git init -b main

배포 표시 파일(deploy.json)과 내용 만들기 — deploy.json이 있어야 배포됩니다.

'{ "buildPack": "static" }' | Out-File -Encoding utf8 deploy.json
'<h1>안녕하세요 koax</h1>' | Out-File -Encoding utf8 index.html

커밋

git add -A
git commit -m "첫 배포"

업로드(push) — 저장소를 미리 안 만들어도 push하면 자동으로 만들어집니다.
<본인계정>은 git.koces.com 로그인 아이디로, <저장소>는 원하는 이름으로 바꾸세요.

git remote add origin https://git.koces.com/<본인계정>/my-site.git
git push -u origin main

반드시 https:// 주소로 하세요 (git@... 형태 아님). 브라우저 로그인은 https에서만 작동합니다.

push하면 브라우저가 떠서 git.koces.com 로그인을 요청합니다. 로그인·승인하면 업로드가 끝납니다. (다음부터는 안 뜹니다.)

약 1분 뒤 https://my-site.koax.site 로 사이트가 뜹니다. 인증서(https)는 자동입니다.
GitLab에서 방금 커밋 옆에 deploy/koax 상태(성공/실패)가 표시됩니다.

됐습니다. 이후 이 저장소는 계속 당신 것이고, 코드를 고쳐 다시 올리면 사이트가 갱신됩니다(→ 4번 항목).

3. deploy.json 옵션

deploy.json은 저장소 루트에 두는 작은 설정 파일입니다. 전부 선택 항목이며, 없는 값은 자동 판단됩니다.

{
  "buildPack": "static",
  "port": 3000,
  "subdomain": "myblog",
  "autoDeploy": false,
  "resources": { "memory": "1g", "cpu": "1" }
}

키	설명	기본값
`buildPack`	`static`(정적 HTML) · `nixpacks`(Node/Python 등 자동) · `dockerfile`(Dockerfile 사용)	`static`
`port`	앱이 여는 포트. Node는 보통 `3000`	빌드팩별 자동
`subdomain`	원하는 주소. `"myblog"` → `myblog.koax.site`. 비워두면 저장소 이름 사용	저장소 이름
`autoDeploy`	`false`=최초 1회만 배포(이후 `[deploy]`로 갱신) · `true`=push마다 자동 갱신	`false`
`resources`	메모리·CPU. 상한: `2g` / `2`. 넘으면 자동으로 줄여집니다	512m / 0.5

buildPack을 적지 않으면 Dockerfile이 있어도 static으로 처리됩니다. Docker로 빌드하려면 "buildPack": "dockerfile"을 꼭 적으세요.

4. 수정하고 다시 배포하기

기본 설정(autoDeploy: false)에서는 push한다고 자동으로 다시 배포되지 않습니다. 실수 배포·데이터 초기화를 막기 위해서입니다.

방법 A — 필요할 때만 배포 (기본)

커밋 메시지에 [deploy] 를 넣어 push하면 그때 한 번 배포됩니다.

git add -A
git commit -m "내용 수정 [deploy]"
git push

웹 UI로 편집할 때도 커밋 메시지 칸에 [deploy] 를 포함하면 됩니다.

방법 B — push할 때마다 자동 배포

deploy.json에 "autoDeploy": true를 넣으면, 이후 push마다 자동 갱신됩니다. (이 설정을 바꾼 다음 push부터 적용됩니다.)

5. 자주 겪는 문제

증상	해결
push할 때 `HTTP Basic: Access denied` / 브라우저가 안 뜸	설치 한 줄을 다시 실행하세요 — `irm https://setup.koax.site/koax-git-setup.ps1 \| iex` 예전에 저장된 로그인 정보가 남아 방해하는 경우로, 스크립트가 그걸 정리하고 브라우저 로그인을 새로 띄웁니다.
사이트가 빈 페이지 / 404	정적 사이트인데 `index.html`이 없는 경우입니다. `index.html`을 추가해 다시 배포하세요.
주소에 `-이름`이 붙음 (`blog-hong.koax.site`)	같은 이름을 다른 사람이 먼저 썼습니다(선착순). `deploy.json`의 `subdomain`으로 다른 이름을 지정하세요.
`예약된 서브도메인` 이라고 거부됨	`api·www·admin·git·koces` 등 예약어는 쓸 수 없습니다. 다른 이름으로.
고쳤는데 사이트가 그대로	기본은 `[deploy]`가 있어야 갱신됩니다(→ 4번). 커밋 메시지에 `[deploy]`를 넣으세요.
확인 메일이 안 옴	스팸함을 확인하세요. 그래도 없으면 관리자에게 문의.

6. 규칙과 한계

본인 계정(개인 네임스페이스) 아래에 저장소를 만드세요 — git.koces.com/<본인아이디>/...
deploy.json이 없으면 배포되지 않습니다. (배포용이 아닌 저장소를 실수로 올리는 것을 막습니다.)
배포는 기본 브랜치(보통 main)에 push할 때만 일어납니다.
앱 한 개당 메모리 512MB · CPU 0.5가 기본이며, deploy.json으로 상한(2GB/2) 안에서 조정할 수 있습니다.

데이터 주의. 앱 안에 저장한 파일이나 DB(예: SQLite)는 다시 배포하면 초기화될 수 있습니다. 지속되어야 하는 데이터(업로드 파일·데이터베이스)가 있으면 관리자와 상의해 영속 볼륨이나 별도 DB를 붙이세요.

이 플랫폼은 사내 서버 한 대에서 여러분의 코드를 직접 빌드·실행합니다. 그래서 사용 권한을 회사 이메일 가입으로 제한합니다. 외부에 공개되는 사이트를 올릴 때는 민감정보·비밀키가 코드에 들어가지 않도록 주의하세요.

문의: 시스템 관리자 · 이 문서는 koax 배포 플랫폼 운영 기준으로 작성되었습니다.
이 문서의 최신본은 항상 setup.koax.site/manual.html 에 있습니다.
관련: git.koces.com(코드) · <이름>.koax.site(배포 주소) · setup.koax.site(설치·설명서)