> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getporter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 소스 코드로 앱 배포・운영

> GitHub 저장소, Git URL 또는 템플릿을 사용해 애플리케이션을 직접 배포합니다.

<Card>
  사이드바의 애플리케이션 메뉴에서 서비스를 직접 배포하거나 관리할 수 있습니다.
</Card>

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy01.png" />
</Frame>

> 애플리케이션 메뉴의 <Icon icon="circle-plus" iconType="solid" size={15} color="2396F1" /> 또는 `⌘ + K`로 생성되는 배포 창을 통해 배포 과정이 시작됩니다.

<Warning>
  애플리케이션 배포 기능은 Porter AI 엔터프라이즈 환경에서 지원하며, 퍼블릭 서비스에서는 지원 예정입니다.
</Warning>

## 애플리케이션 배포하기

### 배포방식 선택

<AccordionGroup>
  <Accordion title="내 GitHub 저장소 배포하기">
    #### 배포할 저장소 선택

    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy02.png" />
    </Frame>

    배포 창에서 **Git 저장소 배포하기**를 클릭한 후, 연동된 GitHub 계정의 저장소를 선택하세요.

    #### 언어/프레임웍 선택

    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy03.png" />
    </Frame>

    배포할 저장소에 맞는 프리셋을 선택하세요.

    <Tip>
      React, vue 등과 같은 정적 페이지의 경우 **Web Application**을 선택해 주세요.
    </Tip>
  </Accordion>

  <Accordion title="Git URL로 배포하기">
    #### 배포키 등록

    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy04.png" />
    </Frame>

    Git 저장소 배포하기 화면에서 **Git URL 탭**을 선택한 후, 배포하려는 저장소의 **SSH 방식의 Git URL**을 입력하면 자동으로 생성된 \*\*배포 키(Deploy Key)\*\*를 조회할 수 있습니다.

    <Info>
      **GitHub**뿐만 아니라 **GitLab, Bitbucket** 등에 반영된 비공개 저장소의 코드도 배포할 수 있도록 SSH 방식의 인증을 지원합니다. 플랫폼별 배포 키 등록은 아래를 참고해 주세요
    </Info>

    <AccordionGroup>
      <Accordion title="GitHub ">
        <Frame>
          <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/06_06.png" />
        </Frame>

        배포하려는 저장소의 **Settings > Deploy keys** 화면 우측 상단의 `Add deploy key`를 클릭한 후 배포 창에서 조회한 배포 키 값을 입력해 키를 추가합니다.
      </Accordion>

      <Accordion title="GitLab">
        <Frame>
          <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/06_07.png" />
        </Frame>

        배포하려는 저장소의 **Settings > Repository** 화면에서 **Deploy keys** 항목의 `Expand`, `Add new key`를 클릭한 후 배포 창에서 조회한 배포 키 값을 입력해 키를 추가합니다.
      </Accordion>

      <Accordion title="Bitbucket">
        <Frame>
          <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/06_08.png" />
        </Frame>

        배포하려는 저장소의 **Repository settings > Access keys** 화면에서 `Add key`를 클릭한 후 배포 창에서 조회한 배포 키 값을 입력해 키를 추가합니다.
      </Accordion>
    </AccordionGroup>

    #### 언어/프레임웍 선택

    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy05.png" />
    </Frame>

    배포할 저장소에 맞는 프리셋을 선택하세요.

    <Tip>
      React, vue 등과 같은 정적 페이지의 경우 **Web Application**을 선택해 주세요.
    </Tip>
  </Accordion>

  <Accordion title="템플릿을 선택해서 배포하기">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy06.png" />
    </Frame>

    개발한 서비스에 적합한 템플릿을 선택한 후 연동된 GitHub 저장소 선택 또는 Git URL을 입력하세요.

    <Tip>
      React, vue 등과 같은 정적 페이지의 경우 **Web Application**을 선택해 주세요.
    </Tip>
  </Accordion>
</AccordionGroup>

<Tip>
  제공되는 템플릿 / 프리셋은 기본 모듈 및 라이브러리가 상이합니다. <Icon icon="windows" size={15} color="9fa3a5" /> Windows, <Icon icon="chrome" size={15} color="9fa3a5" /> Chrome 라이브러리처럼 기본으로 제공되지 않는 라이브러리를 사용하려는 경우, Dockerfile을 작성하고 Dockerfile 템플릿으로 배포해야 합니다.
</Tip>

### 배포 설정과 배포

배포할 저장소와 프리셋 또는 템플릿을 선택한 후, 배포에 관한 아래의 항목을 설정하고 배포하세요.

