DEVELOPER CLI

빈 폴더에서 배포까지, 한 줄로 시작

yakcloud CLI로 프로젝트를 초기화하고 로컬 kind 개발 클러스터에 배포(없으면 자동 생성·오프라인·무료) — 화면을 확인한 뒤 같은 매니페스트를 관리형 검증·운영 클러스터로 승격합니다. 로컬 개발과 관리형 배포가동일한 바인딩 env·데이터소스 파리티로 동작하고, 검증계는 선택입니다.

설치 — 복사해서 붙여넣기

curl -fsSL https://gitea.yakenator.io/yakenator/yakcloud-starter/raw/branch/main/install.sh | sh

macOS · Linux · 설치 후 필요 시 export PATH="$HOME/.local/bin:$PATH"
설치 시 Claude Code 전역 슬래시 명령 /yakcloud 도 함께 생성됩니다.
로컬 개발(project deploy)은 Docker + kind 가 필요합니다(관리형 승격은 불필요).

WATCH · 풀 워크스루

yakcloud 와 cloud 의 만남

빈 폴더에서 Claude Code로 Node 상업용 게시판을 만들어 — 로컬 kind 개발 →검증 → 운영 승격 → 도메인 연결까지, 실제 서비스가 되기까지의 전 과정을 한 번의 워크스루로 담았습니다.

영상 속 그 결과물이 지금 라이브입니다개발 → 검증 → 운영 승격 + 커스텀 도메인 연계까지 끝나 실제 서비스 중.

board20.yakenator.io/board20 ↗

빠른 시작

1 초기화
빈 폴더에 스타터 앱 · CI · 매니페스트 · Claude 스킬을 스캐폴딩합니다.
yakcloud project init my-app
2 개발 배포 (로컬 kind)
로컬 kind 개발 클러스터(없으면 자동 생성)에 빌드·배포합니다. 로컬 도메인 *.localhost 으로 화면·API·WSS 확인 — 오프라인·무료, CI 불필요.
yakcloud project deploy
3 검증·운영 승격
확인되면 그 이미지를 재빌드 없이 상위 클러스터로 승격 — --to val(검증, 선택) 또는 --to prod(운영, 도메인 부착). 기본 도메인은 자동.
yakcloud project promote --to prod

실전 예시 — 개발 → (검증) → 운영

1. 로컬 kind 개발 클러스터에 배포하고 확인

매니페스트 environments.dev(cluster·port·workers)로 로컬 클러스터가 뜹니다(없으면 자동 생성). 데이터소스도 로컬에서 실제 프로비저닝되어 <ALIAS>_URL 등 관리형과 동일한 env로 앱에 주입됩니다.

yakcloud project deploy

배포 후 로컬 도메인 *.localhost 으로 화면·API·WSS 를 그대로 확인합니다. 반복 개발 = 반복 project deploy(오프라인·무료).

2. 확인되면 관리형 클러스터로 승격

로컬에서 확인한 바로 그 매니페스트를 관리형으로 승격합니다. --to val(검증, 선택)에서 이미지를 build·push하고, 이후 그 이미지를 재빌드 없이 --to prod 로 운영 도메인까지 붙입니다(드리프트 0).

yakcloud project promote --to prod v0.2.0

매니페스트 environments.prod.domains 의 도메인이 자동 부착되고, 운영 클러스터 기본 도메인에도 동시에 노출됩니다.

3. 클러스터의 데이터소스 살펴보기

yakcloud datasource ls

클러스터 'my-dev' 데이터 소스 (5)
   이름          타입         위치   상태     플랜
   appdb         POSTGRESQL   내부   READY    small
   cache         REDIS        내부   READY    small
   files         MINIO        외부   READY    small
   search        SOLR         내부   READY    small
   mq            RABBITMQ     내부   READY    small

개발·검증·운영 각 클러스터가 자체 데이터 계층을 가집니다(공유 외부 소스는 클러스터별 격리 계정으로 접속). 환경 간 데이터 백업·싱크는 별도(추후).

명령 레퍼런스

클러스터

`cluster create <name> [--template S\|M] [--nodes N] [--golden]`	배포토큰으로 클러스터 프로비저닝(완료까지 대기)
`cluster ls`	내 클러스터 목록(이름·상태·노드·기본 도메인)

프로젝트

`project init [name]`	빈 폴더에 스캐폴딩(앱 + CI + 매니페스트 + Claude 스킬)
`project deploy [vX.Y.Z]`	커밋 + 태그 push → CI 빌드 → 개발 클러스터 배포(버전 생략=자동 버전업)
`project promote [--to val\|prod] [vX.Y.Z]`	그 이미지를 재빌드 없이 상위 클러스터로 승격(검증 선택). `--to prod` = 운영 도메인 부착
`project info`	프로젝트 개괄 — 매니페스트 + 라이브 상태
`project check [--env dev\|val\|prod]`	배포 전 dry-run(실제 변경 없이 계획만)
`project update`	이 프로젝트의 엔진·CI·스킬만 최신화(앱·매니페스트 보존)

배포환경 설정 (앱별)

매니페스트를 수정하고, 이미 배포돼 있으면 재빌드 없이 라이브 반영(PATCH)합니다.

`domain <fqdn> [wl]`	도메인 등록 + 워크로드에 할당(관리형 도메인 = 즉시 활성)
`scale <wl> <n>`	replicas 변경
`set <wl> --image/--port/--health/--cpu/--mem/--path/--rewrite`	워크로드 필드 수정
`env <wl> KEY=VAL … [--secret KEY] [--unset KEY]`	환경변수 설정 / 해제
`datasource ls`	클러스터에서 이용 가능한 소스 목록(이름 · 타입 · 내부/외부 · 상태)
`source add <name> <type> [plan] [--shared]` · `source rm`	데이터 소스(requires) 추가 / 삭제. `--shared` = 공유 외부 소스(백엔드가 클러스터별 격리 DB/계정 민팅, 소용량 클러스터용).
`bind <wl> <source> <alias>` · `unbind`	소스 바인딩 / 해제 → `<ALIAS>_URL` 등 주입

자격 · 유지보수

`login` · `config` · `logout`	Gitea 계정 + 배포토큰 저장(비밀 = OS 키체인 암호화) · 조회 · 삭제
`upgrade`	전역 `yakcloud` CLI + `/yakcloud` 슬래시 명령 자기 갱신(최신으로)

Claude Code와 함께

설치하면 전역 슬래시 명령 /yakcloud 가 함께 생성됩니다(~/.claude/commands/yakcloud.md). 어떤 프로젝트에서든 Claude Code에 /yakcloud … 로 바로 실행하세요. 또 yakcloud project init 은 프로젝트에 Claude Code 스킬(.claude/skills/yakcloud-deploy)을 넣어 자연어로 배포·환경설정을 맡길 수 있습니다.

1 처음이면 — 빈 폴더에서 Claude Code를 열고 붙여넣기(설치 + 초기화):

yakcloud CLI를 설치하고 새 프로젝트를 초기화해줘 — curl -fsSL https://gitea.yakenator.io/yakenator/yakcloud-starter/raw/branch/main/install.sh | sh 실행 후 yakcloud project init <이름>

2 설치되면 어디서든 슬래시 명령 또는 자연어로:

/yakcloud datasource ls

yakcloud 에 배포해줘

/yakcloud 는 TTY가 없는 Claude Code 환경을 고려해, 마법사가 필요한 project init 은 필요한 값(클러스터·포트·도메인 등)을 대화로 모아 대신 진행합니다. CLI 없이도 스킬의 수동 절차로 안내합니다.

관리형 승격을 위한 1회 준비

로컬 개발(project deploy)만 할 거면 아래는 불필요합니다 — 검증·운영으로 승격(promote)할 때만 준비하세요.

콘솔 설정 → 배포 토큰에서 yakd_… 발급(한 번만 표시).
Gitea 레포 생성 후 git remote add origin ….
레포 Settings → Actions → Secrets: YAKCLOUD_URL, YAKCLOUD_TOKEN, REGISTRY_TOKEN.
yakcloud.yaml 의 environments.val.cluster(검증, 선택) · environments.prod.cluster(+prod.domains) · image 수정(environments.dev 는 로컬 kind 기본값).

스타터 레포 ↗사용자 설명서 데이터 소스 & env (PDF)콘솔 열기 →