Shipyard

01문제 · 해결책 · 사용자 · 성공 기준

개요

문제

아이디어를 실제로 배포하는 과정은 코드 작성만큼 간단하지 않습니다. 개발자는 프로젝트의 실행 방식과 인프라 설정을 파악하고, 환경별 설정을 맞추고, 배포 실패를 디버깅해야 합니다. 팀원이나 이해관계자에게 변경사항을 보여주기 위한 프리뷰 환경도 별도로 구성하고 관리해야 합니다.

특히 다음 문제가 반복됩니다.

저장소마다 실행 명령, 포트, 빌드 방식이 달라 초기 설정에 시간이 듭니다.
로컬과 클라우드 환경별 설정이 달라 환경 차이로 인한 실패가 발생합니다.
프리뷰 배포가 수작업이거나 상시 운영 환경에 의존해 비용과 관리 부담이 생깁니다.
배포 로그는 많지만, 실패 원인과 다음 조치가 명확하지 않습니다.

제안하는 해결책

Shipyard는 저장소를 분석해 배포에 필요한 정보를 추출하고, 이를 공통 배포 템플릿으로 표현합니다. 사용자는 같은 프로젝트 정의를 바탕으로 로컬 Docker, AWS, GCP 중 목표 환경을 선택합니다. 브랜치나 변경사항에 대해서는 만료 시간이 지정된 임시 프리뷰 환경을 만들고, 검토가 끝나면 자동으로 정리합니다.

핵심 경험은 저장소 연결 → AI 분석 결과 확인 → 환경 선택 → 배포 또는 프리뷰 링크 공유입니다. 복잡한 인프라 작업은 기본값과 추상화로 감추되, 사용자가 설정과 결과를 확인하고 제어할 수 있도록 합니다.

목표 사용자

빠르게 데모와 프로토타입을 공개해야 하는 개발자와 해커톤 팀
여러 환경에 같은 애플리케이션을 배포하는 소규모 팀
코드 리뷰 전에 실제 동작을 공유하고 싶은 제품·디자인 팀
배포 경험은 필요하지만 인프라 설정을 직접 관리하고 싶지 않은 팀

해커톤 목표 및 성공 기준

해커톤 결과물은 완전한 범용 클라우드 플랫폼이 아니라, 한 가지 대표 앱을 대상으로 핵심 흐름을 끝까지 시연하는 MVP입니다.

샘플 저장소를 분석해 언어·프레임워크·실행 명령·포트를 제안한다.
공통 템플릿 하나로 로컬 Docker 실행과 최소 한 개 클라우드 대상 배포 흐름을 설명하거나 시연한다.
변경사항에 대해 고유한 프리뷰 URL과 상태를 제공하고, 만료·정리 정책을 보여준다.
빌드 또는 배포 실패 시 로그 요약, 원인 후보, 다음 조치를 사용자에게 제시한다.
사람이 검토하고 승인할 수 있도록 AI가 추론한 설정과 실제 적용 설정을 구분한다.

02구성 요소 · 데이터 흐름

핵심 아키텍처

저장소 분석부터 환경 어댑터, 프리뷰 수명주기 관리까지의 구조는 다음과 같습니다. 공통 배포 명세가 가운데를 지나 각 대상 환경 어댑터로 전달됩니다.

architecture.txt

사용자 / Git 저장소
        │
        ▼
웹 콘솔 및 API ─────────────── Git 이벤트(Webhook)
        │                              │
        ▼                              ▼
저장소 분석기(AI + 규칙)       프리뷰 오케스트레이터
        │                              │
        └──────────▼───────────────────┘
               공통 배포 명세
                      │
           템플릿 렌더러 / 검증기
                      │
       ┌──────────────┼──────────────┐
       ▼              ▼              ▼
 Local Docker     AWS Adapter     GCP Adapter
       │              │              │
       └──────────────┴──────────────┘
                      │
       상태·로그·URL·만료 및 정리 관리

1) 저장소 인입 및 코드 분석