<AccordionGroup>
  <Accordion title="브랜치와 서브 디렉토리">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy07.png" />
    </Frame>

    저장소 선택 후 **브랜치와 서브 디렉토리**를 설정할 수 있는 필드가 표시됩니다. 하나의 저장소에 여러 개의 서비스를 별도의 폴더로 관리하는 경우처럼, **루트디렉토리가 아닌 하위 폴더에 배포할 서비스가 존재**하는 경우 **서브 디렉토리** 필드에 그 경로를 입력하세요.

    <Info>
      서브 디렉토리를 설정을 하지 않은 경우, 루트 디렉토리에서 배포가 실행됩니다.
    </Info>
  </Accordion>

  <Accordion title="버전">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy08.png" />
    </Frame>

    프리셋의 버전을 배포할 저장소에 맞게 선택하세요.

    <Warning>
      프로젝트 설정 파일(build.gradle, requirements.txt, package.json 등)에 명시된 버전과 배포 설정 시 선택한 버전이 일치하지 않으면 빌드 또는 런타임 오류가 발생할 수 있습니다.
    </Warning>
  </Accordion>

  <Accordion title="환경 변수">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy09.png" />
    </Frame>

    환경 변수는 다음 방식들을 조합하여 추가할 수 있습니다:

    * ENV 파일 Drag & Drop
    * (+) 아이콘으로 새로운 변수를 직접 입력
    * 열쇠 아이콘을 사용해 저장된 시크릿 중에서 선택

    <Info>
      환경 변수는 직접 입력하거나 저장된 시크릿을 선택해 적용할 수 있습니다.
    </Info>
  </Accordion>

  <Accordion title="포트 번호">
    포트 번호는 소스 코드 혹은 환경 변수의 설정과 일치해야 하며 정확하지 않은 포트 번호를 입력하거나 공란으로 한 경우, 서비스가 정상적으로 작동하지 않을 수 있습니다.

    <Warning>
      포트 번호에는 기본값이 적용되지 않으므로 소스 코드나 환경 변수에 지정한 값과 동일하게 입력하세요.
    </Warning>
  </Accordion>

  <Accordion title="Install, Build, Start Command">
    서비스의 라이프사이클 명령어를 설정하세요. 각 필드에는 기본 명령어가 표시되어 있으며, 프로젝트 설정에 맞게 변경할 수 있습니다

    * **Install Command**: 의존성 패키지 설치 명령어 (예: `npm install`, `pip install -r requirements.txt`)
    * **Build Command**: 애플리케이션 빌드 명령어 (예: `npm run build`, `gradle build`)
    * **Start Command**: 서비스 실행 명령어 (예: `npm start`, `python app.py`)

    <Info>
      필드값을 입력하지 않으면 placeholder에 표시된 기본값이 적용됩니다.
    </Info>
  </Accordion>

  <Accordion title="더 많은 옵션">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy10.png" />
    </Frame>

    추가로 설정값을 입력할 수 있는 필드가 표시됩니다.

    <Info>
      표시되는 필드는 템플릿 / 프리셋 별로 다릅니다.
    </Info>
  </Accordion>

  <Accordion title="성능(리소스) 설정과 배포">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy11.png" />
    </Frame>

    * **CPU** : 서비스가 사용할 vCPU 리소스의 최댓값을 설정하며, '최소 vCPU' 선택 시 0.1 vCPU 사용

    * **메모리** : 서비스가 사용할 메모리 리소스의 최댓값을 설정

    * **디스크** : 데이터베이스를 배포할 경우 표시되는 필드로, 데이터베이스가 차지할 디스크의 용량 설정

    * **동시 실행(레플리카)** : 설정한 수만큼 서비스가 수평 확장되어 부하 분산 및 안정성 확보

    * **배포** : `배포하기` 클릭
  </Accordion>
</AccordionGroup>

## 애플리케이션 관리하기

### 로그 조회와 터미널 접속

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy12.png" />
</Frame>

> 서비스 카드 또는 상세 페이지의 **<Icon icon="terminal" size={15} color="9fa3a5" /> 아이콘**을 클릭하면, 배포/실행 로그 조회 또는 터미널에 접속할 수 있습니다.

### 재배포(업데이트)

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy13.png" />
</Frame>

> **코드 수정, 리소스 변경 등** 업데이트할 내역이 있는 경우, 서비스 설정 화면 하단부의 `배포하기` 버튼을 누르면 업데이트를 반영한 새로운 배포가 진행됩니다.

### 서비스 중지 / 재시작

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy18.png" />
</Frame>

> 서비스 카드의 스톱 / 플레이 버튼으로 서비스를 중지하거나 재시작할 수 있습니다.

### 롤백(복원)

