셀프 호스팅을 위한 프로덕션 준비 앱 인수인계 체크리스트

실제로 ‘프로덕션 준비 인수인계’가 의미하는 것

프로덕션 준비 인수인계는 운영팀이 추측하지 않고 앱을 운영할 수 있다는 뜻입니다. 알려진 버전을 배포할 수 있고, 상태를 확인할 수 있으며, 경고에 대응하고, 잘못된 릴리스나 중단에서 복구할 수 있어야 합니다. 이 중 어느 하나라도 특정 개발자의 기억에 의존한다면 인수인계가 완료된 것이 아닙니다.

인수인계를 하나의 패키지로 간주하세요. 질문 하나에 답해야 합니다: 원래 만든 사람들이 일주일 동안 사라져도 운영팀이 시스템을 안전하고 가동 상태로 유지할 수 있는가?

튼튼한 패키지는 보통 앱이 무엇을 하는지, ‘정상’이 어떤 모습인지, 릴리스가 어떻게 작동하는지(배포, 검증, 롤백), 구성은 어디에 있는지, 비밀은 어떻게 처리되는지, 모니터링·백업·사건 대응 방법을 포함합니다.

동시에 인수인계가 포함하지 않는 것도 분명히 하세요. 인수인계는 기능 추가, 리팩터, 화면 재설계, 또는 ‘나중에 정리’하겠다는 약속이 아닙니다. 그런 작업들은 별도의 프로젝트이며 각자 범위가 있습니다.

완료라고 호출하기 전에 소유권과 응답 시간을 합의하세요. 예: 운영팀은 가동 시간을 책임지고 배포를 수행한다; 제품팀은 로드맵 변경을 책임진다; 개발팀은 인수인계 후 일정 기간의 지원(버그 수정과 질문 응대)을 제공한다.

간단한 시스템 인벤토리 만들기 (무엇이 어디서 실행되는가)

운영팀은 볼 수 있는 것만 소유할 수 있습니다. 한 페이지 분량의 단순 인벤토리는 배포, 사고 대응, 감사 시 추측을 막습니다. 평이한 영어(또는 팀의 공용 언어)로 구체적으로 작성하세요.

시스템의 모든 실행 구성 요소와 위치를 나열하세요: 백엔드 API, 웹 앱, 백그라운드 워커, 예약 작업, 모바일 앱이 어떻게 연결되는지 등. iOS/Android가 스토어를 통해 배포되더라도 동일한 백엔드에 의존합니다.

앱이 의존하는 외부 서비스도 포함하세요. PostgreSQL, 큐, 오브젝트 스토리지, 또는 서드파티 API(결제(예: Stripe), 메시징, 이메일/SMS, Telegram 등)를 사용한다면 정확한 서비스 이름과 용도를 적어 두세요.

호스팅이 시행착오로 변하지 않게 네트워크 요구사항도 캡처하세요: 필요한 도메인(app, api, admin), 포트와 프로토콜, TLS 인증서 갱신 담당자, DNS 관리 위치, 인바운드/아웃바운드 허용 목록 등.

마지막으로 실제 수치로 예상 부하를 적으세요: 분당 최대 요청 수, 활성 사용자 수, 일반적인 페이로드 크기, 현재 데이터베이스 크기, 예상 성장률. 대략적인 범위도 운영팀이 한계와 경고를 설정하는 데 도움이 됩니다.

AppMaster로 빌드했다면 생성된 백엔드, 웹 앱, 통합 항목을 인벤토리에 포함해 어떤 것들이 함께 배포되어야 하는지 운영팀이 알 수 있게 하세요.

환경 구성 패키징(비밀은 노출하지 않기)

프로덕션 설정은 지루한 부분에서 실패하는 경우가 많습니다: 구성값이 누군가의 머릿속에만 남아 있는 경우입니다. 구성을 전달 가능한 산출물로 취급하세요. 운영팀은 어떤 설정이 있는지, 환경별 차이가 무엇인지, 안전하게 변경하는 방법을 볼 수 있어야 합니다.

오늘 존재하는 모든 환경을 이름으로 적는 것부터 시작하세요. 임시라고 생각되는 환경도 기록하세요. 대부분의 팀은 dev, staging, production과 같은 환경과 “production-eu”나 “staging-us”같은 복사본을 가집니다. 릴리스 테스트, 데이터 마이그레이션, 사고 연습에 어떤 환경을 쓰는지도 적으세요.

환경 변수 이름과 안전한 예시 값(실제 자격증명 아님)을 나열한 단일 구성 참조를 제공하세요. 플레이스홀더는 분명히 표시합니다.

인수인계 패키지에 포함할 항목 예:

• 환경 목록과 각 환경의 용도
• 구성 키(환경 변수나 구성 파일 키)의 참조, 기대 타입, 비밀이 아닌 예시 값
• 환경 간 알려진 차이점(기능 플래그, 속도 제한, 캐시 크기, 이메일 모드, 로깅 레벨)
• 기본값과 키가 없을 때의 동작
• 구성이 저장되는 위치와 배포 중 어떻게 적용되는지

간단한 변경 절차도 추가하세요. 예: 티켓으로 요청 → 서비스 소유자가 검토 → 먼저 스테이징에 적용 → 정해진 창에 프로덕션으로 승격(문제가 생기면 롤백 계획 실행).

AppMaster 앱을 내보내어 셀프 호스팅하는 경우에도 같은 규칙을 지키세요: 생성된 소스와 함께 정리된, 문서화된 구성 키 집합을 배송해 운영팀이 환경별로 일관되게 실행할 수 있도록 합니다.

비밀과 자격증명: 저장, 회전, 접근

비밀은 깔끔한 인수인계를 보안 사고로 바꾸는 가장 빠른 방법입니다. 목표는 단순합니다: 운영팀이 앱이 필요로 하는 모든 비밀, 저장 위치, 누가 읽을 수 있는지, 다운타임 없이 어떻게 변경하는지를 알아야 합니다.

운영팀이 1분 안에 훑어볼 수 있는 짧은 비밀 목록부터 시작하세요. 각 항목에 대해 무엇을 열어주는지(데이터베이스, SMTP, Stripe, JWT 서명키 등), 어디에 저장되는지(vault, 클라우드 시크릿 스토어, Kubernetes Secret, 암호화된 파일 등), 누가 회전 권한을 갖는지 적으세요.

회전 절차는 정책처럼 포괄적으로 적지 말고 요리법처럼 단계별로 적으세요. 정확한 순서, 오래된 비밀이 얼마 동안 유효해야 하는지, 그리고 작동을 증명하는 한 가지 검증 단계를 포함하세요.

회전 체크리스트(예시)

각 비밀에 대해 이 패턴을 사용하세요:

• 새로운 비밀 값을 생성하고 승인된 시크릿 관리자에 저장합니다.
• 앱이 새 값을 사용하도록 구성 변경을 배포합니다.
• 검증: 로그인, 결제, API 호출이 정상적으로 동작하고 오류율이 평상시와 같음을 확인합니다.
• 이전 비밀을 폐기하고 더 이상 작동하지 않는지 확인합니다.
• 회전 날짜, 수행자, 다음 회전 예정일을 기록합니다.

암호화 기대사항도 명확히 하세요. 비밀은 시크릿 스토어에서 저장 시 암호화되어야 하고, 앱과 의존성 사이 전송 중에는 TLS로 보호되어야 합니다. 비밀을 소스 코드, 빌드 아티팩트, 공유 문서에 절대 넣지 마세요.

비상 접근(브레이크 글래스)을 정의하세요. 정상 접근이 차단된 경우 누가 승인할 수 있는지, 얼마나 오픈되는지, 이후에 어떤 감사를 해야 하는지 명시합니다.

배포 패키지: 아티팩트, 버전, 롤백

운영팀은 재현할 수 있는 것만 소유할 수 있습니다. 좋은 배포 패키지는 세 가지 질문에 답하기 쉽도록 만듭니다: 정확히 무엇을 실행 중인가, 어떻게 다시 배포하나, 문제가 생기면 어떻게 빨리 되돌리나?

빌드의 "자재 명세서(bill of materials)"를 포함하세요. 단지 위치만이 아니라 아티팩트를 어떻게 확인하는지도 적습니다:

• 아티팩트 상세: 컨테이너 이미지 이름/태그(또는 바이너리/패키지 이름), 앱 버전, 빌드 날짜, 체크섬
• 소스 참조: 빌드에 사용한 릴리스 태그나 커밋 해시, 중요한 빌드 플래그
• 지원 대상: VM, 컨테이너(Docker), Kubernetes 등과 권장 기본 대상
• 배포 단계: 전제 조건(런타임, 데이터베이스, 스토리지), 정확한 순서, 일반적인 배포 시간
• 데이터베이스 마이그레이션: 자동 실행 여부 또는 수동 실행 방식, 로그 위치, 성공 확인 방법

작고 구체적인 예시를 하나 추가하세요. 예: “v1.8.2를 배포하려면 이미지 태그를 업데이트하고 마이그레이션을 실행한 뒤 웹 워커를 재시작합니다. 헬스체크가 10분 내에 실패하면 v1.8.1로 되돌리고 마이그레이션 작업을 중지합니다.”

추측 없는 롤백

롤백 계획은 새벽 2시에 따라 할 수 있는 지침처럼 읽혀야 합니다. 다음을 명시하세요:

• 롤백을 촉발하는 신호(오류율, 실패한 헬스체크, 로그인 실패 등)
• 마지막으로 알려진 정상 버전과 저장 위치
• 데이터베이스 변경이 되돌릴 수 있는지 여부와 되돌릴 수 없을 때의 대응 방법

AppMaster로 구축되어 소스 코드로 내보낸 앱이라면 생성된 코드 버전, 빌드 지침, 런타임 기대사항을 포함해 운영팀이 나중에 동일한 릴리스를 재빌드할 수 있게 하세요.

모니터링과 알림: 무엇을 측정하고 언제 호출할지

인수인계는 운영팀이 앱의 상태를 볼 수 있고 사용자가 불평하기 전에 경고를 받을 때만 완성됩니다.

어떤 로그가 필요하고 어디로 가는지(파일, syslog, 로그 플랫폼)를 합의하세요. 로그는 시간 동기화되어야 하고 요청 또는 상관 ID를 포함해 사고를 종단 간 추적할 수 있게 해야 합니다.

일반적으로 필요할 로그: 애플리케이션 로그(주요 이벤트와 실패), 오류 로그(스택 트레이스와 실패한 작업), 액세스 로그(요청과 상태 코드), 감사 로그(관리자 행동과 데이터 추출), 인프라 로그(재시작, 노드 압력, 디스크 문제) 등입니다.

다음으로 사용자 영향과 시스템 상태를 반영하는 소수의 메트릭을 정의하세요. 다섯 가지만 고른다면: 지연(p95/p99), 오류율, 포화도(CPU/메모리/디스크), 큐 깊이, 외부에서의 가용성 체크입니다.

알림 규칙은 명확해야 합니다: 무엇이 트리거인지, 심각도(호출 대 티켓), 누가 온콜인지, 언제 에스컬레이션하는지. “정상”의 대시보드 스냅샷과 짧은 설명(일반적인 지연 범위, 기대 오류율, 보통의 큐 깊이)을 추가하세요. 그 맥락이 시끄러운 알람을 줄이고 새로운 대응자가 빠르게 행동하는 데 도움이 됩니다.

백업과 복구: 복원이 반복 가능하도록 만들기

백업은 "가져두는 것"이 아니라 "요청 시 복구할 수 있는 것"입니다.

정확한 범위를 적으세요: 데이터베이스, 파일 스토리지(업로드, 리포트, 인보이스), 코드에 없는 구성과 암호화된 데이터를 읽는 데 필요한 키 같은 사람들이 자주 잊는 항목들.

목표는 평이한 용어로 유지하세요. RPO는 얼마나 많은 데이터를 잃을 수 있는지(예: 15분), RTO는 얼마나 오래 다운되어도 되는지(예: 1시간)입니다. 비즈니스와 합의한 숫자를 선택하세요. 이는 비용과 노력을 좌우합니다.

포함할 항목:

• 무엇을 백업하는지, 어디에 저장하는지, 보존 기간
• 누가 백업과 복원을 실행할 수 있는지, 접근 승인 방법
• 단계별 복원 절차와 검증 체크
• 복원 로그가 어디에 있고 “성공”이 무엇인지
• 흔한 실패 모드(잘못된 키, 누락된 버킷, 스키마 불일치)와 해결법

AppMaster로 빌드해 내보낸 앱이라면 PostgreSQL 복원 절차와 외부 스토리지 버킷, 암호화된 필드에 사용되는 키도 포함하세요.

복원 연습을 일정에 넣으세요. 수행 시간, 고장 원인, 변경한 내용을 기록해 다음 번 복원은 더 빠르고 덜 스트레스받게 하세요.

런북과 온콜: 운영팀이 실제 사건을 처리하는 방법

인수인계는 실제로 누군가가 새벽 2시에 호출을 받아 추측 없이 문제를 해결할 수 있을 때 비로소 완성됩니다. 런북은 부족한 지식을 단계로 바꿉니다.

먼저 예상되는 사건부터 시작하세요: 전체 장애, 느려짐, 배포로 인한 문제. 각 런북은 짧게 유지하세요. 빠른 점검을 상단에 두면 응답자는 몇 분 내에 신호를 얻을 수 있습니다.

좋은 런북의 구성

일관된 구조로 만들어 압박 속에서도 스캔하기 쉽도록 하세요:

• 사용자가 보는 증상과 이를 확인하는 방법(예: 오류율 X% 초과, 결제 실패)
• 첫 번째 점검(서비스 상태, 최근 배포, 종속 서비스 상태, 디스크/CPU, DB 연결)
• 다음 점검(열어볼 로그, 핵심 대시보드, 최근 구성 변경, 큐 깊이)
• 결정 포인트(언제 롤백할지, 언제 스케일링할지, 언제 기능을 끌지)
• 에스컬레이션(앱 담당자, 인프라 담당자, 각자 언제 호출할지)

앱이 AppMaster에서 내보내져 셀프 호스팅되었다면 생성된 서비스가 어디에서 실행되는지, 안전하게 재시작하는 방법, 환경별로 기대되는 구성값도 포함하세요.

사건 이후: 올바른 사실을 기록하기

사건 후 간단한 체크리스트를 유지하세요. 타임라인, 마지막에 변경된 항목, 정확한 오류 메시지, 영향을 받은 사용자, 문제를 해결한 조치를 기록하세요. 그런 다음 세부사항이 생생할 때 런북을 업데이트하세요.

접근 제어와 권한: 누가 무엇을 할 수 있는가

운영팀이 시스템을 소유하려면 누가 무엇을 건드릴 수 있는지, 그리고 접근이 어떻게 추적되는지가 명확해야 합니다.

실제로 사용하는 역할을 적으세요. 많은 팀에 충분한 예는 다음과 같습니다:

• 배포자(Deployer): 승인된 버전을 배포하고 롤백을 트리거할 수 있음
• DB 관리자(DB admin): 스키마 변경과 백업 복원 수행
• 읽기 전용(Read-only): 대시보드, 로그, 구성을 보기만 가능
• 사건 지휘관(Incident commander): 장애 시 긴급 조치 승인

"문 여는 정책(door policy)"을 평이한 단계로 문서화하세요: 누가 접근을 부여하는지, 어디에 부여되는지(SSO, 클라우드 IAM, DB 사용자, CI/CD, 관리자 패널), 누가 철회하는지, 오프보딩 시 제거 확인 방법.

비인간 접근도 잊지 마세요. 잡, 통합, 모니터링이 사용하는 모든 서비스 계정과 토큰을 나열하고 각 계정의 최소 권한을 적으세요(예: “버킷 X에서만 읽기 가능”). AppMaster 소스 코드를 내보내어 셀프 호스팅하는 경우 이러한 신원(identity)이 어떤 환경 변수나 구성 파일로 정의되는지 포함하되 비밀 값은 절대 붙여넣지 마세요.

감사 로그 기대사항도 설정하세요: 무엇을 로그로 남겨야 하는지(로그인, 배포, 구성 변경, DB 관리자 행동), 누가 로그를 읽을 수 있는지, 보존 기간, 로그가 어디에 저장되는지, 사건이나 검토 시 로그를 요청하는 방법.

보안 및 컴플라이언스 기초(평이한 영어)

보안 내용은 비전문가도 읽을 수 있게 하되 운영팀이 행동할 수 있을 정도로 구체적이어야 합니다. 한 페이지 요약으로 답하세요: 어떤 데이터를 저장하는가, 어디에 저장되는가, 누가 접근 가능한가?

먼저 데이터 유형을 적으세요: 고객 프로필, 지원 티켓, 결제 메타데이터, 파일 등. 민감한 범주(PII: 이름, 이메일, 전화번호), 자격증명, 회사가 신경 쓰는 규제 데이터도 명시하세요. AppMaster에서 내보낸 소스 코드를 셀프 호스팅하는 경우 해당 데이터가 데이터베이스의 어디에 저장되는지와 어떤 서비스가 이를 읽을 수 있는지도 적으세요.

그다음 보존 및 삭제 규칙을 실무적으로 작성하세요. 무엇을 얼마 동안 보관하는지, 삭제는 어떻게 작동하는지(소프트 삭제 vs 하드 삭제, 지연 삭제), 법적 보류나 감사 필요가 있으면 예외를 누가 승인하는지 적습니다.

로그는 종종 데이터베이스보다 더 많은 정보를 유출합니다. PII가 나타날 수 있는 위치(액세스 로그, 오류 로그, 분석 이벤트)를 명확히 하고 이를 줄이거나 마스킹하는 방법을 적으세요. 어떤 필드는 절대 로그에 남기면 안 된다고 규칙을 적으세요.

승인 절차를 명확히 하세요:

• 인증 관련 변경은 명시된 승인자가 필요합니다.
• 결제 관련 변경(Stripe 키, 웹훅 엔드포인트, 환불 로직)은 명시된 승인자가 필요합니다.
• 역할 및 권한 모델 변경은 명시된 승인자가 필요합니다.
• 보안 패치 창 및 긴급 변경 규칙을 문서화하세요.

하나만 더 추가할 수 있다면 감사 증거가 어디에 있고 누군가 증거를 요구할 때 어떻게 추출하는지 메모를 남기세요.

예시 인수인계 시나리오: 운영팀이 1주일 내 인수

작은 제품팀이 만든 고객 포털을 운영팀이 인수해 자체 호스팅 인프라로 옮깁니다. 목표는 단순히 “앱이 실행된다”가 아니라 "운영팀이 빌더에게 연락하지 않고도 운영할 수 있다"입니다.

일주일의 모습

Day 1: 운영팀은 인수인계 패키지만으로 새 환경에 처음으로 배포를 시도합니다. 앱은 올라오지만 로그인 실패가 발생합니다. 이메일 제공자를 위한 환경 변수가 빠져 있었던 것입니다. 그 항목을 env 템플릿에 추가하고, 처음부터 작동할 때까지 배포를 반복합니다.

Day 2: 의도적으로 첫 알림을 발생시킵니다. 운영팀은 통제된 실패(서비스 하나 중지 또는 아웃바운드 이메일 차단)를 트리거하고 확인합니다: 메트릭이 문제를 보여주고 알림이 올바른 채널로 도달하며 메시지가 다음 조치를 지시합니다.

Day 3: 결제 샌드박스에서 토큰이 만료됩니다. 자격증명 위치와 회전 절차가 문서화되어 있어 운영팀은 추측 없이 교체를 완료합니다.

Day 4: DNS 전환 작업. 잘못된 레코드가 이전 IP를 가리켜 일부 사용자에게 포털이 다운된 것처럼 보입니다. 운영팀은 런북을 따라 DNS, TLS, 헬스체크를 올바른 순서로 점검합니다.

Day 5: 첫 백업 복원 테스트. 운영팀은 새 데이터베이스로 복원해 실제 데이터를 로드할 수 있음을 증명합니다.

1주일 후 ‘완료’의 모습

앱은 7일 동안 미스터리한 수정 없이 실행되었고, 한 번의 성공적인 복원, 명확한 알림, 운영팀이 단독으로 수행할 수 있는 반복 가능한 배포 절차가 확보되었습니다.

셀프 호스팅 인수인계에서 자주 하는 실수들

차분한 인수인계를 새벽 2시의 화재로 바꾸는 가장 빠른 방법은 “우리가 운영팀에게 모든 걸 알려줬다”를 “운영팀이 우리 없이 운영할 수 있다”와 동일하게 보는 것입니다.

셀프 호스팅 인수인계 후 자주 보이는 실패 패턴: 스프레드시트나 채팅에 공유된 비밀, 롤백이 개발자에게 의존하는 경우, 백업은 존재하지만 복원은 테스트하지 않은 경우, 임계값이 조정되지 않아 하루 종일 울리는 알림, 누군가의 머릿속에만 있는 환경 세부사항(포트, DNS 이름, 크론 스케줄, 클라우드 권한) 등이 있습니다.

예: AppMaster에서 소스 코드를 내보내 셀프 호스팅했는데 첫 배포는 성공했습니다. 그러나 2주 후 구성 변경으로 로그인이 깨졌습니다. 비밀이 채팅으로 공유되었고 롤백에 원래 빌더가 필요하다면 운영팀은 ‘어제 작동하던 상태’로 돌아가는데 몇 시간을 허비하게 됩니다.

“인수인계 완료”라고 말하기 전 빠른 점검

티켓을 닫기 전에 짧은 새로 시작 드릴을 실행하세요. 한 명의 운영 엔지니어와 새 환경(새 VM, 새 Kubernetes 네임스페이스, 빈 클라우드 프로젝트)을 주고 인수인계 패키지를 넘깁니다. 그 사람이 패키지로 배포·관찰·복구를 정해진 시간(예: 2시간) 안에 할 수 있다면 거의 준비된 것입니다.

다음 점검을 사용하세요:

• 패키지된 아티팩트, 구성 문서, 런북만으로 처음부터 재빌드 및 배포(롤백 포함)
• 모든 비밀이 합의된 장소에 있는지 확인하고, 회전 절차가 작성되어 테스트되었는지 검증
• 대시보드를 열어 기본 질문에 답하는지 확인: 업 여부, 느린지, 오류 발생 중인지, 자원 부족인지
• 안전한 테스트 경고 하나를 트리거해 페이징 경로, 담당자, 조용한 시간 동작 확인
• 별도 환경에 실제 복원 테스트를 수행하고 정확한 단계와 예상 결과 문서화

생성된 소스 코드를 셀프 호스팅용으로 내보낸 경우 운영팀이 빌드 입력, 버전, 릴리스 태그를 어디에 기록하는지 확인해 향후 릴리스가 재현 가능하도록 하세요.

다음 단계: 소유권 확정 및 패키지 최신 상태 유지

페이저를 받을 사람들과 최종 워크스루를 진행하세요. 리허설처럼 다루세요. 동일한 패키지로 배포, 롤백, 복원, 알림이 모두 작동함을 증명하세요.

최종 워크스루는 보통 다음을 포함합니다: 테스트 환경과 프로덕션에 동일한 단계로 배포, 이전 버전으로 롤백해 앱이 여전히 작동하는지 검증, 깨끗한 환경에 백업에서 복원하고 간단한 실검사(로그인, 레코드 생성, 메시지 전송) 검증, 안전한 테스트 알림 트리거, 사건 시 로그와 대시보드를 어디서 찾을지 확인.

소유권을 명확히 하세요. 각 런북(배포, 사건, 복원)과 각 알림 경로(기본 온콜, 백업, 근무 외 동작)에 대해 이름이 지정된 소유자를 할당하세요. 알림을 아무도 소유하지 않으면 무시되거나 잘못된 사람이 깨게 됩니다.

첫 주 이후 운영팀이 개선할 항목을 알려주는 간단한 Day 2 계획을 작성하세요: 임계값 튜닝, 비용 확인, 오래된 아티팩트 정리, 접근 권한 검토 등. 작고 기한을 정해 실행하세요.

AppMaster(appmaster.io)로 빌드했다면 내보낸 소스 코드 또는 정확한 배포 대상 세부정보(클라우드, 리전, 빌드 설정, 필요한 서비스)를 포함해 운영팀이 원래 프로젝트 워크스페이스에 의존하지 않고 앱을 재현할 수 있게 하세요. 요구사항이 변경될 때마다 패키지를 업데이트하는 간단한 주기를 설정해 런북이 현실에서 벗어나지 않도록 유지하세요.