저장소 파일 구조, 매니페스트, Dockerfile, 환경 변수 예시, 빌드 스크립트를 읽습니다.
규칙 기반 탐지와 AI 분석을 함께 사용해 언어, 프레임워크, 빌드·시작 명령, 서비스 포트, 정적 파일 경로 등을 추론합니다.
분석 결과에는 근거 파일과 신뢰도 또는 확실성 표시를 포함합니다.
비밀키와 민감정보는 로그나 모델 입력에 노출되지 않도록 마스킹하거나 제외합니다.
AI가 제안한 명령은 자동으로 신뢰하지 않고, 검증·사용자 확인 단계를 거친 뒤 실행합니다.

2) 공통 배포 명세 (추상 템플릿 엔진)

환경별 구현 세부사항을 애플리케이션 정의와 분리합니다. 프로젝트는 서비스, 빌드, 포트, 환경 변수 참조, 리소스 요구량, 헬스체크를 공통 명세에 선언하고, 대상 어댑터가 이를 로컬 Docker 또는 각 클라우드의 리소스로 변환합니다.

spec.yaml · 개념 예시

project:
  name: sample-app
  build:
    command: npm run build
  run:
    command: npm run start
  port: 3000
  healthcheck: /health
  env:
    - DATABASE_URL
  preview:
    ttl: 24h

위 예시는 제안서의 개념 설명용이며, 실제 MVP에서는 지원 범위를 좁혀 명세 필드와 템플릿을 고정합니다. 템플릿은 변수 치환만 하는 파일이 아니라, 입력 검증·기본값·환경별 오버라이드·렌더링 결과 검증을 포함하는 인터페이스로 설계합니다.

3) 템플릿 렌더러와 환경 어댑터

공통 명세를 읽어 대상 환경에 맞는 실행 계획과 설정을 생성합니다.
Local Docker 어댑터는 컨테이너 이미지 빌드와 실행 구성을 생성합니다.
AWS 및 GCP 어댑터는 공통 인터페이스 뒤에 두어 공급자별 구현을 분리합니다.
배포 전 plan 단계에서 변경될 리소스와 필요한 설정을 보여주고, 승인 이후 apply를 수행하는 방향을 지향합니다.
어댑터별 기능 차이는 숨기지 않고 지원 여부와 필요한 추가 설정을 명시합니다.

4) 프리뷰 환경 오케스트레이터

브랜치 또는 Pull Request 이벤트를 받아 고유한 프리뷰 작업을 생성합니다.
빌드·배포 상태와 접근 URL을 추적합니다.
프리뷰에는 TTL(기본 만료 정책)을 부여하고, 종료·만료 시 관련 리소스를 정리합니다.
같은 브랜치의 새 커밋은 기존 프리뷰를 갱신하거나 새 실행으로 대체할 수 있습니다.
중복 이벤트 처리, 실패 시 재시도, 수동 종료를 고려합니다.

5) 상태·로그·보안 경계

프로젝트, 배포 실행, 프리뷰 URL, 환경, 만료 시각, 로그 요약을 기록합니다.
시크릿 값 자체가 아니라 시크릿 이름과 참조만 배포 명세에 저장합니다.
클라우드 자격 증명은 최소 권한 원칙으로 사용하고, 사용자별 또는 프로젝트별 경계를 둡니다.
외부 코드의 빌드·실행은 격리된 작업 환경에서 수행하며, 실행 시간과 리소스 사용량을 제한합니다.
위험한 명령, 권한 확대, 공개 네트워크 노출 등은 명시적인 승인과 정책 검사를 요구합니다.

데이터 흐름

1사용자가 저장소를 연결하고 대상 환경을 선택합니다.
2분석기가 저장소를 읽고 배포 후보 설정과 근거를 생성합니다.
3사용자는 후보 설정을 검토하고 필요한 값을 입력·승인합니다.
4템플릿 엔진이 공통 명세를 검증하고 환경별 실행 계획을 렌더링합니다.
5배포 실행기가 빌드와 배포를 수행하며 상태·로그를 수집합니다.
6성공 시 URL을 제공하고, 프리뷰라면 TTL과 정리 일정을 등록합니다.
7만료 또는 종료 시 리소스를 정리하고 결과를 기록합니다.

03MVP 범위

주요 기능

A.AI 코드 분석 및 배포 준비도 진단
- 저장소의 주요 언어와 프레임워크 식별
- 실행에 필요한 빌드·시작 명령, 서비스 포트, 헬스체크 경로 제안
- 필요한 환경 변수 이름 탐지 및 누락 항목 안내
- 배포 전 체크리스트 생성: 예를 들어 시작 명령 없음, 포트 불일치, 빌드 스크립트 누락
- 배포 로그를 짧은 원인 설명과 다음 확인 단계로 요약
- 모든 제안에 근거 파일 또는 로그 구간을 연결하고, 불확실한 값은 확인 요청
B.추상 템플릿 엔진과 다중 환경 배포
- 환경에 독립적인 프로젝트 명세 한 번 작성
- Local Docker / AWS / GCP 배포 대상으로 명세 렌더링
- 공통 기본값과 환경별 오버라이드 지원
- 렌더링 전 스키마 검증, 누락 필드·미지원 기능 사전 안내
- 실행 계획 확인 후 배포하는 승인 단계 제공
- MVP에서는 각 대상의 전체 기능을 동등하게 구현하기보다 공통 인터페이스와 한두 개 대표 경로에 집중
C.임시 프리뷰 환경
- 브랜치 또는 PR 단위 프리뷰 생성
- 빌드 중·성공·실패·만료 상태 표시
- 프리뷰 URL, 생성 시각, 대상 환경, 만료 예정 시각 표시
- TTL 만료 후 자동 정리 및 수동 종료 기능
- 정리 실패 시 재시도와 운영자 확인이 필요한 상태 표시
D.간단한 배포 경험
- 초보자도 따라갈 수 있는 단계형 흐름: 저장소 선택 → 분석 확인 → 환경 선택 → 미리보기 → 배포
- 복잡한 설정은 기본값으로 시작하되, 고급 설정을 열어 세부 제어 가능
- 결과 화면에서 성공 URL, 배포 로그, 사용한 템플릿, 환경 정보를 한눈에 제공
- 실패 메시지를 로그 원문과 AI 요약으로 나누어 제공
E.MVP 범위와 제외 범위
- 저장소 분석 및 설정 제안
- 공통 배포 명세와 검증
- 로컬 Docker 경로
- 한 개 클라우드 환경의 대표적인 배포 경로 또는 실제 자격 증명 없이 시연 가능한 어댑터 모드
- PR/브랜치 프리뷰 생성, URL·상태 표시, TTL 정리 흐름
- 기본 로그와 오류 요약

초기 범위에서 제외하거나 후속 과제로 둠

모든 언어·프레임워크·클라우드 서비스에 대한 포괄 지원
복잡한 네트워크 토폴로지와 엔터프라이즈 정책 관리
완전한 비용 최적화·자동 스케일링
AI가 검토 없이 임의의 인프라 변경을 수행하는 자동화
다중 리전 고가용성 및 운영급 SLA 보장

04웹 앱 PR을 임시 환경으로 배포

데모 시나리오

데모용 웹 애플리케이션의 Pull Request를 검토 가능한 임시 환경으로 배포하는 전체 흐름입니다.

저장소 연결

데모용 웹 애플리케이션 저장소를 선택합니다.

AI 분석

Shipyard가 프레임워크, 빌드 명령, 시작 명령, 포트를 분석합니다. 결과 화면은 각 제안의 근거 파일을 함께 보여줍니다.

검토 및 수정

사용자는 추론된 포트나 환경 변수 목록을 확인합니다. 확실하지 않은 설정은 자동 적용하지 않고 확인을 요청합니다.

환경 선택

먼저 Local Docker를 선택해 공통 명세가 컨테이너 실행 구성으로 변환되는 것을 확인합니다. 이어 클라우드 대상 배포 계획을 렌더링합니다.

배포 계획 확인

생성될 대상과 필요한 시크릿 참조, 예상 작업을 미리 보여줍니다. 사용자가 승인한 뒤 실행합니다.

