KPubData Studio

KPubData Studio는 한국 공공데이터를 수집하고, 출처와 이용 조건을 유지한 스냅샷으로 관리하며, 표와 SQL 로 분석하는 작업공간입니다.

KPubData 제품군: KPubData (공공 API 접근 라이브러리) → KPubData Builder (실행·웨어하우스) → KPubData Studio (작업공간)

이름 — 실행 엔진의 제품명은 KPubData Builder, 저장소·패키지는 kpubdata-builder 입니다. 이 문서의 명령어와 환경변수(VITE_BUILDER_API_URL 등)도 같은 이름을 씁니다 (BRAND.md).

KPubData는 데이터셋을 설계·정규화하는 과정이 종종 복잡하고, YAML 편집 실수, 시각적 피드백 부재, 비개발자 접근 어려움 등의 진입장벽이 있습니다. Studio는 이러한 장벽을 제거하고, 코딩 경험이 없는 사용자도 공공데이터 처리 흐름을 직관적으로 구성하고 관리할 수 있도록 돕습니다.

이 프로젝트가 존재하지 않는 경우

빌드 설정 파일을 CLI나 Python 코드로 직접 작성하려는 경우 → kpubdata-builder 사용
한국 공공데이터를 프로그래밍으로 접근만 하려는 경우 → kpubdata 사용

설치 및 개발 시작

사전 요구사항

Node 22 이상이 필요합니다. (테스트 도구가 Node 22 이상에서만 동작)

빠른 시작 (데모 모드)

git clone https://github.com/kpubdata-lab/kpubdata-studio.git
cd kpubdata-studio
npm install
npm run dev

npm run dev를 실행하면 Vite 개발 서버가 데모 모드(mock 데이터 사용)로 시작됩니다. 브라우저에서 http://localhost:5173에 접속하세요.

Builder와 함께 실행 (실 데이터)

Builder API와 실제 연동하려면:

# 방법 1: 스크립트 사용
./scripts/dev-with-builder.sh --real

# 방법 2: 수동 설정
# 터미널 1: Builder
cd ../kpubdata-builder
# CORS 는 default-deny 이므로 Studio 오리진을 허용하고, Tables·SQL 화면을 위해 warehouse 를 준다
mkdir -p build
KPUBDATA_BUILDER_DEV_MODE=true \
  KPUBDATA_BUILDER_ALLOWED_ORIGINS=http://localhost:5173 \
  uv run kpubdata-builder serve --output-dir build --warehouse build/warehouse

# 터미널 2: Studio
cd ../kpubdata-studio
cp .env.development.real .env.development.local
npm run dev

컨테이너 이미지로 배포

