Skip to Content
문서App Deploy (OTA)

App Deploy (OTA)

App Deploy는 Deplite가 배포 서버(OTA) 역할을 하도록 해주는 기능이에요.
아티팩트를 조직 스토리지에 보관하고, 기기는 온라인이 될 때 스스로 최신 릴리스로 수렴해요.
키오스크나 현장 단말처럼 항상 켜져 있지 않은 기기에 적합해요.

왜 필요한가요

기기는 항상 온라인 상태가 아닐 수 있어요.
App Deploy는 릴리스 게시 후 기기가 부팅되거나 다시 연결될 때 원하는 릴리스를 조회해 최신 상태로 수렴하게 해요.
서버의 원하는 상태가 기준이고, SSE 연결 중 push 알림은 기기를 깨워 다시 조회하게 하는 신호예요.

보안 원칙은 그대로예요

적용(설치·재시작) 로직은 여전히 고객 workflow yaml에만 있어요.
Deplite가 아는 것은 두 가지뿐이에요.

  1. 실행할 로컬 workflow 이름 (Application.updateWorkflowName, 예: app-update)
  2. 배포할 아티팩트 (스토리지에 보관된 파일)

OTA 적용은 결국 “이 아티팩트를 파라미터로 넣어 기기의 로컬 app-update.yaml을 실행한다”라는 뜻이에요.
어떻게 설치하고 재시작하는지는 전부 고객 워크플로우 안에만 있어요.
별도의 실행 엔진이 새로 생기지 않고, 기존 Job·로그·결과 인프라를 그대로 사용해요.

Deplite는 아티팩트의 내용이나 설치 절차를 해석하지 않아요.
“어떤 아티팩트를 어떤 워크플로우로 넘길지”만 결정하고, 실제 적용 방식은 워크플로우에 위임해요.

데이터 모델

App Deploy는 세 가지 개념으로 이루어져 있어요.

Application

배포 대상 앱 하나를 표현해요.
적용에 쓸 workflow 이름(updateWorkflowName), 기본 채널(defaultChannel, 기본값 stable), 조직 내에서 유일한 slug를 가져요.

Release — 게시 후 불변

하나의 배포 단위예요.
게시(publish)하고 나면 내용이 바뀌지 않아요.

필드의미
sequenceapp 범위에서 단조 증가하는 정수. 순서의 진실원본 (max+1)
version사람이 읽는 라벨. 표시 전용
channelstable / beta 또는 임의 채널
fileId배포할 아티팩트 참조
checksumSha256업로드 시 제공. Agent가 다운로드 후 검증
updatePolicyoptional 또는 mandatory
statusdraft → published → yanked

AppDevice

앱과 Agent를 묶고, 그 기기의 현재 상태를 담아요.
구독 중인 channel, 관측된 현재 릴리스(currentReleaseId 등), 희망 릴리스(targetReleaseId), state(idle·pending·updating·failed), 그리고 기기당 in-flight job을 1개로 보장하는 activeJobId를 가져요.

순서는 sequence로 판단해요

릴리스의 순서는 전부 sequence로 결정해요.
sequence는 앱 범위에서 단조 증가하는 정수라서, 어느 릴리스가 더 최신인지 항상 명확하게 비교돼요.

version은 사람이 읽기 위한 표시용 라벨이에요.
Deplite는 version 문자열을 semver로 파싱하거나 비교하지 않아요.
그래서 표시 라벨을 자유롭게 붙여도 배포 순서에는 영향을 주지 않아요.

롤아웃 모델 — 채널 최신 자동

각 기기는 자기 채널을 구독하고, 그 채널의 최신 published 릴리스로 항상 수렴해요.

desired = 채널에서 sequence가 가장 큰 published 릴리스

새 릴리스를 게시하면 해당 채널을 구독하는 기기들의 desired가 갱신되고, 온라인이 되는 순간부터 그쪽으로 따라와요.

강제성은 2단계예요

업데이트의 급함 정도는 릴리스의 updatePolicy로 표현해요.

정책의미기기 동작
mandatory브레이킹 체인지. 최소 버전 마커이보다 낮은 기기는 강제 업데이트 (defer 불가)
optional기능 개선최신으로 수렴하되 여유 있을 때 미룰 수 있음