<Frame>
  <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy14.png" />
</Frame>

> **서비스 상세 페이지의 배포 내역 탭**에서 이전 버전의 서비스 상태로 복원할 수 있습니다.

<Tip>
  복원할 버전을 혼동하지 않기 위해, 커밋 메시지를 확인하세요.
</Tip>

## 트러블슈팅

<AccordionGroup>
  <Accordion title="서브 디렉토리 미적용 (Error: Project files not found)">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy07.png" />
    </Frame>

    배포 시 루트 디렉토리를 기준으로 빌드가 진행됩니다. 저장소의 루트 디렉토리가 아닌 서브 디렉토리에 실행할 소스가 있는 경우 별도로 서브 디렉토리를 지정해주어야 합니다.
  </Accordion>

  <Accordion title="버전 불일치">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy08.png" />
    </Frame>

    배포할 프로젝트를 개발할 때 적용한 JDK, Python, Node.js 등의 버전과 배포 과정에서 적용한 버전이 서로 다를 경우 서비스가 정상적으로 빌드 혹은 실행되지 않습니다.
    프로젝트의 언어와 플랫폼에 맞는 버전을 설정한 후 재배포하세요.
  </Accordion>

  <Accordion title="포트 번호 문제">
    특정 포트에서 서비스되는 프로젝트의 경우, 배포 설정에서 포트 번호가 누락되거나 잘못 입력되면 정상적으로 실행되지 않을 수 있습니다.
    **특정 포트에 바인딩되지 않는 프로젝트의 경우, 배포 설정에서 포트 번호 항목을 공란으로 두어야 합니다.**
  </Accordion>

  <Accordion title="selenium, puppeteer 등의 Chrome 라이브러리 사용">
    제공되는 템플릿은 기본 모듈 및 라이브러리가 상이합니다. <Icon icon="windows" size={15} color="9fa3a5" /> Windows, <Icon icon="chrome" size={15} color="9fa3a5" /> Chrome 라이브러리처럼 기본으로 제공되지 않는 라이브러리를 사용하려는 경우, Dockerfile을 작성하고 Dockerfile 템플릿으로 배포해야 합니다.
  </Accordion>

  <Accordion title="CORS 문제">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy16.png" />
    </Frame>

    React, Vue 등의 정적 페이지를 Web Application 템플릿으로 배포할 때 Rewrites 값을 설정하면, 프런트엔드에서 호출한 경로를 실제 API 주소로 연결할 수 있습니다. 리버스 프록시 기능을 적용하려는 React 등의 프런트엔드 서비스의 코드 중 외부의 **API URL을 호출하는 부분을 자기 자신을 호출하도록 작성**해야 하며, 서비스의 배포 설정 화면에 **Rewrites** 필드를 아래와 같은 규칙으로 입력해 리버스 프록시를 적용할 수 있습니다.

    * **좌측 필드** : 코드에 작성된 호출 경로
    * **우측 필드** : 실제로 호출해야 할 경로

    <Info>
      드롭다운 메뉴에서 같은 프로젝트에 있는 서비스를 선택하고 경로를 추가하거나, URL을 직접 입력할 수 있습니다.
    </Info>
  </Accordion>

  <Accordion title="오류에 대한 실행 로그가 보이지 않는 경우">
    서비스 패널의 **플레이 버튼으로 재시작** 후 실행 로그를 확인해보세요. 어떤 로그도 표시되지 않는다면 서비스 상세 페이지의 **이벤트 탭**에서 발생한 이벤트를 확인하여 문제를 해결해야 합니다.
  </Accordion>

  <Accordion title="리소스 부족(out of memory)">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/deploy17.png" />
    </Frame>

    JVM 기반의 애플리케이션을 배포하는 경우 JVM에 할당한 메모리가 사용 가능한 리소스의 범위를 초과할 때 OOM이 발생할 수 있으며, Node.js 역시 heap 메모리의 부족으로 같은 현상이 발생할 수 있습니다.
    언어 혹은 프레임워크에서 적절하게 메모리를 부여하거나 리소스를 추가로 할당하여 배포해야 합니다.
  </Accordion>

  <Accordion title="타임존">
    <Frame>
      <img className="block rounded-md" src="https://files.cloudtype.io/ale-docs/developers/images/06_21.png" />
    </Frame>

    일반적인 프레임워크에서는 `TZ`라는 환경 변수를 통해 타임존을 설정할 수 있으며, [여기](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 제시된 일람에 따라 국가 및 도시를 설정할 수 있습니다.
    이외의 방법은 사용하고 있는 프레임워크의 공식 문서를 참고하시기 바랍니다.
  </Accordion>
</AccordionGroup>