Dockerfile 로 이미지를 만듭니다 (#411). 이미지는 배포마다 같고, Builder 주소와 OIDC 설정은 컨테이너를 띄울 때 환경변수로 넣습니다.

docker build -t kpubdata-studio .
docker run -p 8080:8080 \
  -e BUILDER_API_URL=https://api.example.org \
  -e OIDC_ISSUER=https://sso.example.org/realms/kpubdata \
  -e OIDC_CLIENT_ID=kpubdata-studio \
  kpubdata-studio

변수	뜻
`BUILDER_API_URL`	브라우저가 부르는 Builder 주소. 설정하면 실 Builder 모드가 켜집니다
`USE_REAL_BUILDER`	`false` 로 두면 주소가 있어도 데모 데이터를 씁니다
`OIDC_ISSUER` · `OIDC_CLIENT_ID`	공개 SPA 클라이언트 설정. 비밀값이 아닙니다
`PRIVACY_URL` · `TERMS_URL`	이 배포의 개인정보 처리방침과 이용약관 페이지. 로그인·가입 화면과 계정 메뉴에 링크됩니다
`SUPPORT_CONTACT`	사용자가 문의할 곳. 메일 주소 또는 `https:` 페이지. 승인 대기·오류 화면과 계정 메뉴에 표시됩니다
`ACCOUNT_URL`	로그인 서비스의 계정 관리 화면(비밀번호 변경·탈퇴). 비워 두면 `<OIDC_ISSUER>/account`
`ASSISTANT_ENABLED`	`true` 로 두면 Ask KPubData 가 외부 AI 제공자를 부릅니다. 기본은 꺼짐입니다 (보내는 것)
`ASSISTANT_ALLOWED_ORIGINS`	Ask KPubData 가 부를 수 있는 https origin, 공백으로 구분. 켤 때 반드시 적습니다

처리방침과 약관의 문서는 Studio 에 들어 있지 않습니다. 배포를 운영하는 쪽이 작성해 공개하고 그 주소를 적습니다. 적지 않은 항목은 화면에 나타나지 않습니다.

브라우저가 Builder 를 직접 부르므로, Builder 의 KPUBDATA_BUILDER_ALLOWED_ORIGINS 에 이 Studio 의 origin 을 넣어야 합니다. 값에 따옴표·공백·< 같은 문자가 있으면 컨테이너가 그 이유를 남기고 시작하지 않습니다.

실 Builder 모드에는 로그인 설정이 함께 필요합니다. Studio 는 Builder 에 로그인 토큰(Bearer)만 보냅니다. BUILDER_API_URL 을 주면서 OIDC_ISSUER 나 OIDC_CLIENT_ID 를 비우면 페이지는 뜨지만 로그인 화면이 "인증 초기화에 실패했습니다" 에서 멈춥니다. 인증 서버가 없으면 BUILDER_API_URL 도 비워 데모로 띄웁니다.

Builder 와 한 VM 에 함께 올리기

Builder 의 docker-compose.prod.app.yml 에 studio 프로필이 있어 Builder·Caddy 와 함께 올라옵니다. 저장소를 받는 것, GHCR 로그인, .env 는 Builder 의 배포 가이드 §12 를 따릅니다.

docker compose -f docker-compose.prod.app.yml --profile caddy --profile studio up -d

위 변수는 Builder 의 .env 에 STUDIO_ 를 붙여 적습니다: STUDIO_BUILDER_API_URL, STUDIO_OIDC_CLIENT_ID, STUDIO_PRIVACY_URL, STUDIO_TERMS_URL, STUDIO_SUPPORT_CONTACT. OIDC_ISSUER 만은 Builder 와 같은 값을 같은 이름으로 씁니다.
ACCOUNT_URL, ASSISTANT_ENABLED, ASSISTANT_ALLOWED_ORIGINS 는 그 compose 가 넘기지 않습니다 (kpubdata-builder#1274).
Studio 이미지는 pull 하지 않고 STUDIO_REF 의 커밋에서 빌드합니다. 그 기본값은 Studio main 보다 오래됐을 수 있습니다.
이 절차로 올려 본 기록: docs/deploy-rehearsal.md.

주요 기능

빌드 기획서 작성: 버튼과 입력만으로 데이터셋 빌드 규칙을 설정합니다.
실시간 미리보기: 설정한 규칙에 따라 데이터가 어떻게 정리될지 즉시 확인합니다.
빌드 실행 및 모니터링: Builder와 연동하여 실제 데이터 수집 과정을 실시간 추적합니다.
결과물 검사: 생성된 데이터 파일의 구조와 내용을 시각적으로 확인합니다.

기술 스택

기술	설명
Vite	빠른 프런트엔드 빌드 도구
React	UI 라이브러리
TypeScript	타입 안정성
React Router	화면 라우팅
Zustand	셸 UI·세션 상태 관리 (서버 응답은 화면별 훅이 불러옴)
Tailwind CSS	스타일링

개발 명령어

npm run dev        # 개발 서버 실행
npm run lint       # ESLint 검사
npm test           # Vitest 테스트
npm run build      # 프로덕션 빌드
npm run preview    # 빌드 결과 프리뷰

문서

문서	설명
ARCHITECTURE.md	시스템 아키텍처
STATE_MODEL.md	상태 관리 모델
UI_SPEC.md	UI 명세
AGENTS.md	AI 에이전트 가이드
CONTRIBUTING.md	기여 가이드
PRD.md	제품 요구사항

더 자세한 정보는 docs/ 디렉토리를 참고하세요. Keycloak 인증 설정 및 문제 해결은 docs/troubleshooting.md를 확인하세요.

제품군

패키지	역할
kpubdata	접근 + 파싱 + 정규화 SDK
kpubdata-builder	데이터셋 조립 + 파이프라인
kpubdata-studio	시각적 인터페이스

English: See README.en.md

Name		Name	Last commit message	Last commit date
.github		.github
__tests__		__tests__
assets		assets
docker		docker
docs		docs
e2e		e2e
overrides		overrides
public		public
screens		screens
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.development		.env.development
.env.development.real		.env.development.real
.gitignore		.gitignore
.gitleaksignore		.gitleaksignore
.npmrc		.npmrc
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
API_CONTRACT.md		API_CONTRACT.md
ARCHITECTURE.md		ARCHITECTURE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
INFORMATION_ARCHITECTURE.md		INFORMATION_ARCHITECTURE.md
LICENSE		LICENSE
PRD.md		PRD.md
README.en.md		README.en.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
STATE_MODEL.md		STATE_MODEL.md
UI_SPEC.md		UI_SPEC.md
USER_FLOWS.md		USER_FLOWS.md
eslint-suppressions.json		eslint-suppressions.json
eslint.config.mjs		eslint.config.mjs
index.html		index.html
mkdocs.yml		mkdocs.yml
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
playwright.keycloak.config.ts		playwright.keycloak.config.ts
playwright.multiuser.config.ts		playwright.multiuser.config.ts
playwright.real.config.ts		playwright.real.config.ts
postcss.config.mjs		postcss.config.mjs
requirements-docs.txt		requirements-docs.txt
screenshots.md		screenshots.md
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vite.csp.ts		vite.csp.ts
vitest.config.ts		vitest.config.ts
vitest.setup.ts		vitest.setup.ts

Navigation Menu

Repository navigation

About

Repository files navigation

KPubData Studio

이 프로젝트가 존재하지 않는 경우

설치 및 개발 시작

사전 요구사항

빠른 시작 (데모 모드)

Builder와 함께 실행 (실 데이터)

컨테이너 이미지로 배포

Builder 와 한 VM 에 함께 올리기

주요 기능

기술 스택

개발 명령어

문서

제품군

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

KPubData Studio

이 프로젝트가 존재하지 않는 경우

설치 및 개발 시작

사전 요구사항

빠른 시작 (데모 모드)

Builder와 함께 실행 (실 데이터)

컨테이너 이미지로 배포

Builder 와 한 VM 에 함께 올리기

주요 기능

기술 스택

개발 명령어

문서

제품군

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages