koax 배포 사용설명서

코드를 push하면 <이름>.koax.site 로 자동 배포됩니다 — 사내에서 운영하는 Git · 자동배포 플랫폼.

1. 처음 한 번만 — 준비

1-1. 계정 만들기

1-2. Git 설치

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

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

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

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

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

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

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

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

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

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

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

3. deploy.json 옵션

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

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

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. 데이터베이스(PostgreSQL) 쓰기

데이터를 저장해야 하는 앱이면 deploy.json에 두 줄만 추가하세요. 관리자에게 요청할 필요 없이 push하면 DB가 만들어지고 앱에 연결됩니다.

{
  "buildPack": "nixpacks",
  "port": 3000,
  "dataClass": ["internal"],
  "database": "postgresql"
}

5-1. 무엇이 만들어지나요

결과는 GitLab 커밋 옆에 코멘트로 남습니다: 🗄️ PostgreSQL 연결 준비됨

5-2. dataClass — 데이터 등급을 먼저 정하세요

DB를 쓰려면 앱이 어떤 데이터를 저장하는지 적어야 합니다. 애매하면 한 단계 높게 적으세요.

5-3. 앱 코드에서 쓰기

환경변수 DATABASE_URL을 읽으면 됩니다.

// Node.js (pg)
const { Pool } = require('pg');
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

# Python
import os, psycopg
conn = psycopg.connect(os.environ["DATABASE_URL"])

// Prisma — schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

"scripts": {
  "build": "prisma generate && next build",
  "start": "prisma migrate deploy && next start"
}

5-4. 이미 배포한 앱에 DB 추가하기

deploy.json에 dataClass와 database를 추가해 push하세요.

• "autoDeploy": true 이면 DB 연결 후 자동으로 다시 배포됩니다.
• 기본값(false)이면 DB만 준비되고, 커밋 메시지에 [deploy]를 넣어 배포할 때 연결됩니다. 한 번에 하려면 처음부터 [deploy]를 넣어 push하세요.

관리자가 이미 DATABASE_URL을 연결해 둔 앱은 건드리지 않습니다. 변수 이름을 바꾸고 싶으면 "database": { "type": "postgresql", "envVar": "PG_URL" } 처럼 적습니다.

5-5. 백업·삭제·로컬 개발

6. 자주 겪는 문제

7. 규칙과 한계

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

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