PR 프리뷰 생성

새 PR 이벤트를 흉내 내거나 실제 Webhook을 전달해 고유 프리뷰 작업을 시작합니다.

결과 공유

대시보드에 빌드 상태와 프리뷰 URL, TTL이 나타납니다. 팀원이 링크에서 변경 화면을 확인합니다.

실패 처리 데모 (선택)

잘못된 빌드 명령을 넣어 실패를 발생시키고, AI가 관련 로그와 가능한 수정 방향을 요약하는 모습을 보여줍니다.

정리

프리뷰를 수동 종료하거나 TTL 만료를 시뮬레이션합니다. 리소스 정리 상태와 종료 기록을 확인합니다.

데모에서 전달할 핵심 메시지

개발자는 배포 도구를 여러 개 직접 조합하지 않고 하나의 흐름으로 시작할 수 있습니다.
같은 애플리케이션 정의를 여러 환경에 재사용할 수 있습니다.
AI는 설정을 제안하고 실패 분석을 돕지만, 중요한 실행은 검증과 승인 뒤에 수행됩니다.
프리뷰는 일회성 검토 자원으로 만들고 사용 후 정리할 수 있습니다.

05구현 가능한 출발점

기술 스택 제안

아래는 구현 가능한 출발점이며, 해커톤 팀의 익숙한 도구와 실제 배포 환경에 맞춰 조정합니다.

영역	제안	역할
웹 콘솔	React 또는 Next.js, TypeScript	프로젝트 연결, 분석 결과, 배포 상태와 프리뷰 URL 표시
API / 오케스트레이션	Node.js(TypeScript) 또는 Python(FastAPI)	저장소 분석, 배포 작업 생성, 상태 조회 API
AI 분석	LLM API + 규칙 기반 탐지	코드 구조 요약, 배포 설정 후보와 로그 설명 생성
공통 명세	YAML/JSON + JSON Schema	환경 독립적인 프로젝트 및 프리뷰 설정 표현
템플릿 렌더링	자체 렌더러 또는 제한된 템플릿 엔진	명세를 검증하고 어댑터 입력으로 변환
컨테이너	Docker / Docker Compose	로컬 빌드와 실행, 데모의 재현성 확보
클라우드 어댑터	AWS 및 GCP SDK/CLI 또는 IaC 도구	대상별 배포 구현을 공통 인터페이스 뒤에 격리
비동기 작업	Redis 기반 큐 또는 클라우드 작업 큐	빌드·배포·정리 작업 실행과 상태 추적
상태 저장	PostgreSQL 또는 SQLite(데모)	프로젝트, 실행, 프리뷰, 만료 상태 저장
이벤트 연결	GitHub Webhooks	PR/브랜치 이벤트 기반 프리뷰 생성
관측성	구조화 로그와 작업별 상태 이벤트	디버깅 및 실행 이력 확인

구현 원칙

해커톤 시간 안에 하나의 엔드투엔드 경로를 먼저 완성합니다.
로컬 Docker를 기준 경로로 두어 클라우드 자격 증명이나 네트워크 문제에도 데모가 가능하게 합니다.
클라우드 어댑터는 인터페이스로 분리하고, 지원하지 않는 기능은 명확한 오류로 반환합니다.
생성한 배포 명세와 실제 실행 계획을 화면에서 비교할 수 있게 합니다.
시크릿 값은 저장소·로그·AI 프롬프트에 포함하지 않습니다.

06자주 묻는 질문

Q&A

Q1.

AI가 잘못된 배포 설정을 만들면 어떻게 하나요?

AI 결과는 확정된 설정이 아니라 후보입니다. 탐지 결과에 근거와 불확실성을 표시하고, 명세 검증과 미리보기 단계를 거칩니다. 리소스 생성이나 공개 배포 같은 영향이 있는 작업은 사용자의 승인을 받은 뒤 실행합니다. 규칙 기반 검증으로 필수 값과 위험한 설정을 추가 확인합니다.

Q2.

로컬 Docker와 AWS/GCP가 서로 다른데 어떻게 같은 템플릿을 쓰나요?

애플리케이션의 공통 요구사항과 공급자별 구현을 분리합니다. 공통 명세에는 빌드·실행·포트·환경 변수 참조 같은 보편 항목을 두고, 어댑터가 이를 대상 환경의 구체적인 설정으로 변환합니다. 공급자에 따라 의미가 다른 기능은 무리하게 동일하게 보이게 하지 않고, 미지원 또는 추가 설정 필요 상태로 표시합니다.

Q3.

프리뷰 환경이 계속 남아 비용이 늘지 않나요?

프리뷰마다 TTL을 부여하고 만료 시 자동 정리를 수행하는 것이 기본입니다. 수동 종료도 제공하고, 정리 작업의 성공 여부를 기록합니다. 클라우드 리소스 태그와 생성 이력을 연결해 정리 실패를 탐지할 수 있도록 합니다. MVP에서는 만료 처리와 상태 확인 흐름을 우선 구현합니다.

Q4.

저장소의 비밀키나 사용자 데이터는 어떻게 보호하나요?

분석 과정에서 시크릿 패턴을 마스킹하고, 분석 목적에 필요하지 않은 민감 데이터는 처리하지 않는 원칙을 둡니다. 비밀값은 배포 명세에 평문으로 저장하지 않고 시크릿 이름이나 안전한 참조만 전달합니다. 빌드 실행은 격리하고, 작업별 권한과 리소스를 제한합니다. 데모에서는 실제 운영 비밀키 대신 가짜 값이나 비밀 저장소 참조를 사용합니다.

Q5.

어떤 프로젝트든 지원하나요?

초기 버전은 대표적인 웹 앱 유형과 제한된 런타임에 집중합니다. 저장소 분석 결과 지원 범위를 벗어나면 추측으로 배포하지 않고, 지원되지 않는 항목과 필요한 수동 설정을 알려줍니다. 이후 실제 사용에서 자주 등장하는 프레임워크와 어댑터를 추가합니다.

Q6.

기존 CI/CD 도구를 대체하나요?

목표는 모든 CI/CD 기능을 다시 만드는 것이 아닙니다. 저장소 분석, 공통 템플릿, 프리뷰 생성, 여러 환경의 단순한 배포 경험을 한 흐름으로 연결하는 데 초점을 둡니다. 필요하다면 기존 CI 시스템을 빌드 실행기로 연결하고, Shipyard는 명세·환경 선택·프리뷰 수명주기를 관리할 수 있습니다.

Q7.

프리뷰 URL은 누가 접근할 수 있나요?

접근 정책은 환경별로 다르게 설정할 수 있게 설계합니다. 기본값은 팀 내부 공유 또는 보호된 접근으로 두고, 공개 URL이 필요한 경우 사용자가 이를 명시적으로 선택합니다. 해커톤 데모에서는 공개 여부와 데모 환경의 제한을 분명히 안내합니다.

Q8.

해커톤 이후 확장 방향은 무엇인가요?

우선 프레임워크와 어댑터를 확장하고, 프로젝트별 템플릿 버전 관리·팀 권한·비용 추적·정책 검사·롤백을 추가할 수 있습니다. 더 나아가 AI 분석 결과를 배포 이력과 연결해 반복적인 설정 수정을 줄이고, 안전한 자동화 범위를 단계적으로 넓힐 수 있습니다.

07제안 요약

코드에서 시작해, 승인된 배포와 프리뷰 정리까지

Shipyard는 AI 코드 분석, 환경 독립적인 템플릿 엔진, 수명이 제한된 프리뷰 환경을 하나의 간단한 배포 경험으로 묶습니다. 해커톤에서는 범용 클라우드 플랫폼을 완성하려 하기보다, 저장소 분석부터 승인된 배포와 프리뷰 정리까지 이어지는 한 가지 성공 경로를 구현합니다. 이를 통해 배포를 쉽게 시작하고, 안전하게 검토하고, 사용 후 정리하는 개발자 경험을 보여주는 것을 목표로 합니다.

원문 제안서 다운로드 (.md)

개요

문제