강제 여부는 채널의 최소 버전 마커를 기준으로 판단해요.

minSequence = 채널에서 published + mandatory 중 sequence 최대 forced = currentSequence == null || currentSequence < minSequence

강제 여부의 판단은 Deplite 서버가 하고, 강제의 집행(앱 차단 등)은 Agent가 해요.
서버는 “이 기기는 지금 반드시 올라와야 한다”라고 알려주고, 실제로 어떻게 막을지는 워크플로우와 Agent가 정해요.

기기 동기화 — pull이 진실

기기는 부팅하거나 서버에 연결될 때 desired 릴리스를 조회해요.
SSE 연결 중 새 릴리스가 게시되면 서버가 push 알림으로 기기를 깨우고, 기기가 desired를 다시 조회해요.
원하는 상태는 서버의 릴리스와 채널 설정으로 결정돼요.

안전망 폴링으로도 원하는 상태를 확인해요.
최소 폴링 간격은 Free 플랜 60분, Pro 플랜 15분이에요.
더 짧은 간격으로 조회하면 429와 Retry-After 헤더가 반환되고, 응답 본문에는 pollIntervalSeconds와 retryAfterSeconds가 포함돼요.
실제 다음 조회 간격은 heartbeat 또는 desired 응답의 pollIntervalSeconds를 따라주세요.

아티팩트 규칙

릴리스에 쓰는 아티팩트는 반드시 cleanupRule='persistent'로 업로드해야 해요.
그래야 릴리스 생성이 통과하고, 스토리지 정리 작업이 그 파일을 회수하지 않아요.

참조 중인 아티팩트는 삭제가 막혀 있어요.
draft나 published 릴리스가 가리키는 파일을 지우려고 하면 409로 차단돼요.
지워야 한다면 먼저 릴리스를 yank한 다음 파일을 삭제해주세요.

아티팩트를 임시(정리 대상) 규칙으로 업로드하면 릴리스 생성이 통과하지 못해요.
App Deploy용 파일은 항상 persistent로 올려주세요.

앱에 공개키가 등록돼 있으면 서명 없는 파일 릴리스는 게시할 수 없어요.
기기는 SHA-256 체크섬을 확인하고, 앱에 포함한 공개키로 파일 서명을 검증해주세요.
서버 응답의 artifact_public_key는 신뢰 기점이 아니에요.
앱 공개키와 서버가 내려준 공개키가 다르면 serverKeyMismatch로 확인할 수 있어요.
서버 Agent의 공개키 배치와 검증 모드는 아티팩트 검증에서 확인해주세요.

운영 노트

Android의 versionCode는 이전 값보다 낮게 설치할 수 없어요.
이전 빌드로 롤백하려면 해당 빌드를 더 높은 versionCode로 다시 빌드해 새 릴리스로 게시해주세요.

Agent가 수렴하는 방식

기기는 서명된 desired 상태를 조회해 현재 릴리스와 희망 릴리스를 비교해요.
부팅·연결 시 desired를 조회하고, SSE 연결 중 push 알림을 받으면 다시 조회해요.
서버의 공개키는 desired 응답 서명 검증에 사용되고, 배포 파일은 SHA-256과 앱에 포함한 공개키로 서명을 확인해요.
서버가 내려주는 artifact_public_key는 파일 서명의 신뢰 기점이 아니며 앱의 공개키와 다르면 serverKeyMismatch로 나타나요.

Android SDK의 heartbeat health에는 상태 정보를 함께 보낼 수 있어요.
최대 32개 키, JSON 직렬화 기준 4KB 이하만 저장돼요.
키는 ^[A-Za-z0-9_.-]{1,64}$에 맞아야 하고 값은 문자열·유한 숫자·불리언이어야 해요.
제한을 넘는 health는 저장하지 않지만 heartbeat 응답은 HTTP 200이며 healthRejected에 이유가 담겨요.

자세한 요청·응답 형식과 엔드포인트는 엔드포인트 문서를 참고해주세요.

관련 문서

최종 수정 일자: